РОЗРОБНИКАМ

Що таке відкриті дані?

Закон України «Про доступ до публічної інформації» № 2939-VI від 13.01.2011 регламентує питання відкритих даних наступним чином:

Публічна інформація у формі відкритих даних - це публічна інформація у форматі, що дозволяє її автоматизоване оброблення електронними засобами, вільний та безоплатний доступ до неї, а також її подальше використання.

Розпорядники інформації зобов’язані надавати публічну інформацію у формі відкритих даних на запит, оприлюднювати і регулярно оновлювати її на єдиному державному веб-порталі відкритих даних та на своїх веб-сайтах.

Публічна інформація у формі відкритих даних є дозволеною для її подальшого вільного використання та поширення.

Будь-яка особа може вільно копіювати, публікувати, поширювати, використовувати, у тому числі в комерційних цілях, у поєднанні з іншою інформацією або шляхом включення до складу власного продукту, публічну інформацію у формі відкритих даних з обов’язковим посиланням на джерело отримання такої інформації.

Які існують формати даних?

Відповідно до Положення про набори даних, які підлягають оприлюдненню у формі відкритих даних, затвердженого постановою Кабінету Міністрів України від 21.10.2015 № 835 визначено наступні формати для оприлюднення публічної інформації у формі відкритих даних:

  • Текстові дані TXT, RTF, ODT*, DOC(X), PDF (з текстовим змістом, не скановане зображення), (X)HTML*
  • Структуровані дані RDF*, XML*, JSON*, CSV*, XLS(X), ODS *, YAML*
  • Графічні дані GIF*, TIFF, JPG (JPEG)*, PNG*
  • Відеодані MPEG, MKV, AVI, FLV, MKS,MK3D
  • Аудіодані MP3, WAV, MKA
  • Дані, розроблені з використанням програми Macromedia Flash SWF, FLV
  • Архів даних ZIP*, 7z*, Gzip*, Bzip2*

При створенні нових наборів даних забезпечується використання відкритих форматів даних (формати, позначені * у таблиці) та структурованих даних (формати RDF, XML, JSON, CSV).

Робота з файлами наборів даних (ресурсами) на основі API

Наш портал надає стороннім Web ресурсам та мобільним програмним додаткам можливість доступу до своїх, об'єднаних у набори даних, ресурсам через інтерфейс прикладного програмування (server-side Web АРІ). З цією метою в паспорті кожного опублікованого на порталі набору даних указується гіперпосилання на наявні на ньому ресурси. За допомогою цього гіперпосилання в паспорті кожного набору даних може бути реалізований базовий запит на одержання повного обсягу ресурсів, що маються в цьому наборі. За рідкісним винятком, у випадку, якщо ресурси набору даних представлені файлами не машинозчитуваних форматів, у паспорті цього набору може вказуватися звичайне посилання на наявні в ньому файли ресурсів.

Застосовуваний на нашому порталі механізм server-side Web АРІ запитів сумісний з можливостями API CKAN Datastore. Єдиним недоліком Одеського порталу Відкритих даних є те, що в рамках API CKAN Datastore підтримуються також й POST запити, тоді як даний портал підтримує лише GET запити.

Усі запити для нашого порталу можуть бути відправлені через HTTP. У відповідь же на ці запити дані можуть бути повернуті у виді вибірки або у форматі JSON, чи у форматі XML.

Зразок базового гіперпосилання на ресурс набору даних з використанням інтерфейсу прикладного програмування (API URL)

Ресурси, якого або набору даних можуть бути запитані по такій базовій адресі, як: http://data.ngorg.od.ua/api/action/datastore/search

За замовчуванням завдяки вищезгаданому запиту повертаються дані у форматі XML. Якщо необхідно, щоб дані поверталися у форматі JSON, то наприкінці вищенаведеної адреси необхідно приписати .json. Так, наприклад, така адреса буде виглядати як: http://data.ngorg.od.ua/api/action/datastore/search.json.

Отримані результати запитів у форматі JSON завжди можна подивитися за допомогою Web сервісу: http://json.bloople.net/, який дозволяє візуалізувати дані формату JSON у виді HTML сторінки

