API requests

Navitel Monitoring system is a program with an open API interface. Receiving / editing / deleting of any information about monitoring objects, as well as administration of users, is possible using the API requests. Authorization of requests to the dispatching system is carried out using the API keys generated in the dispatch system settings. To obtain such key, in the dispatching system open the Settings menu and select the API tab.

1. General

For all requests of the public JSON-RPC API interface, the prefix "public-1.0-" is used. In the following description of all methods, this prefix is implied. For example, the method described below as group.get should be called as public-1.0-group.get.

Close

1.1. Request format

All requests are HTTP POST requests, the JSON object of the following structure is used as the request body:

{ "jsonrpc": "2.0", "id": <request-id>, # steadily increasing integer "method": <method-name>, # method name, a string "params": [ .... ] }

  • The id field is a monotonically increasing ID requests, an integer

  • Method field - method name, string

  • The params field is a list of (empty) method arguments.

Because the JSON-RPC API is designed for robots, incoming requests will not support filters and paging now. All the filtering must be done on the requestor's side.

Close

1.2. Result returning

All methods return the HTTP code and the body of the response. If the request is a valid HTTP request, the HTTP code is returned 200, and the response body is the JSON object. If the request succeeded, then the returned object contains the result field.

{ "result": .... }

The value returned in the result field is specific to each request and is described below.

Close

1.3. Error message

If the request was rejected for reasons related to the correctness of the HTTP request, then appropriate HTTP error codes are possible (for example, 400, 403, 404, 405, etc.).

If the request was syntactically correct, but at execution occurred an error at the level of the Dispatcher System, then the HTTP 200 code is returned, and the returned JSON object has no result field, but the error field:

{ "error": .... }

Formats of possible errors in the execution of requests are described below.

Close

2. Main requests

2.1. Retrieving the List of Vehicles

Before trying to retrieve information on vehicles with the help of an API key, it is necessary to get the list of vehicles and their identification characteristics. For that, make a (GET) request:

https://www.dispatch.navitel.ru/api/1.0/vehicles.xml?apikey=[val]&namefilter=

where "apikey=[val]" is a typical name/value parameter. The "apikey" part of this parameter is name, whereas "[val]" is a place for value input. Insert the API key that you receive from the program settings in the value part of this parameter. Therefore, a proper request for the list of vehicles would look similar to this:

https://www.dispatch.navitel.ru/api/1.0/vehicles.xml?apikey=00000000000000000000000&namefilter=

Additionally, the filter name parameter must be in the end of the list of vehicles request

namefilter=[value]

where "[value]" – is the filter value. You may indicate a particular object name which you want to get the information about, or you can leave the field empty if you want to retrieve the list of all objects, as shown in the example above.

After requesting the list of vehicles you receive a reply in the form of an .xml code piece.

<reply> <resulttype="array"> <v i="0"> <group_name>security_group</group_name> <tracker_id>GALILEOSKY:00000000000000000000000000000000</tracker_id> <tracker_type>GALILEOSKY</tracker_type> <vehicle_id>xxxxx-xxxx-xxxx-xxxxxxxxxxxx</vehicle_id> <vehicle_name>Subaru</vehicle_name> </v> <v i="1"> <group_name>security_group</group_name> <tracker_id>GRANIT:00000000000000000000000000000</tracker_id> <tracker_type>GRANIT04</tracker_type> <vehicle_id>xxxxx-xxxx-xxxx-xxxxxxxxxxxx</vehicle_id> <vehicle_name>cardabalet</vehicle_name> </v> </result> </reply>

The response includes information about vehicles, including group/company, imei/id of the tracker, type of the tracker, id of the vehicle, and name of the vehicle. You will be able to use that data after in order to identify vehicles that you want to retrieve the information about.

You can specify the preferred format of the result in your request. For that, add the suitable extension after the "vehicles" word. Possible extensions: ".xml" or ".json" (this functionality is available for any type of request to the dispatch system).

The result in this example will be delivered in the form of an .xml

https://www.dispatch.navitel.ru/api/1.0/vehicles.xml

and in this example, the result will be delivered in the form of .json code

https://www.dispatch.navitel.ru/api/1.0/vehicles.json

Close

2.2. Request authentication

The JSON-RPC API uses the API key for identification, which is the first mandatory parameter of all methods except apikey.get. To get the API key in the menu bar, click Settings (). In the dialog that appears, click the API tab, and then click Create.

Close

2.3. Request creation scheme

  • apikey.get - obtaining API keys by user name and password

    • Parameters:

      • login

      • password

    • Result:

      • string of API key

Close

2.4. Group requests

  • group.get — getting group list.

    • Parameters:

      • Object containing the following fields:

        • (optional) parent_group_uuid_list – Optional list of parent groups. Parent groups must be accessible to the user who is performing the request. If there is no or an empty list in the request, the result contains all the top-level groups available to the user, or all groups, if the recursive parameter is True.

        • recursive — boolean whether to list the groups recursively.

    • Result:

      • list of structures that describe groups. The following fields in the structures are documented:

        • obligatory:

          • uuid — UUID of the group

          • name —

        • non-obligatory:

          • parent_group_uuid — UUID of the parent group, if the parent group exists and the API is available to the user

          • limits — an object containing a list of constraints, if constraints are specified for a group (the group is a company):

            • max_users — Maximum number of users, integer or null, if no limit is specified

            • max_vehicles — Maximum number of vehicles, integer or null, if no limit is specified

            • valid_until — License validity period, line in ISO-8601 format or null if no limit is specified

  • group.create — group creation.

    • Parameters:

      • groups — A list of objects that describe created groups. In each object, the same fields are documented as the group.get fields. Do not specify the group UUID, the field will be ignored.

    • Result

      • UUID list of created groups.

  • group.edit — change selected fields in existing groups.

    • Parameters:

      • group_fields — A dictionary of objects describing modifiable group fields. The keys in the dictionary are UUID groups. The fields in the objects correspond to the fields in group.get. The fields that are not specified in the object are not changed. The absence of the group with the specified UUID at the time of the request is an error.

    • Result is absent

  • group.delete — groups deleting.

    • Parameters:

      • uuid_list — List of UUIDs of deleted groups. The absence of a group with the UUID specified at the time of the request is not considered an error.

    • Result is absent

Close

2.5. Requests from monitoring objects

  • vehicle.get — receiving a list of tracking devices for the specified group.

    • Parameters:

      • parent_group_uuid — group's UUID.

    • Result:

      • list of structures describing monitoring objects in this group. In each structure, the following fields are documented:

        • obligatory:

          • uuid — monitoring object's UUID

          • name — monitoring object's name

          • parent_group_uuid

          • tracker_type — string identifying the type of tracker, from a fixed list of rows (enum); currently there is only one element in the list - OLYMPSTROY. In the future, the list of trackers supported by this API will be expanded

          • tracker_identifier — string or a set of strings that identify an instance of a tracker of this type.
            Note: currently there are no trackers that require an array of lines, later they will be explicitly listed

        • non-obligatory:

          • display_icon — number of the icon. At present, numbers from 0 to 14 are standardized.

          • display_color — Color icons, a line in CSS format hexadecimalcolors (#RRGGBB).

        • Caller must correctly process the presence of new, undocumented fields.

  • vehicle.create — creating new vehicles as objects.

    • Parameters:

      • vehicles — A list of structures describing the monitoring objects that are being created. The UUID is not specified (set by the server). Valid fields correspond to the fields in the vehicle.get. Required fields are:

        • name

        • parent_group_uuid

        • tracker_type

        • tracker_identifier

    • Result:

      • list of UUIDs of the created monitoring objects or an error if at least one of the requested objects can not be created.

  • vehicle.edit — Editing properties of monitoring objects.

    • Parameters:

      • vehicle_fields — a dictionary, keys of which are UUIDs of monitoring objects, and values - structures describing changes in objects. Valid fields correspond to fields in the vehicle.get. The fields that are not specified in the query are not changed. Impossibility for one reason or another to edit at least one of the listed objects results in an error of the entire request, no changes are applied.

    • Result:

      • Not available if the operation completed successfully, or an error message is displayed in the specified format.

  • vehicle.delete — deleting vehicles.

    • Parameters:

      • uuid_list — UUID list of deleted monitoring objects. The absence of an object with the UUID specified at the time of the request is not considered an error.

    • Result: No, if the operation was successful, or an error message in the specified format.

Close

2.6. Role requests

  • role.get — get list of roles for the specified group.

    • Parameters:

      • parent_group_uuid.

    • Result:

      • list of structures describing the roles in this group. In each structure, the following fields are documented:

        • uuid — role UUID

        • name — role name

Close

2.7. User's requests

  • user.get — get a list of users for the specified group.

    • Parameters:

      • parent_group_uuid

    • Result:

      • list of structures describing users in this group. The fields are described above.

  • user.create — creating users.

    • Parameters:

      • Users — A list of structures describing the users being created. UUID is not specified (set by the server).

    • Result:

      • UUID list of created users.

  • user.edit — modifying selected fields from existing users.

    • Parameters:

      • user_fields — a dictionary of structures describing the user's modifiable fields. The keys in the dictionary are UUID users. Undefined fields should be changed. The absence of a user with the specified UUID at the time of the query execution is an error.

    • Result is absent

  • user.setPassword – set user's password.

    • Parameters:

      • uuid – user's UUID

      • password – new password

  • user.delete — deleting created users.

    • Parameters:

      • uuid_list — List of UUIDs to delete users. Absence at the time of performing a user request with the specified UUID is not considered an error.

    • Result is absent

Close

3. Requests for creating travel sheets

3.1. Retrieving data from a travel report

JSON-RPC request is as follows:

{ "jsonrpc": "2.0", "id": <requestId>, "method": "public-1.0-report.trip.get", "params": [ apiKey, { "startTime": <timestamp>, "endTime": <timestamp>, "lang": <langId>, "vehicles": [ "<uuid1>", "<uuid2>",... ] } ] }

Answer format:

{ "id": <requestId>, // request ID "result": { "startTime": <timestamp>, "endTime": <timestamp>, "address_fields": [ "country", "region", "parish", "city", "district", "street", "building" ], "headers": [ "moveTime", "startTime", "origin", "endTime", "destination", "maxSpeed", "kilometresTravelled", "totalFuelConsumption" ], "vehicles": [ { "uuid": "<uuid>", // vehicle UUID "name": "<name>", "rows": [ [ <interval>, <timestamp>, <address>, <timestamp>, <address>, <kmh>, <km>, <litres> ], ... ] }, { "uuid": "<uuid>", // vehicle UUID "name": "<name>", "rows": [ ... ], }... ] } }

Close

3.2. Retrieving Monitoring Information

A regular request to the dispatch system is basically a line that consists of a base-URL and a set of request parameters. The base-URL should always be as such (the exception is when retrieving the list of vehicles):

https://www.dispatch.navitel.ru/api/1.0/vehicleinfo.xml?

Parameters of the request are a line of name/value pairs, each pair separated by an ampersand ("&"). They are to be put right after the question mark of the base-URL. Each parameter has the following name/value form:

field=[value]

where "[field]" is the parameter name, and "[value]" is the parameter value. There are several names available for input: "id", "name", "imei", "time", "what", "apikey". The input is case-sensitive.

A request should normally contain such parameters as listed below:

1. A set of vehicle identifications. Any vehicle is defined by one out of the three possible identifications: "id", "name", "imei". The identification is basically a line of such type:

id=[vehicle_static_id_0]

where "[vehicle_static_id_0]" is the vehicle ID that you can get by requesting the list of vehicles.

Since identifications are just mere name/value parameters, you can use many of them to receive information about several vehicles at once. Similar to other parameters, identifications should be separated by an ampersand.

id=[vehicle_static_id_0]&id=[vehicle_static_id_0]

You can use different types of identifications when specifying vehicles in request. For example:

id=[vehicle_static_id_0]&name=[vehicle_name]&imei=[vehilce_imei]&id=[vehicle_static_id_N]

If you happen to input different identifications of the same vehicle, do not worry, the vehicle will always be shown only once.

2. API key:

apikey=[val]

where "[val]" is the API key that you can receive in the settings of the dispatch system.

3. Set of necessary parameters, each parameter separated by an ampersand ("&"):

field=[value]&field=[value]&field=[value]

where "[field]" is the parameter name, and "[value]" is the parameter value. Use the tables below as guidance for correct parameter names and values.

Close

3.3. Parameters for a Fixed Period of Time T

As of now, you should already be aware of how to include identification and API parameters in the request. But there is also the "what" parameter that is used to request information about an indicator specified in the value of the parameter block.

Say, if I wanted to receive information about speed of an object at this particular moment of time, I would use parameter

what=speed_kmh

then, the full request would be as such:

https://www.dispatch.navitel.ru/api/1.0/vehicleinfo.xml?apikey=00000000000000000000000&name=NaviCar&what=speed_kmh

In the example above I requested information about speed of the vehicle named "NaviCar" and used the API access code "00000000000000000000000" to access the dispatch system. Similarly, you may request information on parameters listed in the table below. The name for all parameters from this table is "what"; the value should be taken from the "Value" column of the table.

Parameter description

Value

ignition

ignition

latitude, longitude

lat_deg, lon_deg

speed

speed_kmh

movement direction

direction_deg

number of satellites, hdop

satellite_count, hdop

height

altitude_m

gsm parameteres (mcc,mnc,lac etc)

mcc, mnc, lac, cellid, signal_strength, timing_advance

external power supply voltage

external_power_mv

internal power battery voltage

battery_power_mv

tracker's temperature

temperature_c

accelerometer readings (x, y, z)

acceleration_x_ms2, acceleration_y_ms2, acceleration_z_ms2

alarm button

alarm_on

coolant temperature

coolant_temp_c

engine rotation rate

engine_rpm

fuel level (%)

fuel_percent

mileage

mileage_km

total fuel consumed

total_fuel_consumed_l

fuel level (can)

can_fuel_l

engine operating time (can )

mhours

speed (can)

can_speed_kmh

fuel level (calculated, converted etc.)

fuel_l

analog inputs

analog_input

digital inputs

digital_input

can input

can_input

frequency input

frequency_hz

pulse counters

pulse_counter_pcs

axle load

axle_load_kg

can log version

can_log_version

size of the received packaged in bytes

in_chunk_size

the count of packages received

in_package_count

size of the serve reply in bytes

out_chunk_size

the number of server replies

out_package_count

the list of wire input values

one_wire_input

the list of sensor input values

sensor_input

the list of analog input values

voltage_mv

Close

3.4. Time Specification

When no time parameter is specified in the request, the return includes data on the current moment of time. For specifying a distinct moment in time in the request a special time parameter is used:

time=[val]

where "[val]" is a moment in time specified in compliance with the ISO 8601 standard (see https://en.wikipedia.org/wiki/ISO_8601). The input is case-sensitive.

According to this standard, the time format has the form "YYYY-MM-DDThh:mm:ss". Therefore, the input should be as such:

time=2016-07-12T12:00:00

where the date is indicated as July 12th 2015 and the time is 12:00:00.

You can also specify a time zone in the value of the time parameter by adding the time zone name in the end of the value (for example, MSK or "Asia/Novosibirsk").

time=2016-07-12T12:00:00MSK

To indicate the UTC time zone, simply add "Z" in the end of the parameter value.

You can also adjust a time zone by simply moving the time "hh:mm" backward or forward up until you reach the necessary time zone.

time=2016-07-22T12:00:00+03:00

Close

3.5. Time Interval Specification

If you want to specify a time interval, indicate 2 time moments as shown in the previous chapter and separate them with the slash symbol.

time=[val1]/ [val2]

where "[val1]" – is the beginning of the time interval, while "[val2]" is the end.

For example:

time=2015-07-12T12:00:00/2015-07-15T15:52:01

This means that the time interval starts on 12th July of 2015 at 12:00:00, and ends on 15th July of 2015, at 15:52:01.

It is also possible to create a time interval in the "IsoTime/duration" form, where duration of the interval is specified as "PxxYxxMxxDTxxHxxMxxS (the P prefix is followed by the interval duration, case-sensitive). If there is a time interval set, the largest value from this interval is taken for the group A parameters.

The table below provides the list of "what" parameters that must always be used together with the time interval parameters:

Parameter description

Value

duration of movement

moveTime

duration of stay

stopTime

stay with no data

lostSignalTime

mileage

kilometresTravelled

fuel consumption in liters

totalFuelConsumption

average speed

avgMoveSpeed

top speed

maxSpeed

initial point

origin

destination point

destination

end/start fuel level

endFuelLevel, startFuelLevel

fuel consumption (liters) per /100km

fuelPer100Km

fuel/drain count (events)

fuelingCount, fuelDrainCount

fuel/drain count (liters)

totalFueling, totalFuelDrain

Close

4. Operations with layers

4.1. Retrieving layer list in groups

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.get", "params": [ "", ["", ""...] // list of group's UUID ] }

Response at positive outcome:

{ "result": [ <object list> ] }

Each layer is described by following structure:

{ "uuid": "", "external_id": ", // non-obligatory ID of layer in external system "parent_group_uuid": "", "name": ", "visibility": , "priority": }

Close

4.2. Data update in layers

This method clears the layer specified in the "" parameter, and then fills this layer with a list of new objects.

Request format:

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.objects.replace", "params": [ "", "", [ <object list> ] ] }

Each object has the following structure:

{ "name": "", "geometry": "", // currently supported only one type POINT "icon_url": "", "color_id": , // currently only colors from 1 to 9 are standardized "geo_object_fields": { // non-obligatory dictionary of additional object features "": ,... } }

Response at positive outcome:

{ "result": [ "", ""... ] // list of created object's UUIDs. }

In the response, the serial number of the UUID corresponds to the object number in the request. All the requested changes are applied atomically: or all are applied, or the state of the layers has not changed.

Close

4.3. Adding an object into a layer

Similar to "public-1.0-layer.objects.replace", but without first deleting the existing objects in the layer.

Request:

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.objects.create", "params": [ "", "", [ <object list> ] ] }

Each object has the following structure:

{ "name": "", "geometry": "", // currently supported only one type POINT "icon_url": "", "color_id": , // currently only colors from 1 to 9 are standardized "geo_object_fields": { // non-obligatory dictionary of additional object features "": ,... } }

Response at positive outcome:

{ "result": [ "", ""... ] // list of created object's UUIDs. }

In the response, the serial number of the UUID corresponds to the object number in the request. All the requested changes are applied atomically: or all are applied, or the state of the layers has not changed.

Close

4.4. Editing objects in layers

Similar to "public-1.0-layer.objects.replace", but the enumerable objects identified by the "uuid" field must already exist in the layer. Specifying object properties other than "uuid" is optional. The fields of the object that are not specified in the query are not changed in the dispatch system.

Request:

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.objects.create", "params": [ "", "", [ <object list> ] ] }

Each object has the following structure:

{ "uuid": "", // All the following fields are optional, if the field is not specified it will not be edited. "name": "", "geometry": "", // currently supported only one type POINT "icon_url": "", "color_id": , // currently only colors from 1 to 9 are standardized "geo_object_fields": { // non-obligatory dictionary of additional object features "": ,... } }

Close

5. Data types description

<RequestId> - unique request-response ID, integer.

<LangId> is the code of the preferred response language, language is a lowercase, two-letter, ISO 639 language code.

<Interval> - time interval in seconds, integer.

<Timestamp> - the number of seconds since 01/01/1970 00:00 UTC.

<Address> is an array whose elements are strings corresponding to the address components listed in the address_fields field.

<Kmh> - speed, km/h, float.

<Km> - distance, km, float.

<Litres> - volume, l, float.

Close