Робота з регіонами

25 9 Травня, 2023

Зміст статті

Якщо у Вас виникли складнощі, зверніться до нас за консультацією, тел. 067 312 60 60 або у чат на сайті.

Ознайомитись з усіма можливостями API програми Web4 можна перейшовши за посиланням – Довідник API.

Для роботи з API потрібно використовувати токен доступу, як його отримати описано тут.

Тестування API зручно проводити з допомогою програми Postman.

Програма Web4 працює з двома типами регіонів (кругові/довільної форми). Вигляд кругового регіону та регіону довільної форми у програмі Web4 на Мапі.

Вигляд кругового регіону та регіону довільної форми у програмі Web4 у Cписку регіонів.

ВАЖЛИВО!!! Якщо користувач виконав якийсь з запитів на створення/редагування/видалення регіону, перебуваючи у програмі Контроль Плюс, то для того, щоб регіон було створено/редаговано/видалено зі Списку регіонів/мапи, потрібно вийти та повторно виконати вхід у програму.

Створення регіонів

Кругові регіони

Круговий регіон можна створити за допомогою запитів двома методами –  v3/insRegionCircle та v3/insRegionsCircle.

Метод v3/insRegionCircle – створює один круговий регіон навколо вказаної точки заданого радіусу. 

Параметри методу:

  • name – назва регіону;
  • lat – широта центру регіону;
  • lng – довгота центру регіону;
  • radius – радіус регіону (у метрах, більший за 10 м, менший за 32000 м).

Приклад запиту v3/insRegionCircle

POST https://api.gps-khm.net/v3/insRegionCircle?token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту

{
  "name": "Круговий тестовий регіон 1",
  "lat": 49.661044,
  "lng": 27.409944,
  "radius": 1500
}

Відповідь

Status code 200
{
    "id": 68940 //Значення цього параметра буде використовуватись для роботи із регіоном
}

Після цього регіон має з’явитись у Списку регіонів та на Мапі.

Метод v3/insRegionsCircle – створює масив кругових регіонів (також можна створити 1 регіон).

Параметри методу такі ж, як і у v3/insRegionCircle.

Приклад запиту v3/insRegionsCircle 

POST https://api.gps-khm.net/v3/insRegionsCircle?token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту (створення двох регіонів)

[
  {
    "name": "Круговий тестовий регіон 2",
    "lat": 49.690065,
    "lng": 27.400588,
    "radius": 1400
  },
  {
    "name": "Круговий тестовий регіон 3",
    "lat": 49.676181,
    "lng": 27.333641,
    "radius": 1300
  }
]

Відповідь

Status code 200

Після цього регіони мають з’явитись у Списку регіонів та на Мапі.

Регіони довільної форми

Регіон довільної форми можна створити за допомогою запитів двома методами – v3/insRegionPolygon та v3/insRegionsPolygon.

Метод v3/insRegionPolygon – створення одного регіону довільної форми. 

Параметри методу:

  • name – назва регіону;
  • coordinates – масив координат вершин регіону (мінімум 3 координати).

Приклад запиту v3/insRegionPolygon

POST https://api.gps-khm.net/v3/insRegionPolygon?token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту

{
  "name": "Тестовий регіон довільної форми 1",
  "coordinates": [
    {
      "lat": 49.776940,
      "lng": 27.426681
    }, 
    {
      "lat": 49.788135,
      "lng": 27.453460
    }, 
    {
      "lat": 49.769845,
      "lng": 27.458438
    } 
  ]
}

Відповідь

{
    "id": 68943  //Значення цього параметра буде використовуватись для роботи із регіоном
}

Після цього регіон має з’явитись у Списку регіонів та на Мапі.

Метод v3/insRegionsPolygon – створення масиву регіонів довільної форми (також можна створити 1 регіон).

Параметри методу такі ж, як і для методу v3/insRegionPolygon.

Приклад запиту v3/insRegionsPolygon

POST https://api.gps-khm.net/v3/insRegionsPolygon?token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту (створення двох регіонів)

[
  {
    "name": "Тестовий регіон довільної форми 2",
    "coordinates": [
      {
        "lat": 49.813730,
        "lng": 27.538261
      }, 
      {
        "lat": 49.813951,
        "lng": 27.572937
      }, 
      {
        "lat": 49.783148,
        "lng": 27.576026
      }, 
      {
        "lat": 49.783259,
        "lng": 27.543239
      } 
    ]
  },
  {
    "name": "Тестовий регіон довільної форми 3",
    "coordinates": [
      {
        "lat": 49.843628,
        "lng": 27.456207
      }, 
      {
        "lat": 49.835325,
        "lng": 27.466335
      },  
      {
        "lat": 49.832003,
        "lng": 27.448310
      } 
    ]
  }
]

Відповідь

Status code 200

Після цього регіони мають з’явитись у Списку регіонів та на Мапі.

Отримання регіонів

