Skip to main content

Quick start

Examples of calls to the principal API methods. All requests except obtaining a token require the Authorization: Bearer <token> header produced at the Authentication step. The server address in the examples is nav.gpspos.ru; your company's address may differ. All methods are located under /api/ relative to the server address (see base path).

The response examples show the most commonly used fields; the complete set of fields for each model is specified in the Swagger UI (nav.gpspos.ru/api/docs).

User profile​

GET /api/Profile

Returns summary data for the user.

curl https://nav.gpspos.ru/api/Profile \
  -H "Authorization: Bearer <token>"

Response structure:

{
  "Objects": [],
  "Geozones": [],
  "ObjectIcons": [],
  "ServerTime": 1750000000000
}
  • Objects — the user's objects with their sensors; the element structure matches the response of GET /api/Objects.
  • Geozones — the user's geozones.
  • ObjectIcons — the object icon catalogue.
  • ServerTime — the current server time in Unix milliseconds.

Object list​

GET /api/Objects

Returns an array of monitored objects available to the user under their access rights.

curl https://nav.gpspos.ru/api/Objects \
  -H "Authorization: Bearer <token>"

Example response element:

[
  {
    "Id": 123,
    "CompanyId": 45,
    "CompanyName": "Demo company",
    "ClusterId": 1,
    "Name": "Truck 01",
    "IMEI": "861234567890123",
    "DeviceType": "Teltonika FMB920",
    "StateNumber": "A123BC777",
    "Phone": "+70000000000",
    "IconId": 12,
    "TrackColor": "#1E90FF",
    "Status": 1,
    "Timeout": 600,
    "MaxSpeed": 90,
    "TimeZone": "Europe/Moscow",
    "CreateDate": "2025-01-15T10:00:00",
    "GroupIds": [7],
    "Sensors": [
      {
        "Id": 501,
        "Name": "Ignition",
        "Source": "din1",
        "Units": "",
        "DataType": 1,
        "OnText": "On",
        "OffText": "Off",
        "CalibrationTable": []
      }
    ]
  }
]
  • Status — the object state: 0 — blocked, 1 — active, 10 — broken, 11 — on service, 15 — not installed, 255 — deleted.
  • CreateDate — the object creation date as an ISO 8601 string; the other time fields are transmitted in Unix milliseconds.
  • Sensors — the object's sensors; Source contains the name of the device input, CalibrationTable holds the calibration table.

The GET /api/Objects/lite method returns the same list with a reduced set of fields: Id, ClusterId, Name, Comment, IMEI, Phone, Phone1, Flags, IconId, CompanyId, DeviceType, TrackColor, CreateDate, Status. Lookup by IMEI is performed with GET /api/Objects/byimei/{imei} and returns a single record in the same format.

Status of all objects​

GET /api/ObjectsStatus

Returns the current state of all available objects. For a single object — GET /api/ObjectsStatus/{id}.

curl https://nav.gpspos.ru/api/ObjectsStatus \
  -H "Authorization: Bearer <token>"

Example response:

{
  "Positions": [
    {
      "ObjectId": 123,
      "Online": true,
      "Lat": 55.751244,
      "Lng": 37.618423,
      "Alt": 156,
      "Time": 1750000000000,
      "Speed": 42,
      "heading": 275,
      "Sat": 11,
      "Accuracy": 5
    }
  ],
  "SensorValues": [
    { "SensorId": 501, "Time": 1750000000000, "Value": 1 }
  ],
  "DriverKeys": [
    { "ObjectId": 123, "Time": 1749998000000, "UId": "1A2B3C4D" }
  ],
  "Stats": [
    {
      "ObjectId": 123,
      "Day": 1749945600000,
      "Length": 184.5,
      "MoveTime": 12600,
      "ParkTime": 71400,
      "IdleTime": 1800,
      "EngineTime": 14400,
      "AvgSpeed": 53,
      "MaxSpeed": 89,
      "Fuel": 62.3
    }
  ]
}
  • Positions — the object's last position. The heading field is named heading, in lower case, unlike the other fields.
  • SensorValues — the latest sensor readings; SensorId corresponds to the Id field in the object's Sensors array.
  • DriverKeys — the last attached driver key, with UId as its identifier.
  • Stats — daily statistics: Length in kilometres, MoveTime, ParkTime, IdleTime, and EngineTime in seconds, Day — the start of the day in Unix milliseconds.

Object history​

POST /api/ObjectsHistory

