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

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

CautionCaution:

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

CautionCaution:

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

CautionCaution:

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

CautionCaution:

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

LegacyLegacy:

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.

URL: http://[Web Connector URL Prefix]/rest/GenerateKmlService

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

LegacyLegacy:

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.

URL: http://[Web Connector URL Prefix]/rest/Generate3DKmlService

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.

CautionCaution:

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

8/28/2015