Usage
Connection modes#
The connection to the streaming endpoint will result in an HTTP persistent connection, or a standard HTTP request that will end the connection after having finished the data requested when using batch mode.
Streaming mode#
The server will keep sending messages until the connection terminates. The client can reconnect and resume consuming the messages from the last known position token. The position token is sent in short intervals as part of the Target Updates stream.
Note that while a single HTTP connection in streaming mode may persist for long periods without termination, code to support automatic reconnection using the last known position token is highly recommended for customer usage in production.
Streaming mode - Recent History#
If live target updates are not essential for your use case, then streaming mode can also be used with a four hour delay. This otherwise behaves exactly the same and will work with the API request shared above. Please speak to the Spire team if this might be of interest.
Batch mode#
In batch mode, the server will only send the target updates between the desired dates and then stop the connection.
To activate Batch mode, you simply need to use the query parameters start and end in your query parameters.
Query Parameters#
The following parameters can be specified to filter the stream on the server-side or to reduce the bandwidth requirements. Since these are query parameters the total number of filters that can be specified is limited by the maximum URL length. All query parameters are optional, if not specified then all the data is sent to the stream.
| Query Parameters | Type | Description |
|---|---|---|
position_token | string | BEGINNING to start from oldest still available target updateLATEST (default) to start from last available target update token to resume the stream from a certain position, the invocation must return a token that was previously sent and is not older than 6 hours |
icao_address | string | Comma separated list of ICAO addresses (6 hex characters) |
tail_number | string | Comma separated list of tail numbers |
flight_number | string | Comma separated list of flight numbers |
callsign | string | Comma separated list of callsigns |
airline | string | Comma separated list of airline IATA codes |
latitude_between | float,float | Two numbers, separated by a comma. First value must be smaller than the second; specifies south-to-north range. First value is inclusive, last value is exclusive |
longitude_between | float,float | Two numbers, separated by a comma. Specifies west-to-east range. E.g. range [170, -170) is a 20° range crossing anti-meridian, and [-170, 170) is a 340° range covering most of the globe. First value is inclusive, last value is exclusive |
altitude_between | integer,integer | Altitude in ft, two integers separated by a comma. First value is inclusive, last value is exclusive |
max_age | integer | This filters out delayed data. If an aircraft timestamp is older than n milliseconds, the target update will not be returned |
compression | string | Compression of the data.gzip (default) GZip compressionnone to disable compression |
info
Adding those parameters will automatically enable batch mode.
| Query Parameters | Type | Description |
|---|---|---|
start | datetime | Batch mode data extraction starting date, format is in ISO 8601 |
end | datetime | Batch mode data extraction ending date, format is in ISO 8601 |