Returns the track, events, files, and sensor values of an object over the specified interval. The interval must not exceed one month; if it does, 400 Bad Request is returned.

Request body:

{
  "ObjectId": 123,
  "From": 1750000000000,
  "Till": 1750086400000
}
  • ObjectId — the object identifier.
  • From, Till — the start and end of the interval in Unix milliseconds.
curl -X POST https://nav.gpspos.ru/api/ObjectsHistory \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"ObjectId":123,"From":1750000000000,"Till":1750086400000}'

Example response:

{
  "Track": {
    "Intervals": [
      {
        "From": 1750000000000,
        "Till": 1750003600000,
        "Position": { "Lat": 55.751244, "Lng": 37.618423, "Alt": 156 }
      },
      {
        "From": 1750003600000,
        "Till": 1750007200000,
        "Positions": [
          {
            "Lat": 55.751244,
            "Lng": 37.618423,
            "Alt": 156,
            "Time": 1750003600000,
            "Speed": 0,
            "heading": 275,
            "Sat": 11
          }
        ]
      }
    ]
  },
  "Events": [
    {
      "Id": 90001,
      "ObjectId": 123,
      "Time": 1750004000000,
      "Type": 2,
      "Status": 1,
      "Text": "Speeding",
      "ResetTime": 0,
      "NotificationId": 15
    }
  ],
  "Files": [
    { "ObjectId": 123, "Time": 1750004500000, "Type": "image/jpeg", "Uid": "9f1c…" }
  ],
  "Sensors": [
    {
      "SensorId": 501,
      "Intervals": [
        {
          "From": 1750000000000,
          "Till": 1750007200000,
          "Values": [ { "Time": 1750000000000, "Value": 1 } ]
        }
      ]
    }
  ],
  "Violations": {
    "SpeedViolations": [],
    "AccelerationViolations": [],
    "BrakingViolations": [],
    "TurningViolations": [],
    "AccelerometerFaulty": false
  }
}
  • Track.Intervals contains intervals of two kinds. A parking interval carries a Position field with a single point; a movement interval carries a Positions field with an array of points. There is no separate field indicating the kind of interval.
  • Events — the events for the period; Type is a bitmask of the event type, and NotificationId is zero for system events and for events whose rule has been deleted.
  • Files — the files received from the device during the period. The file body is downloaded with GET /api/ObjectFiles/{id}.
  • Sensors — sensor readings grouped by sensor and interval.
  • Violations — an object rather than an array: violations are split by category, and the AccelerometerFaulty flag indicates incorrect accelerometer readings for the period.

Events and acknowledgement​

GET  /api/Events/feed
POST /api/Events/ack

GET /api/Events/feed returns unacknowledged events for the notification feed, excluding events from groups muted by the user. The GET /api/Events method returns the same list without that filtering.

curl https://nav.gpspos.ru/api/Events/feed \
  -H "Authorization: Bearer <token>"

Example response:

[
  {
    "Id": 90001,
    "ObjectId": 123,
    "Time": 1750004000000,
    "Type": 2,
    "Status": 1,
    "Text": "Speeding",
    "ResetTime": 0,
    "NotificationId": 15
  }
]

Processed events are acknowledged by a list of Id values; an unacknowledged event is returned in every subsequent response:

curl -X POST https://nav.gpspos.ru/api/Events/ack \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[1001,1002,1003]'

The method returns an empty response body.

Sending a command to an object​

POST /api/Commands/run

Sends a command to a list of objects — by template (TemplateId, the template list is available at GET /api/CommandTemplates) or as a raw string (Command).

Request body:

{
  "ObjectIds": [123],
  "TemplateId": 7,
  "Command": ""
}
curl -X POST https://nav.gpspos.ru/api/Commands/run \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"ObjectIds":[123],"TemplateId":7}'

The method returns an empty response body. A successful response indicates that the command has been accepted and queued for delivery to the device; the outcome of its execution is reflected in the object's events.

Addresses from coordinates​

POST /api/ReverseGeocoder

Accepts a list of coordinates and returns the corresponding addresses. The order of the response elements matches the order of the coordinates in the request.

curl -X POST https://nav.gpspos.ru/api/ReverseGeocoder \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[{"Latitude":55.751244,"Longitude":37.618423}]'

Example response:

[
  { "Address": "Moscow, Red Square", "Street": "Red Square", "Error": null }
]

The Error field contains an error description if the address for a coordinate could not be resolved.

See also​