Перелік середовищ (host):
\nПрод - https://api.address.gov.ua/
\n[host]/api-user/edraHistory/[type]?id=[id]&from=[from]&to=[to]\n\nЗагальний опис API
\nAPI надає можливість вивантажувати дані (адрес, вулиць і об'єктів АТУ) у вигляді архіву з відповідним типом файлів (json або xml) за територіальною одиницею за вказаний період (або увесь час). Якщо файлу з історією змін за вказаними параметрами користувача не існує, або якщо параметри співпадають, але файл згенерований більше тижня тому - то система формує новий файл. Якщо ж файл згенерований в системі і за вказаними параметрами користувача створений менше тижня тому - то він буде вивантажений користувачу. Файл формується у evenStream.
\nПри використанні апі відображаються усі версії об'єктів. Обрати конкретну версію в ендпоінті не можна
\nОпис перевірок
\nAPI має перевірки на наявність та валідність параметрів
\ntype - при його відсутності користувач отримує помилку (param type is required). Якщо параметр не json/xml - користувач отримає помилку (param type is invalid)
\nfrom, to - при вказанні не валідного проміжку - користувач отримає помилку (invalid params: [date] is not a valid date)
\nid - за відсутності параметру користувач отримає помилку (not enough query params: id)
\nОпис dateType
\nfact - фільтрація відбувається в проміжку вказаних дат у параметрах from,to за фактичною зміною об'єкта в БД.
plan - фільтрація відбувається в проміжку вказаних дат у параметрах from,to за юридичною датою об'єкта, з якої вступає в чинність.
Ідентифікатор об'єкта АТУ(Область,Район, ТГ, Населені пункти, Райони в місті)
\n","type":"text/plain"},"key":"id","value":"81797"},{"description":{"content":"Дата початку періоду за який вивантажуємо
\n","type":"text/plain"},"key":"from","value":"2023-01-01"},{"description":{"content":"Дата кінця періода за який вивантажуємо
\n","type":"text/plain"},"key":"to","value":"2023-06-02"},{"disabled":true,"description":{"content":"Тип повідомлення (progress, detail)
\n","type":"text/plain"},"key":"messageType","value":""},{"disabled":true,"description":{"content":"Означка, чи повертати результат одним файлом чи багатьма (concat, separate)
\n","type":"text/plain"},"key":"resultFile","value":""},{"disabled":true,"description":{"content":"Скасовує поточну генерацію даних та запускає знову
\n","type":"text/plain"},"key":"reload","value":""},{"description":{"content":"Параметр глибини запиту (atu|streets|address). \nЯкщо вказано atu то вивантажить тільки АТУ;\nЯкщо вказано streets то вивантажить АТУ та вулиці;\nЯкщо вказано address то вивантажить АТУ, вулиці та адреси;
\n","type":"text/plain"},"key":"depth","value":"address"},{"disabled":true,"description":{"content":"Тип дати для фільтрації даних (fact,plan). По замовчуванню fact
\n","type":"text/plain"},"key":"dateType","value":""}],"variable":[{"id":"dc267ffa-02ae-449a-8060-b20cbfcbf5f4","description":{"content":"Відповідає за формат вихідних файлів (xml/json)
\n","type":"text/plain"},"type":"any","value":"json","key":"type"}]}},"response":[{"id":"9991eb1a-8ca1-4a22-b29a-4236802c0bc2","name":"Підготовка архіву до скачування","originalRequest":{"method":"GET","header":[],"url":{"raw":"[host]/api-user/edraHistory/:type?id=81797&from=2023-01-01&to=2023-06-02","host":["[host]"],"path":["api-user","edraHistory",":type"],"query":[{"key":"id","value":"81797","description":"Ідентифікатор населеного пункту"},{"key":"from","value":"2023-01-01","description":"Датат початку періоду за який вивантажуємо"},{"key":"to","value":"2023-06-02","description":"Дата кінця періода за який вивантажуємо"}],"variable":[{"key":"type","value":"json","description":"Відповідає за формат вихідних файлів (xml/json)"}]}},"status":"OK","code":200,"_postman_previewlanguage":"plain","header":[{"key":"Server","value":"nginx"},{"key":"Date","value":"Wed, 03 May 2023 08:24:33 GMT"},{"key":"Content-Type","value":"text/event-stream; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache"}],"cookie":[],"responseTime":null,"body":"data: Select history info\n\ndata: Creating jsons\n\ndata: Creating archive\n\ndata: Finish:Zip is complete. Press F5 to download\n\n"},{"id":"5a9cdd43-e78f-40fe-a183-97649e2d5810","name":"Скачування файлу","originalRequest":{"method":"GET","header":[],"url":{"raw":"[host]/api-user/edraHistory/:type?id=81797&from=2023-01-01&to=2023-06-02","host":["[host]"],"path":["api-user","edraHistory",":type"],"query":[{"key":"id","value":"81797","description":"Ідентифікатор населеного пункту"},{"key":"from","value":"2023-01-01","description":"Датат початку періоду за який вивантажуємо"},{"key":"to","value":"2023-06-02","description":"Дата кінця періода за який вивантажуємо"}],"variable":[{"key":"type","value":"json","description":"Відповідає за формат вихідних файлів (xml/json)"}]}},"status":"OK","code":200,"_postman_previewlanguage":"raw","header":[{"key":"Server","value":"nginx"},{"key":"Date","value":"Wed, 03 May 2023 08:25:13 GMT"},{"key":"Content-Type","value":"application/zip"},{"key":"Content-Length","value":"762657"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"public, max-age=0"},{"key":"Last-Modified","value":"Wed, 03 May 2023 08:24:37 GMT"},{"key":"ETag","value":"W/\"ba321-187e0b6a068\""},{"key":"Accept-Ranges","value":"bytes"}],"cookie":[],"responseTime":null,"body":"Викачує файл (якщо він був сформований 24 години тому)"},{"id":"000613cf-843e-47db-9eab-9c2ee65223eb","name":"Body сформованого файлу","originalRequest":{"method":"GET","header":[],"url":{"raw":"[host]/api-user/edraHistory/:type?depth=address&id=40190&resultFile=concat","host":["[host]"],"path":["api-user","edraHistory",":type"],"query":[{"key":"messageType","value":"","description":"Тип повідомлення (progress, detail)","disabled":true},{"key":"resultFile","value":"","description":"Означка, чи повертати результат одним файлом чи багатьма (concat, separate)","disabled":true},{"key":"reload","value":"","description":"Скасовує поточну генерацію даних та запускає знову","disabled":true},{"key":"depth","value":"address","description":"Параметр глибини запиту (atu|streets|address). \nЯкщо вказано atu то вивантажить тільки АТУ;\nЯкщо вказано streets то вивантажить АТУ та вулиці;\nЯкщо вказано address то вивантажить АТУ, вулиці та адреси;"},{"key":"dateType","value":"","description":"Тип дати для фільтрації даних (fact,plan). По замовчуванню fact","disabled":true},{"key":"id","value":"40190"},{"key":"resultFile","value":"concat"}],"variable":[{"key":"type","value":"json"}]}},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"atu\": [\n {\n \"atu_id\": \"3321463574483699634\",\n \"external_id\": \"40190\",\n \"name\": \"Щітки\",\n \"type\": 504,\n \"level\": 5,\n \"namespace\": \"UA.ATU.M\",\n \"parent\": \"3321463570742379982\",\n \"version\": \"001\",\n \"date_from\": \"2020-11-26 00:00:00\",\n \"date_to\": \"2026-02-06 11:29:17.509614\",\n \"katottg\": \"UA05020030090040190\",\n \"koatuu\": null,\n \"comment\": null,\n \"status\": 4,\n \"occupation_status\": null,\n \"cdate\": \"2024-03-11 17:02:14.466188\",\n \"editor_date\": \"2026-02-06 11:29:17.509614\",\n \"adm_center\": null,\n \"statut_communities\": null,\n \"is_last_version\": false,\n \"nais_atu_id\": \"1953\",\n \"atu_id_from\": null,\n \"atu_id_to\": null,\n \"change_type\": null,\n \"nais_ach_type\": null\n },\n {\n \"atu_id\": \"3826463989651474252\",\n \"external_id\": \"40190\",\n \"name\": \"Щіточки\",\n \"type\": 504,\n \"level\": 5,\n \"namespace\": \"UA.ATU.M\",\n \"parent\": \"3321463570742379982\",\n \"version\": \"002\",\n \"date_from\": \"2026-02-06 11:27:55.421373\",\n \"date_to\": null,\n \"katottg\": \"UA05020030090040190\",\n \"koatuu\": null,\n \"comment\": null,\n \"status\": 3,\n \"occupation_status\": null,\n \"cdate\": \"2026-02-06 11:27:55.421373\",\n \"editor_date\": \"2026-02-06 11:29:17.509614\",\n \"adm_center\": null,\n \"statut_communities\": null,\n \"is_last_version\": true,\n \"nais_atu_id\": null,\n \"atu_id_from\": \"3321463574483699634\",\n \"atu_id_to\": \"3826463989651474252\",\n \"change_type\": 2,\n \"nais_ach_type\": null\n }\n ],\n \"street\": [\n {\n \"str_id\": \"3359336555767399954\",\n \"external_id\": \"0708369\",\n \"namespace\": \"UA.ADR.S\",\n \"parent\": \"3321463574483699634\",\n \"version\": \"001\",\n \"level\": 7,\n \"type\": 1,\n \"date_from\": \"2004-04-09 00:00:00\",\n \"date_to\": \"2015-11-24 00:00:00\",\n \"comment\": null,\n \"status\": 4,\n \"name\": \"Леніна\",\n \"name_eng\": null,\n \"cdate\": \"2024-05-03 00:07:19.228477\",\n \"editor_date\": null,\n \"edrato_id\": \"3321463574483699634\",\n \"no_id\": null,\n \"nais_atu_id\": \"447486\",\n \"is_last_version\": false,\n \"str_id_from\": null,\n \"str_id_to\": null,\n \"change_type\": null,\n \"nais_ach_type\": null,\n \"alternative_id\": null\n }\n ],\n \"address\": [\n {\n \"addr_id\": \"3354283046269355325\",\n \"external_id\": \"9355324\",\n \"namespace\": \"UA.ADR.B\",\n \"parent\": \"3354283046269355324\",\n \"version\": \"001\",\n \"level\": 8,\n \"type\": 1,\n \"date_from\": \"2004-04-09 00:00:00\",\n \"date_to\": \"2026-02-06 11:29:17.509614\",\n \"comment\": null,\n \"status\": 4,\n \"addr_num\": \"4\",\n \"post_index\": null,\n \"is_corner\": false,\n \"corner_str_id\": null,\n \"corner_address\": null,\n \"district_id\": null,\n \"cdate\": \"2024-05-03 13:21:27.924623\",\n \"editor_date\": \"2026-02-06 11:29:17.509614\",\n \"is_last_version\": false,\n \"addr_id_from\": null,\n \"addr_id_to\": null,\n \"change_type\": null,\n \"alternative_id\": [\n {\n \"id\": \"6235674d-ea75-41d9-b094-8f7882f61359\",\n \"register_name\": \"mvs\",\n \"addr_num\": \"4\"\n },\n {\n \"id\": \"3732380444407105427\",\n \"register_name\": \"dpa\",\n \"addr_num\": \"4\"\n }\n ]\n }\n ]\n}"}],"_postman_id":"17566210-85ba-4987-ac7f-8bb4c2bbe022"}],"id":"f961f18a-4b8c-4524-8745-835fc8785ade","description":"Цей розділ містить перелік методів для роботи з ресурсами системи EDRA через REST інтерфейс. Всі запити повертають дані у форматі JSON (або XML за запитом).
\nНижче наведено загальні коди відповідей та категорії помилок, які можуть виникати під час взаємодії з API.
\n","_postman_id":"f961f18a-4b8c-4524-8745-835fc8785ade"},{"name":"OAUTH2.0","item":[{"name":"OauthGetToken","id":"308d0524-374d-421a-b739-d66c484f53f3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"clientId","value":"qwerty123","type":"text"},{"key":"clientSecret","value":"qwerty123","type":"text"}]},"url":"[host]/api-user/oauth/token","description":"[host]/api-user/oauth/token\n\nАПІ надає можливість отримання токена для подальших запитів до системи за схемою OAUTH 2.0. Для того, щоб отримати токен потрібно:
\nОтримати clientSecrete та clientId від адміністратора системи
\nПередати отримані параметри у запит, як це показано у наведеному прикладі
\nОтримати токен у параметрі відповуді access_token
\nДля виконання запиту до системи використовуючи токен потрібно:
\nОтримати токен за схемою, яка описана вище
\nПередати токен у заголовок запиту Authorization у вигляді строки наступного вигляду: Bearer <отриманий токен>
\nУ системі реалізовано доступ до API за схемою OAuth 2.0.
\nДля отримання токена доступу необхідно виконати POST-запит за ендпоінтом:
\n/api-user/oauth/token\n\nУ body запиту передаються такі параметри:
\nclientId — ідентифікатор клієнта
clientSecret — секретний ключ клієнта
{\n \"access_token\": \"<token>\"\n}\n\nДля доступу до методів API отриманий токен необхідно передавати у HTTP-заголовку Authorization.
Формат передачі токена:
\nAuthorization: Bearer <access_token>\n\nУ разі успішного виконання запиту API повертає токен доступу та час його дії:
\n{\n \"access_token\": \"<token>\",\n \"lifetime\": 3600,\n \"status\": 200\n}\n\n\nде:
\naccess_token — токен доступу до API
lifetime — час дії токена у секундах
status — HTTP-статус виконання запиту
Кожна операція з отримання токену логується, а логи записуютсья у <тека коду сервера>/log/auth/oauth/<дата>. Лог являє собою файл з такими полями:
timestamp - дата створення запису у лог
\nname - назва
\nhostname - сайт до якого було здійснено запит
\nip - IP-адреса з якої прийшов запит
\nlevel - рівень логу (INFO, DEBUG, ERROR)
\nresp_code - http-код відповіді
\nresponse - відповідь (записується якщо виникла помилка запиту)
\nМетод EdraHistory генерує 3 типи файлів: address, street та atu. Нижче надано описи структур цих файлів.
\nСтатуси помилок API
\n","_postman_id":"89344515-59a6-45a3-9d3b-17f7a7aa6166"}],"event":[{"listen":"prerequest","script":{"id":"17ec45e5-321c-46bd-a599-2e35bd6493dc","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"d84894f4-2bed-43ea-9f0e-9a32ec1b07fd","type":"text/javascript","exec":[""]}}],"variable":[{"key":"publicUrl","value":"[host]","type":"string"},{"key":"test","value":"https://edratest.e-construction.gov.ua","type":"string"},{"key":"prod","value":"https://cabinet.address.gov.ua","type":"string"},{"key":"stage","value":"https://edrastage.e-construction.gov.ua","type":"string"},{"key":"local","value":"http://admin.edra.local.softpro.ua","type":"string"}]}