Page tree

Citypoint - контроль и аналитика автопарка

Skip to end of metadata
Go to start of metadata

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

Запрос:

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

Фильтрация результатов запроса.

sortstring

Сортировка результатов запроса. По умолчанию сортируется по RecordDate от более ранних записей к более поздним.
page[offset]int

Пропустить первые n записей.
page[limit]int40000100000

Максимальное количество записей в ответе

fields[histState]string

Фильтрация полей отображаемых в состояниях

Для получения данных только по заданным датчикам следует указать их после Sensor через точку

Пример:

fields[histState]=Sensors.1,Sensors.2,Sensors.3

Такой фильтр скроет в ответе все сенсоры id которых не 1, 2 или 3.

with_total_countbooleantrue

Отключение расчета количества записей.

При значении with_total_count=false поле meta не содержится в структуре ответа.

Также в ответе будут отсутствовать ссылки first / prev / next / last, т.к. для их показа нужно знать общее количество подходящих записей.

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

Ответ:

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

ПолеОписание
links

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

metaСодержит поле total_count которое содержит количество записей в выбранной истории.
data

Содержит объект истории ТС.

Каждый объект ТС содержит

ПолеТипОписание
Idstring

Идентификатор точки (состояния) истории

typestringТип ресурса (всегда "histStat")
attributesobjectДанные истории (см. Описание атрибутов)

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

Описание объекта состояния ТС в истории (histState).
ПолеТипNullableОписание
AltintдаВысота над уровнем моря, в метрах.
Direction
doubleдаНаправление движения в градусах
Latdoubleда

Широта в градусах

LondoubleдаДолгота в градусах
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),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, при этом в данных будут отображаться только эти датчики (других полей не будет).

  • No labels