v2.1 Детальная история

Получение истории состояний ТС.

Запрос:

URL:

Вся история: GET https://api.url/v2.1/user/<user_id>/cars/<car_id>/history/full

Данные по отдельному пакету истории: GET https://api.url/v2.1/user/<user_id>/cars/<car_id>/history/full/<history_id>

Доп. Заголовки:

Accept - для указания формата ответа. Должен быть "application/vnd.api+json", для совместимости принимается также "application/json".

Authorization - для передачи токена. Передается в формате: Bearer <access_token>.

Доп. Параметры запроса:

Имя	Тип	Значение по умолчанию	Максимально допустимое значение	Описание
filter[histState]	string			Фильтрация результатов запроса.
sort	string			Сортировка результатов запроса. По умолчанию сортируется по RecordDate от более ранних записей к более поздним.
page[offset]	int			Пропустить первые n записей.
page[limit]	int	40000	100000	Максимальное количество записей в ответе
fields[histState]	string			Фильтрация полей отображаемых в состояниях Для получения данных только по заданным датчикам следует указать их после Sensor через точку Пример: fields[histState]=Sensors.1,Sensors.2,Sensors.3 Такой фильтр скроет в ответе все сенсоры id которых не 1, 2 или 3.
with_total_count	boolean	true		Отключение расчета количества записей. При значении with_total_count=false поле meta не содержится в структуре ответа. Также в ответе будут отсутствовать ссылки first / prev / next / last, т.к. для их показа нужно знать общее количество подходящих записей.

Параметр include (определённый в стандарте JSON API) в текущей версии api не поддерживаются. В случае их получения сервер будет возвращать ошибку 400

Ответ:

Ответ присылается в формате JSON API.

Поле

Описание

links

Поле links содержит ссылку на текущий ресурс (self)

Описание атрибутов истории:

Описание объекта состояния ТС в истории (histState).

Поле	Тип	Nullable	Описание
Alt	int	да	Высота над уровнем моря, в метрах.
Direction	double	да	Направление движения в градусах
Lat	double	да	Широта в градусах
Lon	double	да	Долгота в градусах
RecordDate	datetime	нет	дата создания пакета на устройстве
Sensors	Array[SensorData]	нет	Массив датчиков Каждый датчик содержит: id (идентификатор датчика) и value (показание датчика).
Velocity	double	да	Скорость движения

Коды ответов:

200 ОК - Сервер обработал запрос. В теле ответа содержится объект истории.

401 Unauthorized - не передан заголовок Authorization, либо токен невалидный или окончилась валидация.

403 Forbidden - нет прав на просмотр (id пользователя не соответствует токену).

404 Not Found - ТС не найдена или принадлежит другому пользователю либо нет истории по ТС (ни разу не выходила на связь либо история удалена).

400 Bad Request - Переданы не поддерживаемые параметры, запрошен слишком большой период, либо сервер не понял запрос (описание ошибки в теле ответа).

Также возможны другие ошибки.

Пример

GET https://api.url/v2.1/user/1/cars/1/history/full HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <auth token>

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Allow: GET				
		
{
    "links": {
        "self": "https://api.url/v2.1/user/1/cars/1/history/full",
    },
    "meta": {
        "total_count": 1000
    },
    "data": [
       {
           "type": "histState",
           "id": "3212394712398",
           "attributes": {
               "RecordDate": "2014-10-09T16:04:14Z",
               "Alt": null,
               "Direction": 45.0,
               "Lat": 45.1234,
               "Lon": 120.321,
               "Velocity": 0,
               "Sensors": [
                   {  
                     "id": 1,
                     "value": 1
                   },
                   {
                     "id": 55,
                     "value": 8
                   }
               ]
           }
       },
       { 
           "type": "histState",
           "id": "3212394712999",
           "attributes": {
               "RecordDate": "2014-10-09T16:24:24Z",
               "Alt": null,
               "Direction": 42.2,
               "Lat": 45.12341,
               "Lon": 120.3213,
               "Velocity": 12,
               "Sensors": [
                    {
                        "id": 1,
                        "value": 1
                    },
                    {
                        "id": 55,
                        "value": 8
                    },
               ]
           }
       },
       ... остальные пакеты ...
  ]
}

Примеры популярных запросов:

Получение всех данных истории за период c 2019-01-01 00:00:00 до 2019-02-01 00:00:00

https://api.url/v2.1/user/<user_id>/cars/<car_id>/history/full?filter[histState]=and(gte(RecordDate,2019-01-01T00:00:00Z),lt(RecordDate,2019-02-01T00:00:00Z))

Запрос вернёт все пакеты истории которые есть на период от 2019-01-01 00:00:00 (включительно) до 2019-02-01T00:00:00 (не включительно), если данных за указанный промежуток не было то будет пустой массив.

Получение уровня топлива на ТС на 2019-01-01 12:33:00

Датчики уровня топлива - 12, 68 и 325. Полный список можно получить запросом "https://api.url/v2.1/sensors?fitler[sensor]=eq(Destination,100)" (см метод v2.1 Справочник датчиков).

https://api.url/v2.1/user/<user_id>/cars/<car_id>/history/full?sort=-RecordDate&filter[histState]=and(exist(Sensors,12,68,325),and(gte(RecordDate,2019-01-01T12:33:00Z),lte(RecordDate,2019-01-01T12:33:00Z)))&fields[histStat]=Sensors.12,Sensors.68,Sensors.325&page[limit]=1&with_total_count=false

Запрос вернёт последний пакет где был один из датчиков 12, 68 или 325, при этом в данных будут отображаться только эти датчики (других полей не будет).

Page tree