IBM IoT for Automotive : Vehicle Data Hub

Preview

IBM IoT for Automotive : Vehicle Data Hub

+ Day(s) remaining in the trial

Overview

The IoT for Automotive service API provides automotive domain specialized application development enablers for data acquisition, storage, real-time processing, and business rules support. IoT for Automotive provides APIs to fetch vehicle location, movement, vehicle health, and analytic insights. You can also use the APIs to retrieve and manage large volumes of automotive data, including map context and driver behavior data.
Use the following API documentation to help you to develop your IoT for Automotive service to suit your requirements:

Getting started

Authentication

To authenticate to the IoT for Automotive API, submit the user name and the password for the service instance that you would like to use. The API supports HTTP basic authentication. To see the user credentials of the IoT for Automotive instance that you created on Bluemix, go to the dashboard and click Manage. **NOTE:** The Username and Password credentials for the IoT for Automotive service instance are not the same as your Bluemix account user name and password.

Security

Keys

Pick a key to use with this API. Make sure you are logged in with your IBM id for your keys to be populated in the dropdown below. By selecting a key, it will be pre-filled for each endpoint in the Documentation section that can be used with the built-in testing. If you want to change which key to use for a particular endpoint, you can do so at the endpoint in the Documentation section.
You can manage your API keys in the <MyAPIs> section. API keys authenticate you to your subscription, so make sure to keep them secret. Do not share the X-IBM-Client-Secret portion of any API key in publicly accessible places such as GitHub, or client-side code.



Manage your keys
 

Documentation

IBM IoT for Automotive : Vehicle Data Hub:

CarProbe

Get Car Probe

GetCarProbe obtains a list of CarProbe data of vehicles that are satisfied with a given condition. For each vehicles, CarProbe data which is received last time is obtained.

  1. The rectangle condition is mandatory, CarProbe data of vehicles in the rectangle are obtained.
  2. Other conditions are optional, the list of CarProbe data is narrow down to satisfy with conditions specified.

For example,

  • If the 'link_id' is specified, the list is narrow down to obtain only CarProbe of vehicles that are on the link and in the rectangle.
  • If the 'mo_id' is specified, the list is narrow down to obtain only CarProbe of vehicle that has the id and in the rectangle.
  • If both 'link_id' and 'mo_id' are specified, the list is narrow down to obtain only CarProbe of vehicle that is on the link and has the id and in the rectangle.

A CarProbe of a vehicle will be evicted automatically if no CarProbe of the vehicle is received within a certain period of time from the time when the last CarProbe was received. The expiration time is configurable, however, it is fixed to one minute in Bluemix IoT for Automotive service.

GetCarProbe is implemented to get CarProbe data of vehicles that are in a small area of a map, for example, 10 km square. Even if the number of vehicles is not many, response time will be very long in the case that a condition specifies very wide area of a map.

GET   /carProbe

			https://[Tenant_Unique_Sub_Domain].automotive.internetofthings.ibmcloud.com/carProbe
		
Keys
Path and Query parameters

confidence

DOUBLE , optional

Position confidence.

invalid_match_result

DOUBLE , optional

A value of -1 indicates that the map that is matched with this map vendor or version is invalid.

last_modified

STRING , optional

Last modified time stamp.

link_id

STRING , optional

Link ID in the Context Mapping service.

max_altitude

DOUBLE , optional

Upper altitude limit.

max_latitude

DOUBLE , required

Upper latitude limit.

max_longitude

DOUBLE , required

Upper longitude limit.

min_altitude

DOUBLE , optional

Lower altitude limit.

min_latitude

DOUBLE , required

Lower latitude limit.

min_longitude

DOUBLE , required

Lower longitude limit.

mo_id

STRING , optional

Moving object ID.

speed_over

DOUBLE , optional

Speed lower limit (km/h) 0.1 km/h unit.

speed_under

DOUBLE , optional

Speed upper limit (km/h) 0.1 km/h unit.

tenant_id

STRING , required

Tenant ID.

vehicle_model

STRING , optional

Vehicle model.

vehicle_status

DOUBLE , optional

A vehicle status of 1 is normal, and 0 is the initial value.

vehicle_type

STRING , optional

Vehicle type.

Request code
								
HttpResponse<String> response = Unirest.get("https:///[Tenant_Unique_Sub_Domain].automotive.internetofthings.ibmcloud.com/carProbe?tenant_id=SOME_STRING_VALUE&mo_id=SOME_STRING_VALUE&vehicle_type=SOME_STRING_VALUE&vehicle_model=SOME_STRING_VALUE&invalid_match_result=SOME_NUMBER_VALUE&confidence=SOME_NUMBER_VALUE&speed_over=SOME_NUMBER_VALUE&speed_under=SOME_NUMBER_VALUE&link_id=SOME_STRING_VALUE&vehicle_status=SOME_NUMBER_VALUE&last_modified=SOME_STRING_VALUE&min_longitude=SOME_NUMBER_VALUE&min_latitude=SOME_NUMBER_VALUE&min_altitude=SOME_NUMBER_VALUE&max_longitude=SOME_NUMBER_VALUE&max_latitude=SOME_NUMBER_VALUE&max_altitude=SOME_NUMBER_VALUE") .header("authorization", "Basic REPLACE_BASIC_AUTH") .asString();
Response model

200

Successful operation.

Body

contents

ARRAY , required

400

The tenant ID that was provided is invalid.

Body

401

Authorization Failed.

