Geozones API (create/update)

End point:

https://gps.freetrack.com.ua/api/

Опис

Список доступних методів

create-geozones- створення множини геозон
update-geozones- оновлення множини геозон

Приклади використання

_{*червоні параметри є обов'язковими}

Параметр	Приклад	Опис

Параметр	Приклад	Опис
auth_token	{ ваш токен авторизації }	POST/GET параметр або Bearer Authentication
api_type	system	тип запиту
api_name	`create-geozones` або `update-geozones`	метод, який викликаємо
geozones	[ {"name":"test", "type":"polygon", "data":[ ["49.10", "28.3085"], ["49.1095", "28.3085060"], ["49.107", "28.309"] ]}, {…. next data item}, {.. next item} ]	дані для створення, оновлення геозон…

Кожен об'єкт даних для створення геозони, може містити наступні елементи в самому запиті:

"externalID" - це не обов'язковий атрибут (зовнішій ID геозони у Вашій системі), буде повернуто для спрощення ідентифікації даних.

_*"name" - назва бажаної геозони, в нашій системі, вона унікальна в рамках компанії. Кожна новостворена геозона буде додана до поточної компанії користувача, що виконав запит.

_*"geozoneID" - наш внутрішній ID геозони, це поле використовується тільки під час оновлення геозони.

_*"data" - координати полігональної геозони, мінімальна кількість 3 одиниці.

_*"latitude, longitude" - координати центру радіальної геозони.

_*"radius" - радіус радіальної геозони (мінімальне значення - 1, значення вказується в метрах).

_*"type" - тип геозони в нашій системі, обов'язкове поле, як для створення так і для оновлення, бо при оновлені можна змінити тип геозони - [circle або polygon].

"specialType" - спеціальний тип геозони. Може приймати значення “base“, “special“,”extended”.

“base“ - звичайна геозона;
“special“ - спеціальна (сервісна) геозона;
“extended“ - розширена геозона (на даний момент використовується для опису сміттєвих контейнерів) і вимагає додаткового, обов'язкового параметра "specialTypeExtend"

Якщо параметр "specialType" відсутній то геозона має по замовчуванню тип “base“.

"specialTypeExtend" - описує розширені характеристики для “extended“ геозон.

Типи геозон - параметр "type"

Типи геозон - параметр "type"
`circle`	кругова геозона, обов'язкові параметри для її створення: latitude, longitude, radius
`polygon`	полігональна геозона, обов'язкові параметри для її створення: data (більше 2х координат) до прикладу: "data":[ ["49.10", "28.3085"], ["49.1095", "28.3085060"], ["49.107", "28.309"] ]

Розширені характеристики - параметр "specialTypeExtend"		Приклад

Розширені характеристики - параметр "specialTypeExtend"

Приклад

multy

Описує характеристику вмісту сміттєвих контейнерів для БАГАТОКВАРТИРНОГО будинку. Містить значення :

mixed (змішані)
paper (папір)
plastic (пластик)
glass (скло)

"specialTypeExtend":{
"multi":{
"mixed":1,
"paper":0,
"plastic":3,
"glass":4
}
}

private

Описує кількість контейнерів змішаних відходів для ПРИВАТНОГО будинку

"specialTypeExtend":{"private":5}

Одночасне використання “multy“ та “private“ не допускається

Приклад правильного запиту для створення геозон:

[{
    "name":"test-1",
    "type":"polygon",
    "externalID":475214,
    "data":[
        ["49.108622", "25.3085"],
        ["49.109584511", "25.3085060"],
        ["49.104454", "25.309"]
        ]
    },
    {"name":"test-2",
     "type":"circle",
     "externalID": 75112,
     "latitude": "49.82646690800183",
     "longitude": "23.95317792892456",
     "radius": 17,
     "specialType":"special"
    },
    {"name":"test-3",
    "type":"polygon",
    "data":[
        ["49.10", "28.3085"],
        ["49.1095", "28.3085060"],
        ["49.107", "28.309"]
        ],
    "specialType":"extended",
    "specialTypeExtend":{
		"multi":{
			"mixed":1,
			"paper":2,
			"plastic":3,
			"glass":4
		}
     }
   }
]

Приклад правильного запиту для оновлення геозон:

[{
    "name":"test-6",
    "type":"polygon",
    "geozoneID":777,
    "externalID":475214,
    "data":[
        ["49.108622", "25.3085"],
        ["49.109584511", "25.3085060"],
        ["49.104454", "25.309"]
    ]
    },
    {
    "name":"test-7",
    "type":"circle",
    "geozoneID": 555,
    "latitude": "50.8264669",
    "longitude": "25.95922456",
    "radius": 17,
    "specialType":"extended",
    "specialTypeExtend":{"private":5}
    }
    ]

Приклад правильної відповіді

{
    "result": "ok",
    "response": [
        {
            "result": true,
            "name": "test-1",
            "externalID": 475214,
            "geozoneID": 10288
        },
        {
            "result": true,
            "name": "test-2",
            "externalID": 75112,
            "geozoneID": 10289
        },
        {
            "result": true,
            "name": "test-3",
            "geozoneID": 10290
        }
    ]

Приклад неправильних відповідей

*У випадку дублювання імені геозони HTTP код відповіді буде всеодно -200, а всі інші будуть 400.

Це пов'язано з тим, що якусь кількість геозон може бути все таки створено/оновлено. Результат кожної операції слід перевіряти на значення "result" в кожному повернутому елементі. Також в кожному елементі може бути властивість з ключем -"errorMessage" , це - опис помилки, якщо "result" = false.

Типи можливих помилок

Помилка	Пояснення

Помилка	Пояснення
Wrong format for ['geozones'] parameter	не правильно відформатовано параметр - geozones
Empty ['geozonesItem'] parameter!	елемент geozones є порожній об'єкт
Can`t find ['geozoneID'] at some data item	не передане потрібне значення в якомусь з об'єктів
Can`t find ['name'] at some data item	не передане потрібне значення в якомусь з об'єктів
Can`t find ['type'] at some data item	не передане потрібне значення в якомусь з об'єктів
Wrong value of ['type'] at some data item	не правильне значення параметру - type
Can`t find ['radius'] at some data item ...	не передане потрібне значення в якомусь з об'єктів
Can`t find ['latitude'] or ['longitude'] at some data …	не передане потрібне значення в якомусь з об'єктів
Can`t find ['data'] at some data item …	не передане потрібне значення в якомусь з об'єкті

НАВЧАЛЬНИЙ ПОСІБНИК

Geozones API (create/update)

Опис

Список доступних методів

Приклади використання

Приклад правильного запиту для створення геозон:

Приклад правильного запиту для оновлення геозон:

Приклад правильної відповіді

Приклад неправильних відповідей

Типи можливих помилок

Wrong format for ['geozones'] parameter

не правильно відформатовано параметр - geozones

Empty ['geozonesItem'] parameter!

елемент geozones є порожній об'єкт

Can`t find ['geozoneID'] at some data item

не передане потрібне значення в якомусь з об'єктів

Can`t find ['name'] at some data item

не передане потрібне значення в якомусь з об'єктів

Can`t find ['type'] at some data item

не передане потрібне значення в якомусь з об'єктів

Wrong value of ['type'] at some data item

не правильне значення параметру - type

Can`t find ['radius'] at some data item ...

не передане потрібне значення в якомусь з об'єктів

не передане потрібне значення в якомусь з об'єктів

не передане потрібне значення в якомусь з об'єкті