Skip to main content

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.

curl -H "Authorization: Bearer <your_token>" "https://api.airsafe.spire.com/v2/targets/stream?compression=none"

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.

curl -H "Authorization: Bearer <your_token>" "https://api.airsafe.spire.com/v2/targets/stream?start=2024-02-20T04:51:42.943Z&end=2024-02-20T05:51:42.943Z&compression=none"

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 ParametersTypeDescription
position_tokenstringBEGINNING to start from oldest still available target update
LATEST (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_addressstringComma separated list of ICAO addresses (6 hex characters)
tail_numberstringComma separated list of tail numbers
flight_numberstringComma separated list of flight numbers
callsignstringComma separated list of callsigns
airlinestringComma separated list of airline IATA codes
latitude_betweenfloat,floatTwo 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_betweenfloat,floatTwo 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_betweeninteger,integerAltitude in ft, two integers separated by a comma. First value is inclusive, last value is exclusive
max_ageintegerThis filters out delayed data. If an aircraft timestamp is older than n milliseconds, the target update will not be returned
compressionstringCompression of the data.
gzip (default) GZip compression
none to disable compression
info

Adding those parameters will automatically enable batch mode.

Query ParametersTypeDescription
startdatetimeBatch mode data extraction starting date, format is in ISO 8601
enddatetimeBatch mode data extraction ending date, format is in ISO 8601