Body

Response example

200

Successful operation.

								{
  "contents" : [array]
}
							

400

The tenant ID that was provided is invalid.

								
							

401

Authorization Failed.

								
							
Send car probe
Sends car probe data, and also returns list of events that might affect the moving object, for example, a vehicle.

POST   /carProbe

			https://[Tenant_Unique_Sub_Domain].automotive.internetofthings.ibmcloud.com/carProbe
		
Keys
Path and Query parameters

op

STRING , optional

If 'sync' is specified, the API response is returned after the process is finished. If 'async' is specified, the API response is returned immediately. ('async' if not specified)

tenant_id

STRING , required

Tenant ID.

Request code
								
HttpResponse<String> response = Unirest.post("https:///[Tenant_Unique_Sub_Domain].automotive.internetofthings.ibmcloud.com/carProbe?tenant_id=SOME_STRING_VALUE&op=SOME_STRING_VALUE") .header("authorization", "Basic REPLACE_BASIC_AUTH") .asString();
Request model

timestamp

STRING , optional

Time stamp of the event in ISO 8601 time format (yyyy-mm-ddThh:MM:ss[.fff]Z).

trip_id

STRING , required

Trip ID.

speed

DOUBLE , required

Speed in km/h, 1 km/h unit.

altitude

DOUBLE , optional

Altitude.

mo_id

STRING , required

Moving object ID.

longitude

DOUBLE , required

Longitude.

driver_id

STRING , optional

Driver ID.

confidence

DOUBLE , optional

Position confidence.

latitude

DOUBLE , required

Latitude.

heading

DOUBLE , required

The angle of moving direction, whereby North is 0, and the value increases in a clockwise direction.

props

OBJECT , optional

ex. {'props':{'key1':'value1',...,'keyN':'valueN'}

Request example
{
  "timestamp": string,
  "trip_id": string,
  "speed": double,
  "altitude": double,
  "mo_id": string,
  "longitude": double,
  "driver_id": string,
  "confidence": double,
  "latitude": double,
  "heading": double,
  "props": object
}
Response model

200

Successful operation.

Body

contents

ARRAY , required

400

The tenant ID is invalid, Map Matching failed with the input position, Driver ID is invalid. (When anonymous driver is disabled and such driver doesn't exist), Vehicle ID is invalid. (When anonymous vehicle is disabled and such vehicle doesn't exist)

Body

401

Authorization Failed.

Body

Response example

200

Successful operation.

								{
  "contents" : [array]
}
							

400

The tenant ID is invalid, Map Matching failed with the input position, Driver ID is invalid. (When anonymous driver is disabled and such driver doesn't exist), Vehicle ID is invalid. (When anonymous vehicle is disabled and such vehicle doesn't exist)

								
							

401

Authorization Failed.

								
							
Send list of car probe
Sends a list of car probe data and also returns list of events that could affect the moving objects, for example, a vehicle.

POST   /carProbeList

			https://[Tenant_Unique_Sub_Domain].automotive.internetofthings.ibmcloud.com/carProbeList
		
Keys
Path and Query parameters

op

STRING , optional

If 'sync' is specified, the API response is returned after the process is finished. The default value is 'async', which means that the response is returned immediately.

tenant_id

STRING , required

Tenant ID.

Request code
								
HttpResponse<String> response = Unirest.post("https:///[Tenant_Unique_Sub_Domain].automotive.internetofthings.ibmcloud.com/carProbeList?tenant_id=SOME_STRING_VALUE&op=SOME_STRING_VALUE") .header("authorization", "Basic REPLACE_BASIC_AUTH") .asString();
Request model

SentCarProbe

object , optional

timestamp

STRING , optional

Time stamp of the event in ISO 8601 time format (yyyy-mm-ddThh:MM:ss[.fff]Z).

trip_id

STRING , required

Trip ID.

speed

DOUBLE , required

Speed in km/h, 1 km/h unit.

altitude

DOUBLE , optional

Altitude.

mo_id

STRING , required

Moving object ID.

longitude

DOUBLE , required

Longitude.

driver_id

STRING , optional

Driver ID.

confidence

DOUBLE , optional

Position confidence.

latitude

DOUBLE , required

Latitude.

heading

DOUBLE , required

The angle of moving direction, whereby North is 0, and the value increases in a clockwise direction.

props

OBJECT , optional

ex. {'props':{'key1':'value1',...,'keyN':'valueN'}

Request example
[{
  "SentCarProbe": {
    "timestamp": string,
    "trip_id": string,
    "speed": double,
    "altitude": double,
    "mo_id": string,
    "longitude": double,
    "driver_id": string,
    "confidence": double,
    "latitude": double,
    "heading": double,
    "props": object
  }
}]
Response model

200

Successful operation.

Body

contents

ARRAY , required

400

The tenant ID is invalid, Map Matching failed with the input position, Driver ID is invalid. (When anonymous driver is disabled and such driver doesn't exist), Vehicle ID is invalid. (When anonymous vehicle is disabled and such vehicle doesn't exist)

Body

401

Authorization Failed.

Body

Response example

200

Successful operation.

								{
  "contents" : [array]
}
							

400

The tenant ID is invalid, Map Matching failed with the input position, Driver ID is invalid. (When anonymous driver is disabled and such driver doesn't exist), Vehicle ID is invalid. (When anonymous vehicle is disabled and such vehicle doesn't exist)

								
							

401

Authorization Failed.

								
							

Loading content...