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.
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.
{ "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.
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.
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.
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
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.
apikey.get - obtaining API keys by user name and password
Parameters:
login
password
Result:
string of API key
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
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.
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
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
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": [ ... ], } ... ] } }
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.
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.
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
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:
{ "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": }
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.
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.
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 "": ,... } }
<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.