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
- GenerateKmlService (as of version 10.1 SP1)
- Generate3DKmlService (as of version 10.1 SP1)
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 |
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 |
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 |
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 |
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
GenerateKmlService
It is not recommended to access this REST endpoint directly unless a version of Web Connector from Tracking Server 10.1 Service Pack 1 or later is deployed. If a previous version of Web Connector is deployed, this endpoint will not behave as documented here.
Description
The GenerateKmlService operation allows you to generate a KML service from a tracking service using customized settings. The Web Connector KML services web page contains several links which invoke the GenerateKmlService operation using default settings. You should only invoke this operation directly if you need to use customized settings, such as a customized style file or customized refresh rate.
Learn how to consume KML services from the Web Connector using default settings
Parameters
Parameter | Details |
---|---|
service | Required Description: The name of the tracking service to generate the KML service from. |
description | Description: The description that appears for the Track List of the KML service in the KML viewing application, such as ArcGIS Explorer. |
styleFilename | Description: The name of the style file (residing in [Web Connector Location]\WebConnector\kml\styles) to be used with the KML service. |
symbolId | Description: The name of the style id in the specified style file to be used with the KML service. Alternatively, you can specify the name of a field in your real-time data to create a unique value renderer based on attributes in your data, as shown in the example below. When a feature has a data value in the chosen field that matches the name of a style id contained in the specified style file, the corresponding style is used for the feature. |
altitudeMode | Description: The altitude mode to be used in the KML service. Values: absolute | clampToGround | clampToSeaFloor | relativeToGround | relativeToSeaFloor |
showTrack | Description: This setting determines whether track lines are shown in the KML service. Values: true | false |
refreshInterval | Description: The refresh interval to be used (in seconds) by the KML service. This refresh updates the positions and track lines for all tracks in the KML service. It also updates the Track List for the KML service in the KML viewing application, such as ArcGIS Explorer. |
updateRefreshInterval | Description: The update refresh interval to be used (in seconds) by the KML service. This refresh only updates the positions and track lines for tracks that currently apear in the KML viewing application, such as ArcGIS Explorer. New tracks that have been added to the KML service since the previous refresh will not appear in the KML viewing application until the next refresh interval has elapsed. |
Example
http://localhost/TrackingServer/WebConnector/rest/GenerateKmlService?service=Taxis&description=Esri Tracking Server Web Connector KML Service&styleFilename=mystyle&symbolId=Field1&altitudeMode=absolute&showTrack=true&refreshInterval=10&updateRefreshInterval=2
Generate3DKmlService
It is not recommended to access this REST endpoint directly unless a version of Web Connector from Tracking Server 10.1 Service Pack 1 or later is deployed. If a previous version of Web Connector is deployed, this endpoint will not behave as documented here.
Description
The Generate3DKmlService operation allows you to generate a 3D KML service from a tracking service using customized settings.
Parameters
Parameter | Details |
---|---|
service | Required Description: The name of the tracking service to generate the 3D KML service from. |
description | Description: The description that appears for the Track List of the 3D KML service in the KML viewing application, such as ArcGIS Explorer. |
styleFilename | Description: The name of the style file (residing in [Web Connector Location]\WebConnector\kml\styles) to be used with the 3D KML service. |
modelHost | Description: The URL specifying the location of 3D models to be used with the 3D KML service. It is recommended to store your 3D models locally in [Web Connector Location]\WebConnector\kml\kml\3Dmodels\models. If you follow this recommendation, you must copy your 3D models to this location and specify http://[Computer Name]/TrackingServer/WebConnector/kml/3Dmodels/models for this parameter. |
modelId | Description: The name of the 3D model file (.dae format) in the specified model host location to be used with the KML service. Alternatively, you can specify the name of a field in your real-time data to create a unique value renderer based on attributes in your data, as shown in the example below. When a feature has a data value in the chosen field that matches the name of a style id contained in the specified style file, the corresponding style is used for the feature. If you want to use a 3D model from the model host location, the file name of the model must also match the style id and the data value. |
modelScale | Description: The model scale defines a scale factor to be used for 3D models in the 3D KML service. |
altitudeMode | Description: The altitude mode to be used in the 3D KML service. Values: absolute | clampToGround | clampToSeaFloor | relativeToGround | relativeToSeaFloor |
showTrack | Description: This setting determines whether track lines are shown in the 3D KML service. Values: true | false |
refreshInterval | Description: The refresh interval to be used (in seconds) by the 3D KML service. This refresh updates the positions and track lines for all tracks in the 3D KML service. It also updates the Track List for the 3D KML service in the KML viewing application, such as ArcGIS Explorer. |
updateRefreshInterval | Description: The update refresh interval to be used (in seconds) by the 3D KML service. This refresh only updates the positions and track lines for tracks that currently apear in the KML viewing application, such as ArcGIS Explorer. New tracks that have been added to the 3D KML service since the previous refresh will not appear in the KML viewing application until the next refresh interval has elapsed. |
If you are configuring Web Connector to use 3D models stored locally on the file system, you will need to set the web folder where the 3D models are stored to support the appropriate MIME type (model/x3d+binary) for the .dae file extension in IIS Manager, as shown below.
Example
http://localhost/TrackingServer/WebConnector/Rest/Generate3DKmlService?service=Taxis&description=Esri Tracking Server Web Connector 3D KML Service&modelHost=http://localhost/TrackingServer/WebConnector/kml/3Dmodels/models&modelId=Field1&modelScale=2&altitudeMode=absolute&showTrack=true&refreshInterval=10&updateRefreshInterval=2&styleFilename=myStylekml