IBM Watson IoT Context Mapping

Live

IBM Watson IoT Context Mapping

+ Day(s) remaining in the trial

Overview

IBM Watson IoT Context Mapping API provides features that you can use to enable your applications to use geospatial map matching and shortest path search. Use the Context Mapping REST API to connect your applications the service, through the HTTP protocol. You will need your tenant ID and your API key credentials, which you can obtain from the Context Mapping administration console.

Getting started

Authentication

To authenticate to the Context Mapping 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 obtain the user credentials of the Context Mapping instance that you created on Bluemix, go to the dashboard and click Manage. **NOTE:** The Username and Password credentials for the Context Mapping 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 Watson IoT Context Mapping:

Event

Create event
Injects a new event into the Context Mapping service.

POST   /eventservice/event

			https://automotive.internetofthings.ibmcloud.com/mapinsights/eventservice/event
		
Keys
Path and Query parameters

tenant_id

STRING , required

Tenant ID used for authentication.

Request code
								
HttpResponse<String> response = Unirest.post("https://api.ibm.com/mapinsights/eventservice/event?tenant_id=SOME_STRING_VALUE") .header("accept", "application/json") .header("content-type", "application/json") .asString();
Request model

timestamp

STRING , optional

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

event_category

STRING , optional

User-defined category of the event.

s_latitude

DOUBLE , required

Latitude of the start point, which is specified in the WGS84 coordinate system.

s_longitude

DOUBLE , required

Longitude of the start point, which is specified in the WGS84 coordinate system.

status

DOUBLE , optional

User-defined status of the event.

end_time

STRING , optional

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

event_type

STRING , required

User-defined type of the event.

start_time

STRING , optional

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

event_name

STRING , optional

User-defined name of the event.

originator

STRING , optional

Source of the event.

heading

DOUBLE , optional

Heading of the event in degrees, where North is 0, and the value increases as the angle moves in a clockwise direction.

Request example
 
Response model

200

Successful operation.

Body

number

DOUBLE , optional

Event ID that was assigned to this event.

400

Invalid input.

Body

401

Authentication failed.

Body

Response example

200

Successful operation.

								{
  "number" : double
}
							

400

Invalid input.

								
							

401

Authentication failed.

								
							
Delete event
Deletes the requested event information that is stored in the Context Mapping service.

DELETE   /eventservice/events

			https://automotive.internetofthings.ibmcloud.com/mapinsights/eventservice/events
		
Keys
Path and Query parameters

event_id

STRING , required

ID of the Event to delete.

tenant_id

STRING , required

Tenant ID used for authentication.

Request code
								
HttpResponse<String> response = Unirest.delete("https://api.ibm.com/mapinsights/eventservice/events?tenant_id=SOME_STRING_VALUE&event_id=SOME_STRING_VALUE") .header("accept", "application/json") .header("content-type", "application/json") .asString();
Response model

200

Successful operation.

Body

number

DOUBLE , optional

The number of deleted events.

400

Invalid input.

Body

401

Authentication failed.

Body

Response example

200

Successful operation.

								{
  "number" : double
}
							

400

Invalid input.

								
							

401

Authentication failed.

								
							
Get all events
Returns all of the event information that is stored in the Context Mapping service. Pagination is supported when you use the num_rec_in_page and num_page parameters.

GET   /eventservice/event/allevents

			https://automotive.internetofthings.ibmcloud.com/mapinsights/eventservice/event/allevents
		
Keys
Path and Query parameters

num_page

DOUBLE , optional

The total number of pages for all of the events.

num_rec_in_page

DOUBLE , optional

The number of events to store on one page.

tenant_id

STRING , required

Tenant ID used for authentication.

Request code
								
HttpResponse<String> response = Unirest.get("https://api.ibm.com/mapinsights/eventservice/event/allevents?num_page=SOME_NUMBER_VALUE&num_rec_in_page=SOME_NUMBER_VALUE&tenant_id=SOME_STRING_VALUE") .header("accept", "application/json") .header("content-type", "application/json") .asString();
Response model