Параметри запиту

HTTP адреса будь-якого запиту може містити наступні параметри:

  • resource_id (змішаний формат) - ідентифікаційний номер, по якому здійснюється пошук необхідного набору даних (ресурсу)
  • filters (змішаний формат) - масив чи рядок, відповідно до якого формується вибірка даних з відповідного ресурсу в наборі даних
  • q (рядок) –  рядок для пошуку по тексту, завдяки якому формується вибірка зі співпадаючих з цим рядком рядків ресурсу в наборі даних*
  • offset (ціле) – кількість рядків, які потрібно пропустити в результаті запиту
  • limit (ціле) - максимальна кількість рядків, що повертаються, у результаті запиту (за замовчуванням: 100)
  • fields ( масив чи рядок найменувань полів, розділених комами) – поля, що будуть повернуті в результаті запиту (за замовчуванням повертаються всі поля в такому ж порядку, як вони представлені в ресурсі)
  • sort (рядок) – розділені комами найменування полів, за якими буде проводитися впорядковування в результаті запиту
  • join (масив) - масив найменувань полів з різних таблиць (ресурсів), що у результаті запиту повинні об'єднатися в єдину таблицю

Значення, що повертаються

Як уже говорилося, у результаті зроблених запитів, значення можуть бути повернуті в таких форматах, як JSON  чи XML. При цьому, для того, щоб уточнити номенклатуру, обсяги та специфіку об'єднання декількох ресурсів у результаті зробленої вибірки можна використовувати словник з наступними ключами:

  • fields (список полів) - поля / колонки та метадані
  • offset (ціле) – значення зсуву запитів
  • limit (ціле) - граничне значення обсягу запиту
  • count (ціле) - загальна кількість оброблюваних записів при формуванні запиту
  • records (список словників) - список результатів зіставлення

Приклади

Нижче приведений простий приклад із двома ресурсами, кожний з яких містить по 4 записи. Будь ласка, зверніть увагу на те, що в реальній ситуації resource_id (позначення ресурсів 1 і 2) має багато символьний шифр у форматі UUID.

Ресурс: 1
+ --------------------- + --------- + -- + ---------- +
|         Країна        | Населення | ID |    Мітка   |
+ --------------------- + --------- + -- + ---------- +
| США                   | 315209000 |  1 | 1359062329 |
| Канада                | 35002447  |  2 | 1359062329 |
| Тихоокеанський_регіон | 40117096  |  3 | 1359062329 |
| Японія                | 127520000 |  4 | 1359062329 |
+ --------------------- + --------- + -- + ---------- +
Ресурс: 2
+ --------------------- + ------------ + -- + ---------- +
|         Країна        | Площа(кв.км) | ID |    Мітка   |
+ --------------------- + ------------ + -- + ---------- +
| США                   |   9629091    |  1 | 1359062713 |
| Канада                |   9984670    |  2 | 1359062713 |
| Тихоокеанський_регіон |   2780400    |  3 | 1359062713 |
| Японія                |   377930     |  4 | 1359062713 |
+ --------------------- + ------------ + -- + ---------- + 

Простий приклад запиту:

http://data.ngorg.od.ua/api/dataset/search?resource_id=1&filters[country]=Тихоокеанський_регіон,США&fields=Країна,Населення,Мітка&sort[country]=asc

Даний запит повертає з першого ресурсу (набору даних) такі стовпчики, як Країна, Населення та Метка з даними по США і Тихоокеанському регіону, відсортованими по стовпчику Країна в порядку зростання.

Пошук по тексту

Для здійснення пошуку по тексту потрібно використовувати параметр query (q). У результаті застосування цього параметру будуть виведені все рядки, де в заданих колонках є рядок для пошуку по тексту, зазначений у параметрі query.

http://data.ngorg.od.ua/api/dataset/search?resource_id=1&&fields=Країна,Населення&query=США

Даний запит повертає з першого ресурсу колонку Країна і колонку Населення з рядками, у яких міститься текст – “США”.

Об'єднання

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

