Структура запроса

Пример запроса к API, выдающего 20 ближайших событий в Москве и Санкт-Петербурге:

https://api.timepad.ru/v1/events.json?limit=20&skip=0&cities=Москва,Санкт-Петербург&fields=location&sort=+starts_at

Разберём по частям.

https:// — доступ к API возможен только по https, при попытке получения данных через http выдаётся ошибка 400. Это позволяет гарантировать целостность данных и предотвратить пересылку любой критичной информации в незашифрованном виде.

api.timepad.ru/v1 — API Таймпада располагается на отдельном домене, в адрес встроено версионирование. Это сделано для того, чтобы если когда-либо появится v2, переход на неё будет опционален, а первая версия продолжит функционировать, пока у неё будут клиенты.

/events — ресурс событий, один из главных ресурсов API. С его помощью можно получить доступ к базе данных лекций, семинаров, концертов, конференций, сборов и встреч, проводимых через Таймпад, отфильтровав одним из нескольких десятков возможных способов.

.json — указание на желаемый формат данных. Поддерживается json и html. Если ничего не указано, API определяет формат автоматически: html в браузере, json во всех остальных случаях.

?limit=20&skip=0 — параметры деления на страницы (пагинации). В данном случае означает "20 событий, начиная с первого".

&cities=Москва,Санкт-Петербург — ограничение выдачи списком городов. Фильтр по городам — один из многих доступных для применения. Полный список в интерактивной документации.

&fields=location — список дополнительных полей, которые нужно вывести. Возможные значения можно посмотреть в интерактивной документации.

&sort=+starts_at — сортировка по дате начала события в порядке увеличения. Возможно также сортировать по нескольким другим параметрам.

Выбор выводимых полей

API событий выводит только некоторые наиболее часто используемые поля событий: название, категорию, дату начала, ссылку, постер.

Для того, чтобы вывести другие поля событий, нужно указать их в параметре fields через запятую, например:

https://api.timepad.ru/v1/events?fields=location,registration_data

В результате такого запроса помимо полей по умолчанию также будут вставлены объект места проведения события и объект дополнительных данных о статусе регистрации на событие. Внутренние объекты или полностью не выводятся, или полностью выводятся, поле fields на их содержимое не влияет.

Список полей, которые можно вывести, можно найти в интерактивной документации с пометкой Optional, как на скриншоте:

Поля с пометкой optional

Сортировка значений

API Таймпада поддерживает сортировку по одному из следующих полей:

name
starts_at
city
referrer_percent
created_at
id

Название поля сортировки нужно указать в запросе, например:

https://api.timepad.ru/v1/events?sort=id

Чтобы сортировать по убыванию, нужно указать - перед названием поля, например:
https://api.timepad.ru/v1/events?sort=-id

При сортировке по возрастанию, можно опционально указать плюс перед названием, например,

https://api.timepad.ru/v1/events?sort=+id

Пагинация

Любые списки в API разделены на страницы. Для управления ими есть следующие параметры:

limit - количество элементов, которые нужно вернуть
skip - количество элементов, которые нужно пропустить

Таким образом, например, если получать события по 10, запросы будут выглядеть так:
https://api.timepad.ru/v1/events?limit=10
https://api.timepad.ru/v1/events?limit=10&skip=10
https://api.timepad.ru/v1/events?limit=10&skip=20
https://api.timepad.ru/v1/events?limit=10&skip=30
...
и так далее

При этом ответ выглядит так:

{
    "total" : "123",
    "values" : [...]
}

В total отражается общее количество элементов в выборке, а в values находятся элементы, соответствующие настройке пагинации.

Пустые поля

API по-умолчанию убирает из результатов поля с пустыми значениями (пустые массивы, пустые строки, null). В случае, когда вам требуеются пустые значения, нужно указать параметр show_empty_fields со значением true

Например: https://api.timepad.ru/v1/events?show_empty_fields=true