Conventions v3.0

Base URL: https://xcglobe.com
All request and response bodies use UTF-8.
Coordinates use decimal degrees in the WGS 84 coordinate system.
Altitudes are meters above mean sea level (MSL).
Timestamps are UTC Unix timestamps in whole seconds.

1. Authentication

Request body:

{
  "username": "pilot",
  "password": "secret",
  "clientId": "flymemini1.0"
}

Fields:

username - XcGlobe username or account email address.
password - XcGlobe account password.
clientId - client name and version; it should remain stable for one application release.

Successful response (200 OK):

{
  "token": "9ab3cdef",
  "user": {
    "id": "937",
    "name": "Pilot Name"
  }
}

token is an opaque bearer token. user.id is returned as a JSON string. user.name is omitted when no pilot name is available.

Invalid credentials (401 Unauthorized):

{
  "error": "INVALID_CREDENTIALS",
  "message": "Invalid username or password."
}

2. Upload live tracking points

The request body contains one or more consecutive four-field point tuples:

There are no spaces, line breaks, or semicolon separators. Multiple tuples are concatenated directly. The final trailing comma is accepted and is the recommended canonical format; it may be omitted.

One point:

Three points:

Point fields:

latitude - WGS 84 latitude in degrees, -90 to 90; negative values indicate south.
longitude - WGS 84 longitude in degrees, -180 to 180; negative values indicate west.
altitudeMeters - MSL altitude in whole meters; use 0 when no altitude is available.
timestampSeconds - positive UTC Unix timestamp in seconds.

Points must be ordered by increasing timestamp. The first point in a later request must be at least one second newer than the last accepted point in the session. A gap longer than three hours starts a new stored track. Clients should serialize requests for a session and keep batches reasonably small. A maximum batch size of 32 KiB is recommended for mobile clients.

Successful response (200 OK):

{
  "status": "success",
  "streamId": "9ab3cdef"
}

streamId identifies the live tracking session and currently has the same value as the bearer token. Treat it as opaque and do not depend on that equality.

3. Error responses

Empty body (400 Bad Request):

{
  "error": "LIVE_TRACK_REQUIRED",
  "message": "Live track point is required."
}

Invalid point data, tuple structure, or time interval (400 Bad Request):

{
  "error": "LIVE_TRACK_INVALID",
  "message": "Live track point format is invalid."
}

Missing or invalid bearer token (401 Unauthorized):

{
  "error": "UNAUTHORIZED",
  "message": "Bearer token is required."
}

Unexpected server failure (500 Internal Server Error):

{
  "error": "INTERNAL_ERROR",
  "message": "Internal server error."
}

Error responses contain a stable, machine-readable error code and a human-readable message. Clients should make decisions from the HTTP status and error value, not by matching message text.

4. Retry behaviour

Accept a batch only after 200 OK with status equal to success. Do not retry a 400 response unchanged. After a 401 response, obtain a new token and retry the batch once. Retry connection failures, rate-limit responses, malformed responses, and 5xx responses with bounded exponential backoff. Keep requests serialized and preserve point order.

5. Legacy API v2 compatibility

The legacy GET /livetrack/login and GET /livetrack/save endpoints remain available for existing integrations. New integrations must use API v3.0. Legacy authentication values are not interchangeable with API v3.0 bearer tokens.

Live tracking API v3.0, 2026-08-07

Legacy API v1

Plase use API v3.0 instead

1. Login request (http GET)

At first, you initiate a login request with XCglobe login parameters and glider type code. You'll get back user_id and session_id values, for all further calls.

glider_type codes:

1 - paraglider
2 - HG flex wing
3 - HG rigid wing
4 - sailplane
5 - PPG foot launched (pilot has motor on his back)
6 - PPG wheel launched (motor is fixed on trike)
9 - other

Response (two lines of text, both values are integers):

Example:

u=937
h=4356533

In the case of an error, response will start with error:, followed by code.

Example:

error:2

Error codes:

1 - wrong input parameters
2 - login error (invalid username or password)
3 - server application internal error
4 - invalid session_id
5 - logging time interval too short (for preventing server overload)

2. Live tracking request (http GET)

Parameters:

user_id, session_id - parameters acquired from a login request
latitude - the latitude in decimal notation, use negative numbers for west
longitude - the latitude in decimal notation, use negative numbers for south
altitude - MSL altitude in meters
radius - radius in km, for retrieving positions of nearby gliders.

Example:

http://xcglobe.com/livetrack/save?uid=213&h=64404596&lat=46.23445&lng=13.97235&alt=968&r=10

Response:

The first line indicates status of the response (ok: or error:). Error codes are the same as for the Login request (see above). Following lines simply list the nearby gliders, if there are any. Response is UTF-8 encoded. Speed is in km/h, flight duration is in seconds, timestamp is UTC Unix time.

Example of the response:

Live tracking API v2.0, 2017-01-05