http://data.ngorg.od.ua/api/dataset/search?resource_id[pop]=1&resource_id[size]=2&filters[pop][Країна]=США,Тихоокеанський_регіон&join[pop]=Країна&join[size]=Країна

Даний запит повертає інформацію з першого та другого ресурсу по таких колонкам, як Країна, Населення, Площа (кв.км) і ID для США та Тихоокеанського регіону.

Робота з наборами даних на основі API

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

  1. Гіперпосилання на ресурси набору даних
  2. Гіперпосилання на паспорт та опис ресурсу набору даних

1) Гіперпосилання на ресурси набору даних для їхнього завантаження чи вибірки за допомогою server-side Web АРI

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

Гіперпосилання може містити, як параметри запиту, так і словник, що визначає номенклатуру, обсяги і специфіку об'єднання декількох ресурсів при поверненні значень за результатами зробленої вибірки.

Параметри запиту:

  • resource_id (змішаний формат) - ідентифікаційний номер, по якому здійснюється пошук необхідного набору даних (ресурсу)
  • filters (змішаний формат) - масив чи рядок, відповідно до якого формується вибірка даних з відповідного ресурсу в наборі даних
  • q (рядок) –  рядок для пошуку по тексту, завдяки якому формується вибірка зі співпадаючих з цим рядком рядків ресурсу в наборі даних*
  • offset (ціле) – кількість рядків, які потрібно пропустити в результаті запиту
  • limit (ціле) - максимальна кількість рядків, що повертаються, у результаті запиту (за замовчуванням: 100)
  • fields ( масив чи рядок найменувань полів, розділених комами) – поля, що будуть повернуті в результаті запиту (за замовчуванням повертаються всі поля в такому ж порядку, як вони представлені в ресурсі)
  • sort (рядок) – розділені комами найменування полів, за якими буде проводитися впорядковування в результаті запиту
  • join (масив) - масив найменувань полів з різних таблиць (ресурсів), що у результаті запиту повинні об'єднатися в єдину таблицю

Ключі словника при поверненні значень за результатами зробленої вибірки:

  • fields (список полів) - поля / колонки та метадані
  • offset (ціле) – значення зсуву запитів
  • limit (ціле) - граничне значення обсягу запиту
  • count (INT) - загальна кількість оброблюваних записів при формуванні запиту
  • records (список словників) - список результатів зіставлення

Нижче приведений приклад гіперпосилання, котрий виводить опис ресурсу, що входить у набір даних “Загальноосвітні навчальні заклади Одеської області” за рахунок зазначення в цьому гіперпосиланні ідентифікаційного номера відповідного ресурсу:

http://data.ngorg.od.ua/api/action/datastore/search.json?resource_id=9a747130-1c6b-46ba-ba99-9d8af72a6884

2) Гіперпосилання на паспорт і опис ресурсу набору даних

Дане гіперпосилання виводить паспорт і опис ресурсів для заданого набору даних. Це гіперпосилання має один єдиний параметр id, що вказує або на ідентифікаційний номер, або на найменування набору даних. Значення для цього параметра записується у форматі рядка.

Нижче приведений приклад гіперпосилання, котрий виводить паспорт і опис ресурсів для набору даних “Загальноосвітні навчальні заклади Одеської області” за рахунок зазначення в цьому гіперпосиланні ідентифікаційного номера цього набору даних:

http://data.ngorg.od.ua/api/3/action/package_show?id=f16110a5-acdd-43f9-a7c7-055f766d671e

Робота з реєстрами наборів даних на основі API

1) Гіперпосилання на реєстр c паспортом і описом ресурсів для розміщених на порталі наборів даних

http://data.ngorg.od.ua/uk/api/3/action/current_package_list_with_resources

Дане гіперпосилання виводить загальний реєстр з описом паспортів та ресурсів для розміщених на порталі наборів даних відповідно до заданих параметрів. Цей реєстр при виведенні сортується таким чином, що останній створений (модифікований) набір даних завжди буде першим у списку цього реєстру.