Отримати регіон можна за допомогою запитів двома методами – v4/selRegions та v1/getRegion.

Метод v4/selRegions – повертає список регіонів.

Параметри методу відсутні.

Приклад запиту v4/selRegions

GET https://api.gps-khm.net/v4/selRegions?token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту – відсутнє.

Відповідь (масив об’єктів типу, як описаний нижче)

Status code 200
    {
        "id": 68945,
        "clientID": 177,
        "name": "Тестовий регіон довільної форми 3",
        "radius": 0,
        "area": 730881.105936927,
        "areaHa": 73.09,
        "x": 0.0,
        "y": 0.0,
        "leftTopX": 27.44831,
        "leftTopY": 49.84363,
        "rightBottomX": 27.46634,
        "rightBottomY": 49.832,
        "type": 10,
        "countryID": null,
        "countryName": null,
        "regionID": null,
        "regionName": null,
        "districtID": null,
        "districtName": null,
        "verticles": [
            {
                "id": 5578059,
                "regionID": 68945,
                "x": 27.45621,
                "y": 49.84363
            },
            {
                "id": 5578060,
                "regionID": 68945,
                "x": 27.46634,
                "y": 49.83532
            },
            {
                "id": 5578061,
                "regionID": 68945,
                "x": 27.44831,
                "y": 49.832
            }
        ],
        "сadastralNumber": "",
        "contractNumber": "",
        "contractWithName": "",
        "сontractDateFrom": null,
        "сontractDateTo": null,
        "isOtherTenants": false,
        "comment": "",
        "color": ""
    }

Метод v1/getRegion – повертає регіон за вказаним id (круговий/довільної форми).

Для прикладу можемо взяти id створеного регіону описаного вище – “Круговий тестовий регіон 1” з id = 68940.

Параметри методу :

  • id – унікальний ідентифікатор регіону, який присвоюється при створенні регіону.

Приклад запиту v1/getRegion

GET https://api.gps-khm.net/v1/getRegion?id=68940&token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту – відсутнє.

Відповідь

Status code 200
{
    "id": 68940,
    "clientID": 177,
    "name": "Круговий тестовий регіон 1",
    "radius": 1500,
    "area": 0.0,
    "areaHa": 0.0,
    "x": 27.40994,
    "y": 49.66105,
    "leftTopX": 0.0,
    "leftTopY": 0.0,
    "rightBottomX": 0.0,
    "rightBottomY": 0.0,
    "type": 10,
    "countryID": null,
    "countryName": null,
    "regionID": null,
    "regionName": null,
    "districtID": null,
    "districtName": null,
    "verticles": [
        {
            "id": 5578049,
            "regionID": 68940,
            "x": 27.40994,
            "y": 49.66105
        }
    ],
    "сadastralNumber": "",
    "contractNumber": "",
    "contractWithName": "",
    "сontractDateFrom": null,
    "сontractDateTo": null,
    "isOtherTenants": false,
    "comment": "",
    "color": ""
}

Редагування регіонів

Для редагування регіонів є 3 методи, 2 з них для редагування відповідного типу регіона – v3/updRegionCircle, v3/updRegionPolygon та 1, який не лише редагує а й може змінювати тип регіону – v1/updRegion.

Метод – v3/updRegionCircle використовується, щоб відредагувати круговий регіон.

Параметри методу:

  • id – унікальний ідентифікатор регіону, який присвоюється при створенні регіону (не може бути змінений);
  • name – назва регіону;
  • lat – широта центру регіону;
  • lng – довгота центру регіону;
  • radius – радіус регіону (у метрах, більший за 10 м, менший за 32000 м).

Приклад запиту v3/updRegionCircle (використаємо створений круговий регіон) – “Круговий тестовий регіон 1” з id = 68940.

POST https://api.gps-khm.net/v3/updRegionCircle?token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту

{
  "id": 68940,  //id регіону "Круговий тестовий регіон 1"
  "name": "Круговий тестовий регіон 1 (редагований)", //Нова назва регіону
  "lat": 49.733689,  //Нова широта центру регіону
  "lng": 27.378616,  //Нова довгота центру регіону
  "radius": 800  //Новий радіус регіону
}

Відповідь

Status code 200
"Ok"

Після цього регіон має змінитись у Списку регіонів та на Мапі.

Метод – v3/updRegionPolygon використовується, щоб відредагувати регіон довільної форми.

Параметри методу:

  • id – унікальний ідентифікатор регіону, який присвоюється при створенні регіону (не може бути змінений);
  • name – назва регіону;
  • coordinates – координати вершин регіону.

Приклад запиту v3/updRegionPolygon (використаємо створений регіон довільної форми) – “Тестовий регіон довільної форми 1” з id = 68943.

POST https://api.gps-khm.net/v3/updRegionPolygon?token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту

