API description

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.

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

• 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.

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:

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:

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:

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

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.

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

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

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:

Answer format:

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):

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:

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:

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.

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

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:

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 ("&"):

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

then, the full request would be as such:

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:

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:

where the date is indicated as July 12^th 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").

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.

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.

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

For example:

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:

Response at positive outcome:

Each layer is described by following structure:

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

Request format:

Each object has the following structure:

Response at positive outcome:

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:

Each object has the following structure:

Response at positive outcome:

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:

Each object has the following structure:

<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.