Параметрами цього гіперпосилання є:

  • limit - параметр, що задає посторінковий вивід наборів даних, де на кожній сторінці повинне виводиться визначена кількість наборів даних; значення для параметра limit записується у форматі цілого числа
  • offset - параметр, що дозволяє вказувати кількість наборів даних, на котре буде зміщений вивід цих наборів від початку списку; значення для параметра offset записується у форматі цілого числа
  • rtype - список словників

2) Гіперпосилання на реєстр із докладним описом відомостей по паспортах та іншим метаданним для всіх розміщених на порталі наборів даних.

http://data.ngorg.od.ua/uk/data.json

Дане гіперпосилання виводить реєстр із докладним описом відомостей по паспортах та іншим метаданним для всіх розміщених на порталі наборів даних

3) Гіперпосилання на реєстр найменувань опублікованих на порталі наборів даних

http://data.ngorg.od.ua/uk/api/3/action/package_list

Гіперпосилання виводить реєстр найменувань наборів даних, що були опубліковані на порталі

Дане гіперпосилання може мати наступні параметри:

  • limit - параметр, що задає посторінковий вивід імен наборів даних, де на кожній сторінці повинне виводиться визначена кількість цих імен; значення для параметра limit записується у форматі цілого числа
  • offset - параметр, що дозволяє вказувати кількість імен наборів даних, на котре буде зміщений вивід цих імен від початку списку; значення для параметра offset записується у форматі цілого числа
  • rtype - список рядків

Робота з розпорядниками наборів даних на основі API

1) Гіперпосилання на реєстр груп, що поєднують набори даних відповідно до тієї чи іншої предметної сфери

http://data.ngorg.od.ua/uk/api/3/action/group_list

Гіперпосилання виводить реєстр груп, що поєднують набори даних відповідно до тієї чи іншої предметної сфери.

Дане гіперпосилання може містити наступні параметри:

  • order_by -  сортування груп або по полю “name” (ім'я), або по полю “packages” (пакети); за замовчуванням сортування відбувається по полю “name”; значення для параметра order_by записуються у форматі рядка
  • sort - необов'язковий параметр для сортування результатів пошуку; за замовчуванням поля “name” і “packages” сортуються по зростанню шляхом завдання значення типу "name asc"; значення для параметра sort записується у форматі рядка
  • all_fields - параметр, що приводить до повернення повної інформації про групи, а не просто до повернення імен цих груп (опціонально, за замовчуванням: “False”); тип значення параметра all_fields – boolean
  • rtype - список рядків

2) Гіперпосилання на реєстр із паспортом та описом ресурсів для всіх наборів даних, об'єднаних у той чи іншій групі по предметній сфері

Дане гіперпосилання виводить паспорти наборів даних та відомості про приналежні до них ресурси для заданої групи (груп)

Гіперпосилання може містити наступні параметри:

  • id - ідентифікатор чи ім'я групи; значення для параметра id записується у форматі рядка
  • limit – параметр, що вказує максимальну кількість наборів даних, що повертаються, у групі (за бажанням); значення для параметра limit записується у форматі цілого числа
  • rtype - список словників

Нижче приведені приклади гіперпосилань для здійснення вибірок паспортів наборів даних та структур їх ресурсів по кожній з наявних на нашому порталі групі (предметній сфері застосування наборів даних):

Група “Місцева державна влада”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=misceva-derzhavna-vlada

Група “Економіка”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=ekonomika

Група “Державні торги”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=derzhavni-torgy

Група “Соціальна сфера”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=socialna-sfera

Група “Громадські організації”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=gromadski-organizaciyi

Група “Освіта”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=osvita

Група “Туризм”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=turyzm

Група “Здоров'я”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=zdorovya

Група “Екологія”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=ekologiya

Група “Сільське господарство”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=silske-gospodarstvo

Група “Промисловість”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=promyslovist

Група “Транспорт”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=transport

Група “Торгівля”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=torgivlya

Група “Метеодані”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=meteodani

Група “Дозвілля і відпочинок”

http://data.ngorg.od.ua/uk/api/3/action/group_package_show?id=dozvillya-ta-vidpochynok