200

Successful operation.

Body

num_page

DOUBLE , required

events [Event]

ARRAY , required

num_rec_in_page

DOUBLE , required

event_count

DOUBLE , required

event_category

STRING , required

Event category of the specified event.

status

STRING , required

User-defined event status.

event_type

STRING , required

User-defined event type name.

region_id

STRING , required

ID of the region where the specified event exists.

event_id

STRING , required

ID of the event.

link_id

STRING , required

ID of the link where this event exists.

s_latitude

DOUBLE , required

Latitude of the event's starting point, which is specified in the WGS84 coordinate system.

distance

DOUBLE , required

Distance in meters from the start point on the map matched link.

map_id

DOUBLE , required

ID of the map where the specified event exists.

s_longitude

DOUBLE , required

Longitude of the event's starting point, which is specified in the WGS84 coordinate system.

end_time

STRING , required

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

start_time

STRING , required

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

event_time

STRING , required

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

event_name

STRING , required

User-defined event name.

originator

STRING , required

Name of the event source.

heading

DOUBLE , required

Heading of the map matched point for the event in degrees, where North is 0, and the value increases as the angle moves in a clockwise direction.

400

Invalid input.

Body

401

Authentication failed.

Body

Response example

200

Successful operation.

								{
  "num_page" : double,
  "events" : [{
    "event_category" : string,
    "status" : string,
    "event_type" : string,
    "region_id" : string,
    "event_id" : string,
    "link_id" : string,
    "s_latitude" : double,
    "distance" : double,
    "map_id" : double,
    "s_longitude" : double,
    "end_time" : string,
    "start_time" : string,
    "event_time" : string,
    "event_name" : string,
    "originator" : string,
    "heading" : double
  }],
  "num_rec_in_page" : double,
  "event_count" : double
}
							

400

Invalid input.

								
							

401

Authentication failed.

								
							
Get event by event ID
Returns the requested event information that is stored in the Context Mapping service.

GET   /eventservice/event

			https://automotive.internetofthings.ibmcloud.com/mapinsights/eventservice/event
		
Keys
Path and Query parameters

event_id

STRING , required

ID of the Event to retrieve.

tenant_id

STRING , required

Tenant ID used for authentication.

Request code
								
HttpResponse<String> response = Unirest.get("https://api.ibm.com/mapinsights/eventservice/event?tenant_id=SOME_STRING_VALUE&event_id=SOME_STRING_VALUE") .header("accept", "application/json") .header("content-type", "application/json") .asString();
Response model

200

Successful operation.

Body

event_category

STRING , required

Event category of the specified event.

status

STRING , required

User-defined event status.

event_type

STRING , required

User-defined event type name.

region_id

STRING , required

ID of the region where the specified event exists.

event_id

STRING , required

ID of the event.

link_id

STRING , required

ID of the link where this event exists.

s_latitude

DOUBLE , required

Latitude of the event's starting point, which is specified in the WGS84 coordinate system.

distance

DOUBLE , required

Distance in meters from the start point on the map matched link.

map_id

DOUBLE , required

ID of the map where the specified event exists.

s_longitude

DOUBLE , required

Longitude of the event's starting point, which is specified in the WGS84 coordinate system.

end_time

STRING , required

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

start_time

STRING , required

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

event_time

STRING , required

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

event_name

STRING , required

User-defined event name.

originator

STRING , required

Name of the event source.

heading

DOUBLE , required

Heading of the map matched point for the event in degrees, where North is 0, and the value increases as the angle moves in a clockwise direction.

400

Invalid input.

Body

401

Authentication failed.

Body

Response example

200

Successful operation.

								{
  "event_category" : string,
  "status" : string,
  "event_type" : string,
  "region_id" : string,
  "event_id" : string,
  "link_id" : string,
  "s_latitude" : double,
  "distance" : double,
  "map_id" : double,
  "s_longitude" : double,
  "end_time" : string,
  "start_time" : string,
  "event_time" : string,
  "event_name" : string,
  "originator" : string,
  "heading" : double
}
							

