ГІПЕРПОСИЛАННЯ НА РЕСУРСИ У ЗАЗНАЧЕНИХ НАБОРАХ ДАНИХ
Наш портал надає стороннім 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 |
+ --------------------- + ------------ + -- + ---------- + Простий приклад запиту:
Даний запит повертає з першого ресурсу (набору даних) такі стовпчики, як Країна, Населення та Метка з даними по США і Тихоокеанському регіону, відсортованими по стовпчику Країна в порядку зростання.
Пошук по тексту
Для здійснення пошуку по тексту потрібно використовувати параметр query (q). У результаті застосування цього параметру будуть виведені все рядки, де в заданих колонках є рядок для пошуку по тексту, зазначений у параметрі query.
http://data.ngorg.od.ua/api/dataset/search?resource_id=1&&fields=Країна,Населення&query=США
Даний запит повертає з першого ресурсу колонку Країна і колонку Населення з рядками, у яких міститься текст – “США”.
Об'єднання
Якщо ви хочете здійснити запит на основі декількох таблиць, то необхідно вказати ці таблиці у виді масивів, аналогічно наступному прикладу:
Даний запит повертає інформацію з першого та другого ресурсу по таких колонкам, як Країна, Населення, Площа (кв.км) і ID для США та Тихоокеанського регіону.