API до наборів даних

Отримати дані про набір даних можна за посиланням такого типу:
https://data.kyivcity.gov.ua/api/3/action/package_show?id=[DATASET_ID]

а, дані про конкретний ресурс за таким посиланням.
https://data.kyivcity.gov.ua/api/action/datastore/search.json?resource_id=[RESOURCE_ID]

Дані можуть бути надані за посиланням виду https://data.kyivcity.gov.ua/api/dataset/search?resource_id=[RESOURCE_ID], де [RESOURCE_ID] – це ідентифікатор певного ресурсу з набору даних. Ідентифікатори можна знайти на сторінці “API даних”, посилання на яку є на сторінці ресурсу.

Разом із ідентифікатором ресурсу можна використовувати наступні параметри:

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

Функції попередньої обробки даних

  • sum (текст) – змінна, за якою необхідно розрахувати суму
  • avg (текст) – змінна, за якою необхідно розрахувати середнє
  • min (текст) – змінна, за якою необхідно знайти мінімум
  • max (текст) – змінна, за якою необхідно знайти максимум
  • std (текст) – змінна, за якою необхідно розрахувати стандартне відхилення
  • variance (текст) – змінна, за якою необхідно розрахувати дисперсію

Формат вказання параметрів в URL:

param_name[resource_alias][field_name]=value,value1

де

  • param_name: назва параметру, який ви використовуєте (наприклад, offset)
  • resource_alias(не обов’язковий): назва ресурсу для вказання його в інших параметрах.
  • field_name(не обов’язковий): назва змінної, яку використовує параметр.
  • value: пеерлік значень, розділених комою.

Зауважте, що аргументи resource_alias and field_name не є обов’язковими та залежать від того, що саме ви хочете отримати в результаті запиту. Наприклад, якщо вам необхідно обмежити кількість записів, ви можете використати параметр limit. При цьому, немає сенсу вказувати назву ресурсу або певну змінну. Необхідно лише надати число, яку саме кількість записів ви хочете отримати:

...&limit=5

Єдине виключення: параметр сортування може використовувати, як зазначений формат, так і альтернативний:

...&sort=field1,field2 desc

Множинні запити

Іноді вам знадобиться отримати інформацію з декількох ресурсів в одному запиті (наприклад, для відображення на дашборді). В цьому випадку ви можете відправити POST запит з JSON об’єектом на https://data.kyivcity.gov.ua/api/action/datastore/search.json з переліком запитів, яі необхідно виконати.

Тіло запиту має відповідати такому формату:

Тіло запиту

{
"my_query": {
"resource_id": {
"states": "d2142282-9838-4cca-972f-f1741410417b",
"gold_prices":"d3c099c6-1340-4ee5-b030-8faf22b4b424"
},
"limit": 5
},
"my_query1": {
"resource_id": {
"gold_prices": "d3c099c6-1340-4ee5-b030-8faf22b4b424"
},
"limit": 5
}
}

Відповідь

{
"my_query": {
"help": "Search a datastore table. :param resource_id: id or alias of the data that is going to be selected.",
"success": true,
"result": {
"fields": [
{
"id": "nombre",
"type": "text"
},
{
"id": "state_id",
"type": "int"
}
],
"resource_id": {
"states": "d2142282-9838-4cca-972f-f1741410417b",
"gold_prices": "d3c099c6-1340-4ee5-b030-8faf22b4b424"
},
"limit": 1,
"total": 5,
"records": [
{
"nombre": "Alabama",
"state_id": "1",
"feeds*flatstore_entry*id": "1",
"timestamp": "1466096874",
"feeds*entity*id": "13"
}
]
}
},
"my_query1": {
"help": "Search a datastore table. :param resource_id: id or alias of the data that is going to be selected.",
"success": true,
"result": {
"fields": [
{
"id": "date",
"type": "datetime"
},
{
"id": "price",
"type": "float"
},
{
"id": "state_id",
"type": "int"
}
],
"resource_id": {
"gold_prices": "d3c099c6-1340-4ee5-b030-8faf22b4b424"
},
"limit": 1,
"total": 748,
"records": [
{
"date": "1950-01-01",
"price": "34.73",
"state_id": "1",
"feeds*flatstore_entry*id": "1",
"timestamp": "1466036208",
"feeds*entity*id": "12"
}
]
}
}
}

Формати відповідей

Запити можуть бути надіслані через HTTP протокол. Дані повертаються у форматах JSON, XML або JSONP. Щоб отримати дані у необхідному форматі, вкажіть формат як розширення запиту в URL.

Тобто замість посилання:

https://data.kyivcity.gov.ua/api/action/datastore/search.json

Скористайтеся посиланням:

https://data.kyivcity.gov.ua/api/action/datastore/search.xml

Або таким:

https://data.kyivcity.gov.ua/api/action/datastore/search.jsonp

Обмеження

Параметр q не працює у поєднанні з параметром join.

Фільтрація не працює з десятковими числовими значеннями (float).

Приклад

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

Реурс 1:

country population id timestamp
US 315,209,000 1 1359062329
CA 35,002,447 2 1359062329
AR 40,117,096 3 1359062329
JP 127,520,000 4 1359062329

Ресурс 2:

country squarekm id timestamp
US 9,629,091 1 1359062713
CA 9,984,670 2 1359062713
AR 2,780,400 3 1359062713
JP 377,930 4 1359062713

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

https://EXAMPLE.COM/api/dataset/search?resource_id=d3c099c6-1340-4ee5-b030-8faf22b4b424&filters[country]=AR,US&fields=country,population,timestamp&sort[country]=asc

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

Текстовий пошук

Запит з аргументом ‘query’ буде шукати перелік змінних у відповідному наборі:

https://example.com/api/dataset/search?resource_id=d3c099c6-1340-4ee5-b030-8faf22b4b424&&fields=country,population&query=US

Такий запит поверне країну та кількість населення Сполучених Штатів Америки..

Поєднання

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

https://example.com/api/dataset/search?resource_id[pop]=d3c099c6-1340-4ee5-b030-8faf22b4b424&resource_id[size]=d3c099c6-1340-4ee5-b030-8faf22b4b424&filters[pop][country]=US,AR&join[pop]=country&join[size]=country

Повертає країну, кількість населення, площу та код країни з ресурсів 1 та 2.