{
  "id": 68943,  //id регіону "Тестовий регіон довільної форми 1"
  "name": "Тестовий регіон довільної форми 1 (редагований)",  //Нове ім'я регіону
  "coordinates": [  //Масив нових координат регіону
    {
      "lat": 49.716488,
      "lng": 27.459640
    }, 
    {
      "lat": 49.707830,
      "lng": 27.481956
    }, 
    {
      "lat": 49.701835,
      "lng": 27.460670
    }, 
    {
      "lat": 49.708496,
      "lng": 27.445907
    }
  ]
}

Відповідь

Status code 200
"Ok"

Після цього регіон має змінитись у Списку регіонів та на Мапі.

Метод – v1/updRegion можна використати не лише для редагування регіону а й для зміни його типу.

Для простішого розуміння принципу зміни регіонів потрібно порівняти вигляд параметрів Кругового регіону та регіону Довільної форми отриманих методом v1/getRegion. У кругового регіону масив verticles містить лише 1 “вершину” (центр регіону) а також має радіус, тому, якщо ми вкажемо при редагуванні регіону кілька вершин та радіус 0, то тип регіону зміниться на Довільної форми. І навпаки, задавши для регіону Довільної форми лише 1 вершину та вказавши радіус регіону (10 м < радіус < 32000 м), регіон змінить тип на Круговий.

Приклад запиту (однаковий для зміни з Кругового типу на Довільної форми та навпаки)

POST https://api.gps-khm.net/v1/updRegion?token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту зміни типу регіону з Кругового на Довільної форми

{
  "ID": 68940,  //id регіону "Круговий тестовий регіон 1"
  "name": "Регіон довільної форми (раніше круговий)", //Нове ім'я регіону
  "radius": 0,
  "verticles": [ //Координати нових вершин регіону
    {
      "regionID": 68940,  //id регіону "Круговий тестовий регіон 1"
      "x": 27.314586,
      "y": 49.746668
    },
    {
      "regionID": 68940,  //id регіону "Круговий тестовий регіон 1"
      "x": 27.326259,
      "y": 49.746003
    },
    {
      "regionID": 68940,  //id регіону "Круговий тестовий регіон 1"
      "x": 27.318019,
      "y": 49.738015
    }
  ]
}

Тіло запиту зміни типу регіону з Довільної форми на Круговий.

{
  "ID": 68943,  //id регіону "Тестовий регіон довільної форми 1"
  "name": "Регіон круговий (раніше довільної форми)", //Нове ім'я регіону
  "radius": 1700,
  "verticles": [  //Координати нового центру регіону
    {
      "regionID": 68943, //id регіону "Тестовий регіон довільної форми 1"
      "x": 27.502212,
      "y": 49.676070
    }
  ]
}

Відповідь

Status code 200
"Ok"

Після цього регіони мають змінитись у Списку регіонів та на Мапі.

Видалення регіонів

Для видалення регіонів обох типів (Кругового чи Довільної форми) доступні 2 методи – v3/delRegion та v1/delRegions.

Метод v3/delRegion – призначений для видалення 1 регіону.

Параметри методу v3/delRegion:

  • id – унікальний ідентифікатор регіону, який йому присвоюється при створенні.

Приклад запиту v3/delRegion (однаковий для обох прикладів) 

POST https://developapi.gps-khm.net/v3/delRegion?token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту для видалення кругового регіону

{
  "id": 68940 //id регіону "Круговий тестовий регіон 1"
}

Тіло запиту для видалення регіону довільної форми

{
  "id": 68943 //id регіону "Тестовий регіон довільної форми 1"
}

Відповідь (однакова для обох прикладів)

Status code 200
"Ok"

Після цього регіони мають зникнути зі Списку регіонів та з Мапи.

Метод v1/delRegions – призначений для видалення кількох регіонів (будь якого типу, можна вказувати ID регіонів різних типів). Також цим методом можна видалити 1 регіон.

Параметри методу:

  • regionIDs – масив унікальних ідентифікаторів id регіонів, які їм присвоюються при створенні.

Приклад запиту v1/delRegions

POST https://developapi.gps-khm.net/v1/delRegions?token={токен отриманий з Особистого кабінету користувача (адміністратора), без фігурних дужок}

Тіло запиту для видалення масиву кругових/регіонів довільної форми (використаємо id створених регіонів методами v3/insRegionsCircle та v3/insRegionsPolygon, для того щоб отримати їхні id скористаємось методом v4/selRegions та у відповіді запиту знайдемо ці регіони по їх назвах).

{
  "regionIDs": [
    68941, //id регіону "Круговий тестовий регіон 2"
    68942, //id регіону "Круговий тестовий регіон 3"
    68944, //id регіону "Тестовий регіон довільної форми 2"
    68945  //id регіону "Тестовий регіон довільної форми 3"
  ]
}

Відповідь

Status code 200
"Ok"

Після цього регіони мають зникнути зі Списку регіонів та з Мапи.

Якщо у Вас виникли складнощі, зверніться до нас за консультацією, тел. 067 312 60 60 або у чат на сайті.