Skip to main content

API

The GALAKTIKA system provides a REST API for integrating external systems — applications, dispatch platforms, billing systems, and other services that require programmatic access to monitoring data: objects, geozones, drivers, events, reports, and movement history.

This section is intended for developers building an integration with the system. It describes the general principles of working with the API and contains a list of methods with their purpose. Request and response schemas are provided in the interactive Swagger documentation, which ships with the API and is available at /api/docs on the API server — for example, nav.gpspos.ru/api/docs.

Getting started​

  1. Obtain from your company administrator or from the provider of GALAKTIKA monitoring services a login and password for a user with API access, together with the API server address. The examples in this section use nav.gpspos.ru; your company's address may differ. Enabling API access in the interface is described in API tools.
  2. Obtain an access token — see Authentication.
  3. Perform the first requests using the examples on the Quick start page.
  4. Locate the required method in API methods and check its schema in the Swagger UI (/api/docs).

Other pages of this section: API methods — the list of available methods; Errors and status codes — the error format and HTTP status codes.

What is available through the API​

  • users;
  • commands and command templates;
  • companies;
  • drivers and driver groups;
  • driver keys and key groups;
  • driver penalties;
  • driver shifts;
  • events and event settings;
  • geozones and geozone groups;
  • objects and object groups;
  • current object state — positions, sensor values, attached keys;
  • object history — tracks, daily statistics, driver shifts;
  • reports and report templates;
  • files received from devices — photos and videos;
  • geocoder.

The methods corresponding to each of these entities are listed on the API methods page.

General principles​

  • Base path — in a standard installation, where the web interface and the API share one domain, methods are located under /api/ relative to the server address, e.g. https://nav.gpspos.ru/api/Objects; Swagger is under /api/docs. The /api/ prefix is applied by the reverse proxy: when the API is deployed on a separate host or port, the methods are served from the root (/Objects). The base address is confirmed with the administrator.
  • Authentication — a JWT token obtained with the user's login and password. The token is passed in the Authorization: Bearer <token> header and is valid for 30 minutes — see Authentication.
  • Access rights — API methods return data within the same access rights as the web interface: only the objects, geozones, and data permitted to the user are available (see Access rights). A separate API account with extended rights is not provided; the set of rights is defined in the control panel.
  • Error format — on error, the API returns JSON of the form { "Status": "FAIL", "ErrorMessage": "..." } (in some cases with an additional Args field listing error arguments) and the corresponding HTTP status code. See Errors and status codes.
  • Rate limiting — by default no more than 20 requests per 60 seconds per client (sliding window). The value is defined in the server settings and may differ in a particular installation. See Rate limiting.
  • Data model — the entities and fields returned by the API correspond to the concepts described in the other sections of this documentation; the terms are listed in the Glossary.

Conventions​

  • Time format — in all fields related to positions, tracks, history, and report intervals (Time, ServerTime, From, Till, etc.), time is passed as the number of milliseconds elapsed since January 1, 1970, 00:00:00 UTC (Unix time in milliseconds), both in requests and in responses. Individual fields holding an entity's creation date (e.g. CreateDate) are returned as an ISO 8601 string; the type of a particular field is specified in the Swagger UI.
  • Time zone — time is transmitted in UTC. In the web interface the same value is displayed in the time zone configured for the user.
  • Field naming — fields in request and response bodies are capitalised (ObjectId, AccessToken, ErrorMessage), as specified in the Swagger UI.
  • Request body — POST and PUT methods accept JSON and require the Content-Type: application/json header. File upload is the exception and uses multipart/form-data.
  • Identifiers — the Id of objects, geozones, drivers, and other entities is unique within a single installation and is not transferable between servers. For objects, lookup by IMEI is provided.
  • Paging — list methods return the entire list available to the user in a single response; paging parameters are not supported.

Limits​

  • History depth per request — one month maximum.
  • Request rate — 20 requests per 60 seconds by default, see Rate limiting.
  • Token lifetime — 30 minutes; a token renewal method is not provided, see Token lifetime.