400

Invalid input.

								
							

401

Authentication failed.

								
							
Get event count
Returns the total number of events that are stored in the Context Mapping service.

GET   /eventservice/event/count

			https://automotive.internetofthings.ibmcloud.com/mapinsights/eventservice/event/count
		
Keys
Path and Query parameters

tenant_id

STRING , required

Tenant ID used for authentication.

Request code
								
HttpResponse<String> response = Unirest.get("https://api.ibm.com/mapinsights/eventservice/event/count?tenant_id=SOME_STRING_VALUE") .header("accept", "application/json") .header("content-type", "application/json") .asString();
Response model

200

Successful operation.

Body

number

DOUBLE , optional

The number of events that are stored in the Context Mapping service.

400

Invalid input.

Body

401

Authentication failed.

Body

Response example

200

Successful operation.

								{
  "number" : double
}
							

400

Invalid input.

								
							

401

Authentication failed.

								
							
Query event
Searches and returns the requested event information by using the specified conditions.

GET   /eventservice/event/query

			https://automotive.internetofthings.ibmcloud.com/mapinsights/eventservice/event/query
		
Keys
Path and Query parameters

event_type

STRING , optional

Type of event.

max_latitude

DOUBLE , required

Maximum latitude of the area for the event query, which is specified in the WGS84 coordinate system.

max_longitude

DOUBLE , required

Maximum longitude of the area for the event query, which is specified in the WGS84 coordinate system.

min_latitude

DOUBLE , required

Minimum latitude of the area for the event query, which is specified in the WGS84 coordinate system.

min_longitude

DOUBLE , required

Minimum longitude of the area for the event query, which is specified in the WGS84 coordinate system.

status

DOUBLE , optional

User-defined status of the event.

tenant_id

STRING , required

Tenant ID used for authentication.

Request code
								
HttpResponse<String> response = Unirest.get("https://api.ibm.com/mapinsights/eventservice/event/query?status=SOME_NUMBER_VALUE&max_latitude=SOME_NUMBER_VALUE&min_longitude=SOME_NUMBER_VALUE&min_latitude=SOME_NUMBER_VALUE&tenant_id=SOME_STRING_VALUE&event_type=SOME_STRING_VALUE&max_longitude=SOME_NUMBER_VALUE") .header("accept", "application/json") .header("content-type", "application/json") .asString();
Response model

200

Successful operation.

Body

event_category

STRING , required

Event category of the specified event.

status

STRING , required

User-defined event status.

event_type

STRING , required

User-defined event type name.

region_id

STRING , required

ID of the region where the specified event exists.

event_id

STRING , required

ID of the event.

link_id

STRING , required

ID of the link where this event exists.

s_latitude

DOUBLE , required

Latitude of the event's starting point, which is specified in the WGS84 coordinate system.

distance

DOUBLE , required

Distance in meters from the start point on the map matched link.

map_id

DOUBLE , required

ID of the map where the specified event exists.

s_longitude

DOUBLE , required

Longitude of the event's starting point, which is specified in the WGS84 coordinate system.

end_time

STRING , required

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

start_time

STRING , required

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

event_time

STRING , required

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

event_name

STRING , required

User-defined event name.

originator

STRING , required

Name of the event source.

heading

DOUBLE , required

Heading of the map matched point for the event in degrees, where North is 0, and the value increases as the angle moves in a clockwise direction.

400

Invalid input.

Body

401

Authentication failed.

Body

Response example

200

Successful operation.

								{
  "event_category" : string,
  "status" : string,
  "event_type" : string,
  "region_id" : string,
  "event_id" : string,
  "link_id" : string,
  "s_latitude" : double,
  "distance" : double,
  "map_id" : double,
  "s_longitude" : double,
  "end_time" : string,
  "start_time" : string,
  "event_time" : string,
  "event_name" : string,
  "originator" : string,
  "heading" : double
}
							

400

Invalid input.

								
							

401

Authentication failed.

								
							

Loading content...