.. title:: Точка входу "Прокурор" для API проекту "Суд на долоні"

.. meta::
    :desctription: Точка входу "Прокурор" для API проекту "Суд на долоні"
    :robots: index, follow
    :viewport: width=device-width, initial-scale=1
    :language: uk
    :keywords: Суд на долоні, API, прокурор
    :author: Кирило Захаров
    :copyright: Суд на долоні

Прокурор
========

Точка входу "Прокурор" повертає інформацію стосовно працівників прокуратури України.

Загальна інформація
-------------------

Інформація щодо працівників прокуратори. Оновлюється раз на місяць з даних `Єдиного державного реєстру декларацій осіб, уповноважених на виконання функцій держави або місцевого самоврядування <https://public.nazk.gov.ua/search>`_.


Кількість прокурорів
--------------------

GET-запит за адресою ``https://api.conp.com.ua/api/v1.0/prosecutor`` повертає загальну кількість прокурорів в системі

.. sourcecode:: http

  GET /prosecutor HTTP/1.0
  Host: https://api.conp.com.ua/api/v1.0

  { "message": 6855 }

-----

Отримання інформації про прокурорів
-----------------------------------

GET-запит за адресою ``https://api.conp.com.ua/api/v1.0/prosecutor/:id`` повертає інормацію про прокурора за `відповідною схемою даних <prosecutor.html>`_ `. Де ``id`` - це транслітерована комбінація регіону прокуратури та ПІБ прокурора.

.. sourcecode:: http

  GET /prosecutor/cholovskyi_vladyslav_mykolaiovych_zahalnoderzhavnyi HTTP/1.0
  Host: https://api.conp.com.ua/api/v1.0

  { 
    person: { 
      source: 'Чоловський Владислав Миколайович',
      idName: 'Чоловський В. М.',
      fullName: 'Чоловський Владислав Миколайович',
      familyName: 'Чоловський',
      givenName: 'Владислав',
      additionalName: 'Миколайович',
      sex: 'чоловік',
      jobTitle: 'Слідчий в особливо важливих справах другого слідчого відділу слідчого управління Генеральної прокуратури України',
      worksFor: { 
        source: 'Головна військова прокуратура',
        name: 'Головна військова прокуратура' 
      } 
    },
    procuracyRegion: 'Загальнодержавний',
    id: 'cholovskyi_vladyslav_mykolaiovych_zahalnoderzhavnyi',
    updatedAt: '2018-08-07T09:34:47.122Z' 
  }

-----


Пошук прокурорів
--------------------------

POST-запит за адресою ``https://api.conp.com.ua/api/v1.0/prosecutor/search`` дозволяє шукати прокурорів.

POST-запит має містити JSON з наступними змінними

:query:
    рядок
    
    Перелік термінів для повнотекстового пошуку.

:defaultOperator:
    рядок
    
    Приймає значення ``or`` або ``and``, щоб шукати будь-який з термінів для повнотекстового пошуку або усі терміни.

:filter:
    об'єкт
    
    Об'єкт, який містить перелік усіх пошукових фільтрів, встановлених користувачем.

:sort:
    об'єкт
    
    Об'єкт, який визначає порядок сортування результатів.

:from:
    ціле число (integer)
    
    Кількість об'єктів, яку необхідно пропустити (використовується для пагінації).

:aggregation:
    булеве значення
    
    Якщо встановлено значення ``false``, то в результаті буде отримано перелік прокурорів, які відповідають повнотекстовому запиту та фільтрам. Якщо встановлено значення ``true``, то повертає перелік агрегацій для фасетного пошуку.

Фільтри
~~~~~~~

Кожен з фільтрів має бути об'єктом з певною назвою (поле, за яким відбувається фільтрація) та будуватися за схемою:

:list:
    масив рядків
    
    Перелік точних значень термінів для фільтрації результату.

:operator:
    рядок
    
    Приймає значення ``or`` або ``and``, щоб у результат попадали сутності з будь-яким зі значень фільтру або усі значення фільтру.

Прокурорів можна фільтрувати за точними значеннями таких змінних:

* **worksFor** - Організація, в якій працює
* **address.region** - Область, в якій працює прокурор
* **sex** - Стать прокурора

Приклад використання фільтру - "(1) Працівники Генеральної Прокуратури України, (2) що є жінками":

.. sourcecode:: http

  ...
  { "filter": {
    "sex": {
      "list": [
        "жінка"
      ],
      "operator": "or"
    },
    "worksFor": {
      "list": [
        "Генеральна Прокуратура України"
      ],
      "operator": "or"
    }
  }
  ...

Сортування
~~~~~~~~~~

Для прокурорів дозволено сортування за повним іменем (`person.fullName.sort`). Якщо змінна ``sort`` у запиті має значення ``{}``, то сортування відбуватиметься за релевантністю.

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

.. sourcecode:: http
  
  ...
  "sort": {
    "person.fullName.sort": { "order": "desc" }
  }
  ...

Агрегація
~~~~~~~~~

Для прокурорів передбачено агрегацію за такими змінними:

* Місце роботи
* Область прокуратури
* Стать прокурора

Агрегації розраховуються автоматично для усіх змінних, для яких встановлено фільтр. Якщо необхідно отримати агрегацію без фільтрації, то необхідно задати "пустий" фільтр таким чином:

.. sourcecode:: http

  ...
  "filter": {
    "sex": {
      "list": [],
      "operator": "or"
    }
  }
  ...


Приклад повного запиту та відповіді
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. sourcecode:: http

  POST /arbitrage/search HTTP/1.0
  Host: https://api.conp.com.ua/api/v1.0

  {
    "query": "",
    "defaultOperator": "or",
    "filter": {
      "fullName": {
        "list": [],
        "operator": "or"
      },
      "sex": {
        "list": [],
        "operator": "or"
      },
      "address.region": {
        "list": [
          "місто Київ"
        ],
        "operator": "or"
      },
      "worksFor": {
        "list": [
          "Київська місцева прокуратура № 4 (Дніпровський район)"
        ],
        "operator": "or"
      }
    },
    "searchIndex": "prosecutor",
    "aggregation": true
  }

  {
    "aggs": {
      "worksFor": [],
      "compound": {},
      "sex": [
        {
          "key": "жінка",
          "doc_count": 28
        },
        {
          "key": "чоловік",
          "doc_count": 28
        }
      ],
      "address.region": []
    },
    "total": 56
  }