1. Request Body
    1. Additional details about values
    2. Special timestamps
    3. Continuation lines
  2. Request Headers
  3. Example

GTS Input Format

Warp 10™ can be fed data via the Ingress endpoint.

The Ingress endpoint has an HTTP or HTTPS URL of the form http://host:port/api/vX/update where X is the version of the API being used.

This endpoint MUST be called using the HTTP POST method.

Request Body

The body of the call contains the readings which should be pushed into the platform, one per line.

Each line has the following format:

TS/LAT:LON/ELEV NAME{LABELS} VALUE

where each element has the following syntax and meaning:

ParameterDescription
TSTimestamp of the reading, in the configured time units since the Unix Epoch.
If omitted, the time of the data ingestion will be used as the time of each reading
LAT:LONOptional geographic coordinates of the reading, using WGS84
ELEVOptional elevation of the reading, in millimeters
NAMEClass name of the reading as a URL encoded UTF-8 character string.
The encoding of character { (Unicode LEFT CURLY BRACKET, 0x007B) is MANDATORY.
LABELSComma separated list of labels, using the syntax key=value where both key and value are URL encoded UTF-8 character strings.
If a key or value contains , (Unicode COMMA, 0x002C), } (Unicode RIGHT CURLY BRACKET, 0x007D) or = (Unicode EQUALS SIGN, 0x003D), those characters MUST be encoded.
VALUEThe value of the reading. It can be of one of four types: LONG, DOUBLE, BOOLEAN, STRING

Additional details about values

A LONG value is represented as a sequence of digits optionally prefixed with a '+' or '-' sign. The values that can be represented span from -2^63 to 2^63-1.

1234567890

A DOUBLE value is represented as a sequence of digits, a mandatory decimal separator ('.'), and a mandatory sequence of digits following the separator. Scientific notation can also be used. The values that can be represented are those representable in the 64 bits IEEE754 double precision floating point format.

3.14159265359

A BOOLEAN value is represented as either T (for true) or F (for false).

T

Lastly, a STRING value is represented as a URL encoded UTF-8 character string enclosed in single quotes.

'caf%C3%A9'

Special timestamps

There are cases in IoT where an absolute timestamp is not available but devices can only create relative timestamps from their startup date.

Such cases can be handled by Warp 10™ by using a special syntax for the TS element of the input format to specify relative timestamps. This syntax is T+xxx or T-xxx where xxx is the delta from the base now timestamp in time units.

The now timestamp is assumed to be the time of the request unless the X-Warp10-Now request header was used. This header can specify a value for now, either as an absolute timestamp expressed in time units or as a time units delta (prefixed by either + or -) from the current timestamp. The special value * can also be used to retrieve the current timestamp each time a timestamp is needed.

Relative timestamps are correctly handled by the datalog replication mechanism.

Continuation lines

When pushing multiple datapoints for the same Geo Time Series™, the first line can have the syntax described above (TS/LAT:LON/ELEV CLASS{LABELS} VALUE), but the following can use the more compact syntax =TS/LAT:LON/ELEV VALUE which will also speed up ingestion as the class and labels will not be parsed for each value.

Request Headers

The Warp 10™ ingress token MUST be passed as the value of the X-Warp10-Token HTTP header.

If the request body is compressed, the Content-Type header MUST be set to the value application/gzip.

Example

POST /api/v0/update HTTP/1.1
Host: host
X-Warp10-Token: TOKEN
Content-Type: text/plain

1380475081000000// foo{label0=val0,label1=val1} 123
/48.0:-4.5/ bar{label0=val0} 3.14
1380475081123456/45.0:-0.01/10000000 foobar{label1=val1} T