Page tree

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

Skip to end of metadata
Go to start of metadata

Информация о зонах доступных пользователю.

Запрос:

URL:

Запрос списка всех зон:

GET https://api.url/v2.1/user/<user_id>/zones

Запрос зоны по id:

GET https://api.url/v2.1/user/<user_id>/zones/<zone_id>

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

If-Modified-Since - Если ранее уже запрашивался полный список зон, то при обновлении следует указывать заголовок If-Modified-Since с датой полученной заголовка ответа Last-Modified

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

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

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

ИмяТипЗначение по умолчаниюМаксимальное значениеОписание
page[offset]int0
Пропустить несколько первых записей
page[limit]int10005000Количество ТС в выводе
fields[zone]string

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

filterstring

Фильтрация результатов (см раздел "Фильтрация результатов")
sortstring

Сортировка результатов.

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

Ответ:

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

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

Поле links содержит ссылки на доступные ресурсы.

Минимально он должен содержать ссылку на текущий ресурс (self).

Если все Зоны не удалось поместить в одном ответе, то также будет содержаться:

next - следующая страница (если есть)

prev - предыдущая страница (если есть)

first - первая страница с результатами

last - последняя страница с результатами


metaСодержит total_count - количество зон у пользователя (с учетом фильтра)
data

Содержит массив объектов Зон в формате JSON API.

Каждый объект Зоны содержит

ПолеТипОписание
idintИдентификатор Зоны (передаётся как строка для соответствия JSON API)
typestringТип ресурса (всегда "zone")
attributesobjectДанные объекта (см. Описание атрибутов Зоны)


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

ПолеТипNullableОписание
NamestringнетНазвание зоны
DescriptionstringдаОписание зоны
Geometryobject<GeoJSON>нет

Расположение зоны (Геометрия в формате GeoJSON)


Поддерживаются только геометрии типа: Point, LineString и Polygon

Геометрии типа Polygon не должны быть самопересающимися и содержать дыры.

Геометрии типа Point и LineString должны иметь дополнительное поле radius в properties (обозначает радиус/ширину точки/линии в метрах).

Colorhex stringнет

Цвет геозоны. Передаётся шестнадцатеричным числом RRGGBBAA

RR - красный байт

GG - зелёный байт

BB - синий байт

AA - прозрачность (0x00 - полностью прозрачный (невидимый), 0xff - полностью непрозрачный)

DateOfCreationdatetimeнетДата создания
AccountNamestringдаЛогин пользователя создателя зоны
UpdateDatedatetimeнетДата обновления

Связанные объекты:

ПолеТипNullableОписание
CreatoruserInfoдаСоздатель зоны

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

200 ОК - Сервер обработал запрос. В теле ответа  содержится список зон. Также будет передан заголовок Last-Modified.

304 Not Modified - Сервер обработал запрос. Изменения не найдены.

403 Forbidden - нет прав на просмотр зон.

404 Not Found - Зона не найдена (при получении зоны по id).

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

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

Пример

Список всех зон

GET http://api.url/v2.1/user/1/zones 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
Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT
					
{
    "links": {
        "self": "http://api.url/v2.1/user/1/zones",
        "first": "http://api.url/v2.1/user/1/zones",
        "next": "https://api.url/v2.1/user/1/zones?page[offset]=200&page[limit]=200",
        "last": "https://api.url/v2.1/user/1/zones?page[offset]=400&page[limit]=200"
    },
    "data": [
        { "type": "zone",
          "id": "1",
          "attributes": {
             "Name": "Зона1",
             "Description": "Описание.",
             "Geometry": {
                 "type": "Feature",
                 "geometry": { 
                     "type": "Point",
                     "coordinates": [ 125.6, 10.1 ]
                 },
                 "properties": {
                     "radius": 100
                 }
             },
             "Color": "FF000073",
             "AccountName": "username",
             "DateOfCreation": "2021-01-01T00:00:00Z",
             "UpdateDate": "2021-01-01T00:00:00Z"
         },
         "relationships": {
             "Creator": {
                  "data": {
                      "id": "478",
                      "type": "user"
                  }
             }         
         }
      },
      ... остальные зоны ...

    ],
    "meta":{
        "total_count": 450
    }
}


  • No labels