ГІПЕРПОСИЛАННЯ НА РЕСУРСИ У ЗАЗНАЧЕНИХ НАБОРАХ ДАНИХ

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

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

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

З базовою інформацією по використанню цих форматів даних при створенні сторонніх Web ресурсів та мобільних програмних додатків можна ознайомитися по наступним посиланням:

1. JSON формат: створення даних та використання з PHP і JS

2. Використання XML / XSL для публікації в Web

Зразок базового гіперпосилання на ресурс набору даних з використанням інтерфейсу прикладного програмування (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 для США та Тихоокеанського регіону.