Using the Web Connector REST API
Using the Web Connector REST API, real-time services from Esri Tracking Server can be consumed in JSON or CSV format. This allows you to integrate your real-time data from Tracking Server into almost any web environment.
For convenience, this documentation can be accessed directly from the Web Connector using the following URL: http://[Web Connector URL Prefix]/rest.
Below is a listing of the REST endpoints available from the Web Connector:
- Service Definitions
- Service Definition
- Message Definitions
- Message Definition
- Observations
- Latest Observations
- Latest Observation
- Publish Data Message
- Gateway Statistics
Service Definitions
URL: http://[Web Connector URL Prefix]/rest/ServiceDefinitions
Description
The ServiceDefinitions operation returns a complete list of service definitions available from the Web Connector, in the format specified.
Parameters
Parameter | Details |
|---|---|
f | Description: The response format. The default response format is json. Values: json | xml |
Caution:If the response format is xml (the default response format), you must ensure that the IIS application pool or user account has access to the Windows temp directory. For example, the Windows temp directory is commonly found in C:\Windows\Temp.
Example
http://localhost/TrackingServer/WebConnector/rest/ServiceDefinitions?f=xml
Service Definition
URL: http://[Web Connector URL Prefix]/rest/ServiceDefinition
Description
The ServiceDefinition operation returns a single service definition, specified by service name, in the format specified.
Parameters
Parameter | Details |
|---|---|
service | Required Description: The name of the service. |
f | Description: The response format. The default response format is json. Values: json | xml |
Caution:If the response format is xml (the default response format), you must ensure that the IIS application pool or user account has access to the Windows temp directory. For example, the Windows temp directory is commonly found in C:\Windows\Temp.
Example
http://localhost/TrackingServer/WebConnector/rest/ServiceDefinition?servicename=cars&f=json
Message Definitions
URL: http://[Web Connector URL Prefix]/rest/MessageDefinitions
Description
The MessageDefinitions operation returns a complete list of message definitions available from the Web Connector, in the format specified.
Parameters
Parameter | Details |
|---|---|
f | Description: The response format. The default response format is json. Values: json | xml |
Caution:If the response format is xml (the default response format), you must ensure that the IIS application pool or user account has access to the Windows temp directory. For example, the Windows temp directory is commonly found in C:\Windows\Temp.
Example
http://localhost/TrackingServer/WebConnector/rest/MessageDefinitions?f=xml
Message Definition
URL: http://[Web Connector URL Prefix]/rest/MessageDefinition
Description
The MessageDefinition operation returns a single message definition, specified by the GUID of the message definition, in the format specified.
Parameters
Parameter | Details |
|---|---|
guid | Required Description: The GUID of the message definition.The GUID of the message definition used by a specific service can be found in the response from the ServiceDefinition operation for that service. |
f | Description: The response format. The default response format is json. Values: json | xml |
Caution:If the response format is xml (the default response format), you must ensure that the IIS application pool or user account has access to the Windows temp directory. For example, the Windows temp directory is commonly found in C:\Windows\Temp.
Example
http://localhost/TrackingServer/WebConnector/rest/MessageDefinition?guid={98139940-6CD7-11D5-B7EF-00010265ADC5}&f=xml
Observations
URL: http://[Web Connector URL Prefix]/rest/Observations
Description
The Observations operation is used to retrieve all the observations for a service. In order to avoid missing or duplicate observations, each Observations operation returns a bookmark keeping track of which observations have already been sent to the client. Each subsequent call to Observations should use the bookmark from the previous call.
Parameters
Parameter | Details |
|---|---|
service | Required Description: The name of the service. |
bookmark | Description: A bookmark returned with each call to Observations. The bookmark is used to avoid missing or duplicate observations on subsequent calls. bookmark=init should be used on the first call to Observations, and the bookmark returned from the previous call should be used on all subsequent calls. If no bookmark is specified, bookmark=init is used. Values: init |
f | Description: The response format. The default response format is json. Values: json | csv |
xMin | Description: The minimum X coordinate value of observations to be returned. This is an optional parameter that should only be used if you want to restrict the observations to a bounding box. |
xMax | Description: The maximum X coordinate value of observations to be returned. This is an optional parameter that should only be used if you want to restrict the observations to a bounding box. |
yMin | Description: The minimum Y coordinate value of observations to be returned. This is an optional parameter that should only be used if you want to restrict the observations to a bounding box. |
yMax | Description: The maximum Y coordinate value of observations to be returned. This is an optional parameter that should only be used if you want to restrict the observations to a bounding box. |
Example
The first time the Observations operation is used, the following format should be used:
http://localhost/TrackingServer/WebConnector/rest/Observations?service=cars&bookmark=init&f=json
A bookmark is returned from the first operation. In this example, the bookmark returned is 2011-12-29T13:34:52.1375219-08:00. This bookmark should be used in the next call to Observations, as shown here:
http://localhost/TrackingServer/WebConnector/rest/Observations?service=cars&bookmark=2011-12-29T13:34:52.1375219-08:00&f=json
For all subsequent calls to Observations, the bookmark from the previous call should be used, as shown above.
Latest Observations
URL: http://[Web Connector URL Prefix]/rest/LatestObservations
Description
The LatestObservations operation is used to retrieve only the latest observation for each unique track in a service, within a time period specified. Each call to LatestObservations returns a new and complete set of latest observations. There is no built-in mechanism for avoiding duplicate or missing observations.
Parameters
Parameter | Details |
|---|---|
service | Required Description: The name of the service. |
lastSeconds | Description: The period of time for which to return the latest observations for each unique track in the service. For example, if lastSeconds=30 is used, then only observations received by Web Connector within the last 30 seconds will be returned. Only the latest observation for each unique track in the service will be returned. If this parameter is not specified, then the latest observations will be returned for all tracks present in the Web Connector cache. |
f | Description: The response format. The default response format is json. Values: json | csv |
xMin | Description: The minimum X coordinate value of observations to be returned. This is an optional parameter that should only be used if you want to restrict the observations to a bounding box. |
xMax | Description: The maximum X coordinate value of observations to be returned. This is an optional parameter that should only be used if you want to restrict the observations to a bounding box. |
yMin | Description: The minimum Y coordinate value of observations to be returned. This is an optional parameter that should only be used if you want to restrict the observations to a bounding box. |
yMax | Description: The maximum Y coordinate value of observations to be returned. This is an optional parameter that should only be used if you want to restrict the observations to a bounding box. |
Example
http://localhost/TrackingServer/WebConnector/rest/LatestObservations?service=cars&lastSeconds=30&f=csv
Latest Observation
URL: http://[Web Connector URL Prefix]/rest/LatestObservation
Description
The LatestObservation operation is used to retrieve the latest observation for a specific, unique track in a service.
Parameters
Parameter | Details |
|---|---|
service | Required Description: The name of the service. |
trackId | Required Description: The unique Track ID value used to identify the track whose latest observation will be returned. |
f | Description: The response format. The default response format is json. Values: json | csv |
Example
http://localhost/TrackingServer/WebConnector/rest/LatestObservations?service=cars&lastSeconds=30&f=csv
Publish Data Message
URL: http://[Web Connector URL Prefix]/rest/PublishDataMessage
Description
The PublishDataMessage operation allows you to publish data messages to Tracking Server in a CSV format through the Generic Input Data Link. The operation can be used with both the HTTP GET and POST request methods. When using the GET request method, the data message is included as a parameter. When using the POST request method, the data message must be inlcuded in the message body.
Parameters
Parameter | Details |
|---|---|
data | Description: The data message being published to Tracking Server. The data message must match the CSV format expected by the Tracking Server Generic Input Data Link. |
Example
http://localhost/TrackingServer/WebConnector/rest/PublishDataMessage?data=Taxis,"-160.0,43.0,0.0",Taxi 1,-160,43,2,1/10/2012 6:00 PM
Gateway Statistics
URL: http://[Web Connector URL Prefix]/rest/GatewayStatistics
Description
The GatewayStatistics operation allows you to retrieve diagnostic statistics from the Tracking Gateway. These statistics can be used to monitor the data flow through your Tracking Server. They can also be used to verify that your Tracking Server is running properly, as well as help to identify and diagnose problems when they occur.
The diagnostic information returned from this operation falls into three categories:
- Connection Properties: Properties related to Gateway connectivity.
- Process Properties: Properties related to the java process running in the Tracking Gateway.
- Service Properties: Properties describing the available tracking services, including message counts and time since last message.
Parameters
Parameter | Details |
|---|---|
f | Description: The response format. The default response format is json. Values: json | xml |
Example
http://localhost/TrackingServer/WebConnector/rest/GatewayStatistics