.. title:: Точка входу "Суддя" для API проекту "Суд на долоні"
.. meta::
:desctription: Точка входу "Суддя" для API проекту "Суд на долоні"
:robots: index, follow
:viewport: width=device-width, initial-scale=1
:language: uk
:keywords: Суд на долоні, API, суддя
:author: Кирило Захаров
:copyright: Суд на долоні
Суддя
=====
Точка входу "Суддя" повертає інформацію стосовно суддів України.
Загальна інформація
-------------------
Інформація про суддів з даних Державної судової адміністрації, опублікованих на `відповідному порталі відкритих даних `_.
Унікальним ідентифікатором для кожного судді є певна судова установа та прізвище, ім'я та по батькові судді (або прізвище та ініціали).
Оновлюється за відповідними нормативно-правовими документами, опублікованими на сайті Верховної Ради України.
Кількість суддів
------------------------
GET-запит за адресою ``https://api.conp.com.ua/api/v1.0/judge`` повертає загальну кількість суддів в системі
.. sourcecode:: http
GET /judge HTTP/1.0
Host: https://api.conp.com.ua/api/v1.0
{ "message": 13852 }
-----
Отримання інформації про суддю
---------------------------------
GET-запит за адресою ``https://api.conp.com.ua/api/v1.0/judge/:id`` повертає інформацію про суддю за `відповідною схемою даних `_ `. Де ``id`` - це транслітерована комбінація коду суду та прізвища та ініціалів судді.
.. sourcecode:: http
GET /judge/0590_ahieiev_o__v_ HTTP/1.0
Host: https://api.conp.com.ua/api/v1.0
{
"person": {
"source": "Агєєв Олександр Володимирович",
"idName": "Агєєв О. В.",
"fullName": "Агєєв Олександр Володимирович",
"familyName": "Агєєв",
"givenName": "Олександр",
"additionalName": "Володимирович",
"sex": "чоловік",
"jobTitle": "Голова Апеляційного суду Донецької області (м. Бахмут)",
"idNameRus": "Агеев А. В.",
"fullNameRus": "Агеев Александр В",
"familyNameRus": "Агеев",
"givenNameRus": "Александр",
"additionalNameRus": "В"
},
"courts": [
{
"address": {
"geo": {
"lon": "37.998301",
"lat": "48.589041"
},
"streetAddress": "вулиця Свободи,10",
"postalCode": "84513",
"locality": "місто Бахмут",
"fullAddress": "84513, Донецька область, місто Бахмут, вулиця Свободи,10",
"source": "84500, м. Бахмут, вул. Свободи,10",
"countryName": "Україна",
"region": "Донецька область",
"oldLocality": "місто Артемівськ"
},
"courtName": "Апеляційний суд Донецької області",
"courtCode": "0590",
"phone": [
"+38 (062) 744 50 26",
"+38 (062) 744 50 24",
"+38 (062) 744 51 44",
"+38 (062) 744 51 57"
],
"instanceType": "Апеляційна",
"organization": {
"legalName": "АПЕЛЯЦІЙНИЙ СУД ДОНЕЦЬКОЇ ОБЛАСТІ",
"head": {
"idName": "Лісовий О. О.",
"familyName": "Лісовий",
"givenName": "Олександр",
"sex": "чоловік",
"jobTitle": "Директор",
"fullName": "Лісовий Олександр Олександрович",
"source": "ЛІСОВИЙ ОЛЕКСАНДР ОЛЕКСАНДРОВИЧ",
"additionalName": "Олександрович"
},
"identifier": {
"valid": true,
"scheme": "UA-EDR",
"id": "02891428"
},
"address": {
"streetNumber": "1-А",
"streetAddress": "проспект Миру, 1-А",
"postalCode": "87500",
"district": "Центральний район",
"locality": "місто Маріуполь",
"fullAddress": "87500, Донецька область, місто Маріуполь, проспект Миру, 1-А",
"source": "87500, Донецька обл., місто Маріуполь, Центральний район, ПРОСПЕКТ МИРУ, будинок 1-А",
"countryName": "Україна",
"region": "Донецька область"
},
"currentStatus": "зареєстровано",
"numberOfFounders": 1,
"name": "АПЕЛЯЦІЙНИЙ СУД ДОНЕЦЬКОЇ ОБЛАСТІ",
"kved": {
"part": "84",
"group": "23"
},
"founders": [
{
"organization": {
"name": "Державна Судова Адміністрація України",
"source": "ДЕРЖАВНА СУДОВА АДМІНІСТРАЦІЯ УКРАЇНИ"
},
"source": "ДЕРЖАВНА СУДОВА АДМІНІСТРАЦІЯ УКРАЇНИ, розмір внеску до статутного фонду - 0.00 грн."
}
],
"full_kved": "84.23 Діяльність у сфері юстиції та правосуддя",
"updatedAt": "2018-08-10T12:30:10.548Z"
},
"courtRegion": "Донецька область",
"openingHours": [
"Пн-Чт з 08:00 до 17:00",
"Пт з 08:00 до 15:45",
"Перерва з 12:00 до 12:45"
],
"url": "http://dna.court.gov.ua/sud0590/",
"email": "inbox@dna.court.gov.ua",
"updatedAt": "2018-08-10T13:15:42.915Z"
}
],
"id": "0590_ahieiev_o__v_",
"updatedAt": "2018-08-10T15:19:57.947Z"
}
-----
Пошук суддів
--------------------
POST-запит за адресою ``https://api.conp.com.ua/api/v1.0/judge/search`` дозволяє шукати суддів.
POST-запит має містити JSON з наступними змінними
:query:
рядок
Перелік термінів для повнотекстового пошуку.
:defaultOperator:
рядок
Приймає значення ``or`` або ``and``, щоб шукати будь-який з термінів для повнотекстового пошуку або усі терміни.
:filter:
об'єкт
Об'єкт, який містить перелік усіх пошукових фільтрів, встановлених користувачем.
:sort:
об'єкт
Об'єкт, який визначає порядок сортування результатів.
:from:
ціле число (integer)
Кількість об'єктів, яку необхідно пропустити (використовується для пагінації).
:aggregation:
булеве значення
Якщо встановлено значення ``false``, то в результаті буде отримано перелік суддів, які відповідають повнотекстовому запиту та фільтрам. Якщо встановлено значення ``true``, то повертає перелік агрегацій для фасетного пошуку.
Фільтри
~~~~~~~
Кожен з фільтрів має бути об'єктом з певною назвою (поле, за яким відбувається фільтрація) та будуватися за схемою:
:list:
масив рядків
Перелік точних значень термінів для фільтрації результату.
:operator:
рядок
Приймає значення ``or`` або ``and``, щоб у результат попадали сутності з будь-яким зі значень фільтру або усі значення фільтру.
Суддів можна фільтрувати за точними значеннями таких змінних:
* **instanceType** - Інстанція суду
* **courtName** - Назва суду
* **sex** - Стать судді
* **address.region** - Область адреси суду
* **address.district** - Район або район у місті адреси суду
* **address.locality** - Населений пункт адреси суду
* **address.fullAddress** - Повна адреса суду
* **address.currentStatus** - Поточний статус суду
Приклад використання фільтру - "(1) Тільки судді-жінки (2) судів першої інстанції (3) міста Харків":
.. sourcecode:: http
...
{ "filter": {
"instanceType": {
"list": [
"Перша"
],
"operator": "or"
},
"sex": {
"list": [
"жінка"
],
"operator": "or"
},
"address.locality": {
"list": [
"місто Харків"
],
"operator": "or"
}
}
...
Сортування
~~~~~~~~~~
Для суддів дозволено сортування за повним іменем. Якщо змінна ``sort`` у запиті має значення ``{}``, то сортування відбуватиметься за релевантністю.
Приклад сортування за повним іменем:
.. sourcecode:: http
...
"sort": {
"person.fullName.sort": { "order": "asc" }
}
...
Агрегація
~~~~~~~~~
Для суддів передбачено агрегацію за такими змінними:
* Інстанція суду
* Область суду
* Населений пункт суду
* Район суду
* Стать судді
Агрегації розраховуються автоматично для усіх змінних, для яких встановлено фільтр. Якщо необхідно отримати агрегацію без фільтрації, то необхідно задати "пустий" фільтр таким чином:
.. sourcecode:: http
...
"filter": {
"instanceType": {
"list": [],
"operator": "or"
}
}
...
Приклад повного запиту та відповіді
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. sourcecode:: http
POST /judge/search HTTP/1.0
Host: https://api.conp.com.ua/api/v1.0
{
"query": "",
"defaultOperator": "or",
"filter": {
"instanceType": {
"list": [
"Апеляційна"
],
"operator": "or"
},
"courtName": {
"list": [],
"operator": "or"
},
"fullName": {
"list": [],
"operator": "or"
},
"sex": {
"list": [
"чоловік"
],
"operator": "or"
},
"address.region": {
"list": [],
"operator": "or"
},
"address.district": {
"list": [],
"operator": "or"
},
"address.locality": {
"list": [
"місто Дніпро"
],
"operator": "or"
},
"address.fullAddress": {
"list": [],
"operator": "or"
},
"organization.currentStatus": {
"list": [],
"operator": "or"
}
},
"searchIndex": "judge",
"aggregation": true
}
{
"aggs": {
"address.locality": [],
"compound": {},
"address.district": [
{
"key": "Бабушкінський район",
"doc_count": 35
},
{
"key": "Жовтневий район",
"doc_count": 18
},
{
"key": "Шевченківський район",
"doc_count": 14
}
],
"courtName": [
{
"key": "Апеляційний суд Дніпропетровської області",
"doc_count": 34
},
{
"key": "Дніпропетровський апеляційний адміністративний суд",
"doc_count": 18
},
{
"key": "Дніпропетровський апеляційний господарський суд",
"doc_count": 14
},
{
"key": "Апеляційний суд Дніпропетровської області (м. Кривий Ріг)",
"doc_count": 1
}
],
"address.region": [
{
"key": "Дніпропетровська область",
"doc_count": 67
}
],
"instanceType": [],
"sex": []
},
"total": 67
}