API v1.0 СаранскТудэй

Все запросы отправляются через GET-метод HTTP-протокола. Результат возвращается в строке-JSON-объекте, которую необходимо декодировать для получения исходных данных.

Быстрый пример

Если в строке браузера набрать адрес:

http://saransktoday.ru/api/1.0/event/?id=1268

Сервер вернёт нечто подобное:

{"category":"24","title":"\"\u0427\u0430\u0439\u0444. \u0420\u043e\u0436\u0434\u0451\u043d\u043d\u044b\u0439 \u0432 \u0421\u0432\u0435\u0440\u0434\u043b\u043e\u0432\u0441\u043a\u0435\"","content":"<p>\u042e\u0431\u0438\u043b\u0435\u0439\u043d\u044b\u0439 \u0442\u0443\u0440 \u043a 30-\u043b\u0435\u0442\u0438\u044e \u0433\u0440\u0443\u043f\u043f\u044b. \u0427\u0410\u0419\u0424\u0443 \u2014 30 \u043b\u0435\u0442. \u041e\u0442\u043c\u0435\u0447\u0430\u0442\u044c \u044d\u0442\u0443 \u0434\u0430\u0442\u0443 \u0433\u0440\u0443\u043f\u043f\u0430 \u0441\u043e\u0431\u0438\u0440\u0430\u0435\u0442\u0441\u044f \u043f\u043e \u0432\u0441\u0435\u0439 \u0441\u0442\u0440\u0430\u043d\u0435 \u0438 \u0437\u0430 \u0435\u0451 \u043f\u0440\u0435\u0434\u0435\u043b\u0430\u043c\u0438 \u0431\u043e\u043b\u044c\u0448\u0438\u043c \u044e\u0431\u0438\u043b\u0435\u0439\u043d\u044b\u043c \u0442\u0443\u0440\u043e\u043c \u00ab\u0427\u0410\u0419\u0424. \u0420\u043e\u0436\u0434\u0451\u043d\u043d\u044b\u0439 \u0432 \u0421\u0432\u0435\u0440\u0434\u043b\u043e\u0432\u0441\u043a\u0435\u00bb.<\/p>\r\n<table>\r\n<tr>\r\n<th>\u041a\u043e\u0433\u0434\u0430<\/th><td>16 \u0430\u043f\u0440\u0435\u043b\u044f, \u0447\u0435\u0442\u0432\u0435\u0440\u0433, 19:00<\/td>\r\n<\/tr>\r\n<tr>\r\n<th>\u0413\u0434\u0435<\/th><td>\u0420\u0435\u0441\u043f\u0443\u0431\u043b\u0438\u043a\u0430\u043d\u0441\u043a\u0438\u0439 \u0414\u0432\u043e\u0440\u0435\u0446 \u041a\u0443\u043b\u044c\u0442\u0443\u0440\u044b<\/td>\r\n<\/tr>\r\n<tr>\r\n<th>\u0421\u0442\u043e\u0438\u043c\u043e\u0441\u0442\u044c \u0431\u0438\u043b\u0435\u0442\u0430<\/th><td>\u043e\u0442 1000<span class=\"rub\">\u0420<\/span><\/td>\r\n<\/tr>\r\n<tr>\r\n<th>\u0413\u0434\u0435 \u043a\u0443\u043f\u0438\u0442\u044c<\/th><td>\u041a\u0430\u0441\u0441\u0430 \u0420\u0414\u041a, \u043c\u0443\u0437\u044b\u043a\u0430\u043b\u044c\u043d\u044b\u0439 \u043c\u0430\u0433\u0430\u0437\u0438\u043d \u00abFLOYD\u00bb (\u0422\u0420\u041a \u00ab\u041e\u0433\u0430\u0440\u0435\u0432 Plaza\u00bb, 5 \u044d\u0442\u0430\u0436)<\/td>\r\n<\/tr>\r\n<\/table>\r\n\r\n<p>\u041d\u0430 \u044e\u0431\u0438\u043b\u0435\u0439\u043d\u044b\u0445 \u043a\u043e\u043d\u0446\u0435\u0440\u0442\u0430\u0445 \u043f\u0440\u043e\u0437\u0432\u0443\u0447\u0430\u0442 \u0440\u0430\u043d\u043d\u0438\u0435 \u043f\u0435\u0441\u043d\u0438 \u0432\u0440\u0435\u043c\u0435\u043d \u0441\u0432\u0435\u0440\u0434\u043b\u043e\u0432\u0441\u043a\u043e\u0433\u043e \u0440\u043e\u043a-\u043a\u043b\u0443\u0431\u0430 \u0438 \u043f\u0435\u0441\u043d\u0438, \u0445\u043e\u0440\u043e\u0448\u043e \u0438\u0437\u0432\u0435\u0441\u0442\u043d\u044b\u0435 \u0432 \u0420\u043e\u0441\u0441\u0438\u0438, \u043b\u044e\u0431\u0438\u043c\u044b\u0435 \u043f\u043e\u043a\u043b\u043e\u043d\u043d\u0438\u043a\u0430\u043c\u0438 \u0438 \u0434\u0430\u0432\u043d\u043e \u0441\u0442\u0430\u0432\u0448\u0438\u0435 \u043c\u0443\u0437\u044b\u043a\u0430\u043b\u044c\u043d\u044b\u043c \u0434\u043e\u0441\u0442\u043e\u044f\u043d\u0438\u0435\u043c \u0441\u0442\u0440\u0430\u043d\u044b. \u0411\u043e\u043b\u044c\u0448\u043e\u0439 \u0441\u043e\u043b\u044c\u043d\u044b\u0439 \u043f\u0440\u0430\u0437\u0434\u043d\u0438\u0447\u043d\u044b\u0439 \u043a\u043e\u043d\u0446\u0435\u0440\u0442 \u0427\u0410\u0419\u0424\u0430 \u2014 \u044d\u0442\u043e \u0430\u043d\u0448\u043b\u0430\u0433 \u0432 \u0437\u0430\u043b\u0435, \u043f\u0435\u043d\u0438\u0435 \u0445\u043e\u0440\u043e\u043c, \u0432\u0441\u0442\u0440\u0435\u0447\u0430 \u0441\u043e \u0441\u0442\u0430\u0440\u044b\u043c\u0438 \u0434\u0440\u0443\u0437\u044c\u044f\u043c\u0438, \u0432\u043e\u0441\u043f\u043e\u043c\u0438\u043d\u0430\u043d\u0438\u044f, \u0441\u0432\u044f\u0437\u0430\u043d\u043d\u044b\u0435 \u0441 \u043b\u044e\u0431\u0438\u043c\u044b\u043c\u0438 \u043f\u0435\u0441\u043d\u044f\u043c\u0438. \u042d\u0442\u043e \u00ab\u0442\u0435\u0431\u0435 \u043e\u043f\u044f\u0442\u044c \u0441\u0435\u043c\u043d\u0430\u0434\u0446\u0430\u0442\u044c \u043b\u0435\u0442\u00bb, \u0410\u0440\u0433\u0435\u043d\u0442\u0438\u043d\u0430 \u0441\u043d\u043e\u0432\u0430 \u0432\u044b\u0438\u0433\u0440\u0430\u0435\u0442 \u0443 \u042f\u043c\u0430\u0439\u043a\u0438, \u0428\u0430\u0445\u0440\u0438\u043d \u043e\u043f\u044f\u0442\u044c \u043f\u043e\u0439\u043c\u0451\u0442, \u0447\u0442\u043e \u0435\u0433\u043e \u0443\u043b\u044b\u0431\u043a\u0430 \u2014 \u0442\u0430\u043a\u0430\u044f \u0436\u0435, \u043a\u0430\u043a \u0443 \u00ab\u0438\u043a\u0430\u0440\u0443\u0441\u0430\u00bb, \u0411\u0435\u0433\u0443\u043d\u043e\u0432 \u0441\u043e\u043e\u0431\u0449\u0438\u0442, \u0447\u0442\u043e \u043e\u043d \u0443\u0435\u0437\u0436\u0430\u0435\u0442, \u0430 \u0421\u0435\u0432\u0435\u0440\u0438\u043d \u0441 \u0414\u0432\u0438\u043d\u0438\u043d\u044b\u043c \u043f\u043e\u0434\u0434\u0435\u0440\u0436\u0430\u0442 \u043b\u044e\u0431\u043e\u0439 \u0437\u0430\u0434\u0430\u043d\u043d\u044b\u0439 \u0440\u0438\u0442\u043c. \u0418 \u0432\u0441\u0451 \u044d\u0442\u043e \u2014 \u0432\u043c\u0435\u0441\u0442\u0435 \u0441 \u0440\u0430\u0434\u043e\u0441\u0442\u043d\u044b\u043c\u0438 \u0437\u0440\u0438\u0442\u0435\u043b\u044f\u043c\u0438 \u043e\u0442 \u043c\u0430\u043b\u0430 \u0434\u043e \u0432\u0435\u043b\u0438\u043a\u0430.<\/p>","description":"\"\u0427\u0430\u0439\u0444. \u0420\u043e\u0436\u0434\u0451\u043d\u043d\u044b\u0439 \u0432 \u0421\u0432\u0435\u0440\u0434\u043b\u043e\u0432\u0441\u043a\u0435\"","keywords":"\"\u0427\u0430\u0439\u0444. \u0420\u043e\u0436\u0434\u0451\u043d\u043d\u044b\u0439 \u0432 \u0421\u0432\u0435\u0440\u0434\u043b\u043e\u0432\u0441\u043a\u0435\"","preview":"http:\/\/saransktoday.ru\/storage\/posters\/preview\/1268\/afisha-view-sar 6..jpg","id":"1268","url":"http:\/\/saransktoday.ru\/news\/concerts\/chayf-rozdenniy-v-sverdlovske\/","category_title":"\u041a\u043e\u043d\u0446\u0435\u0440\u0442\u044b","date_start":"2015-04-16 19:00:58","date_end":"2015-04-16"}

Эту строку нужно декодировать, например, с помощью php-функции json_decode($result, true) и вывести через print_r():

Array
(
    [category] => 24
    [title] => "Чайф. Рождённый в Свердловске"
    [content] => <p>Юбилейный тур к 30-летию группы. ЧАЙФу — 30 лет. Отмечать эту дату группа собирается по всей стране и за её пределами большим юбилейным туром «ЧАЙФ. Рождённый в Свердловске».</p>
<table>
<tr>
<th>Когда</th><td>16 апреля, четверг, 19:00</td>
</tr>
<tr>
<th>Где</th><td>Республиканский Дворец Культуры</td>
</tr>
<tr>
<th>Стоимость билета</th><td>от 1000<span class="rub">Р</span></td>
</tr>
<tr>
<th>Где купить</th><td>Касса РДК, музыкальный магазин «FLOYD» (ТРК «Огарев Plaza», 5 этаж)</td>
</tr>
</table>

<p>На юбилейных концертах прозвучат ранние песни времен свердловского рок-клуба и песни, хорошо известные в России, любимые поклонниками и давно ставшие музыкальным достоянием страны. Большой сольный праздничный концерт ЧАЙФа — это аншлаг в зале, пение хором, встреча со старыми друзьями, воспоминания, связанные с любимыми песнями. Это «тебе опять семнадцать лет», Аргентина снова выиграет у Ямайки, Шахрин опять поймёт, что его улыбка — такая же, как у «икаруса», Бегунов сообщит, что он уезжает, а Северин с Двининым поддержат любой заданный ритм. И всё это — вместе с радостными зрителями от мала до велика.</p>
    [description] => "Чайф. Рождённый в Свердловске"
    [keywords] => "Чайф. Рождённый в Свердловске"
    [preview] => http://saransktoday.ru/storage/posters/preview/1268/afisha-view-sar 6..jpg
    [id] => 1268
    [url] => http://saransktoday.ru/news/concerts/chayf-rozdenniy-v-sverdlovske/
    [category_title] => Концерты
    [date_start] => 2015-04-16 19:00:58
    [date_end] => 2015-04-16
)

В приведенном выше запросе участвует ряд интересных параметров:

  • 1.0 — версия API;
  • event — тип запроса;
  • ?id=1268 — опция запроса.

Типы запроса

В версии 1.0 есть три типа запроса:

  • event — получить подробный элемент события;
  • eventslist — получить список событий;
  • categorieslist — получить список категорий.

У каждого типа запроса есть свой набор опций, обязательных и не очень. Опции представляют собой пары вида ключ=значение объединенные знаком амперсанда (&). Первая пара идёт после знака вопроса. Рассмотрим подробно каждый набор опций.

categorieslist

Все опции этого типа запроса необязательны.

  • offset — число; отступ выдачи, для, например, постраничной выдачи; с нуля;
  • limit — число; количество записей; максимум 100;
  • order — строка; asc: по алфавиту, desc по делфавиту.

Пример

http://saransktoday.ru/api/1.0/categorieslist/?order=asc&offset=3&limit=6

Вернет шесть категорий, отсортированных по алфавиту, начиная с четвёртой по порядку (с третьей в базе данных).

eventslist

Все опции этого типа запроса необязательны.

  • offset — число; отступ выдачи, для, например, постраничной выдачи; с нуля;
  • limit — число; количество записей; максимум 100;
  • category — число; значение поля id из результатов categorieslist.

Вывод событий на сайте не так однозначен, как кажется на первый взгляд. Сначала выводятся события, которые проходят сегодня. Затем выводятся события, которые ещё только предстоят и отсортированы они так: от ближайщих событий к событиям, которые будут совсем не скоро. Потом идут события, которые уже прошли и сортировка та же по логике: от ближайших прошедших к событиям, которые были в далеком прошлом. Такая сортировка имеет значение logic. С ней могут применяться опции offset, limit, category, но не могут применяться date, period_start и period_end. logic — значение опции по умолчанию, если вы не задали другую сортировку, или не задали одну из временных опций. Если вы задаёте временную опцию, то сортировка по умолчанию меняется на desc. Итак, опция order:

  • logic — сначала сегодняшние, потом будущие, потом прошедшие; это значение по умолчанию, если не задана временная опция; не совместима с временными опциями;
  • asc: от самых старых к новым;
  • desc: от новых к старым; будет значением по умолчанию, если будет задана временная опция.

Если любопытство в вас возобладает и вы захотите применить временную опцию вместе с сортировкой logic, получите ответ:

{"error":"You cant use `logic` order with `period` or `date`"}

Временные опции. Все они не могут использоваться со значением logic в опции order.

  • date — дата в формате ГГГГ-ММ-ДД; события выведутся за выбранную дату; не может использоваться вместе с period_start и period_end;
  • period_start — дата в формате ГГГГ-ММ-ДД; события выведутся начиная с этой даты, включительно; не может использоваться вместе с date;
  • period_end — дата в формате ГГГГ-ММ-ДД; события выведутся заканчивая этой датой, включительно; не может использоваться вместе с date.

Примеры

Двадцать событий из категории с id=23, начиная с десятой:

http://saransktoday.ru/api/1.0/eventslist/?offset=9&limit=20&category=23

События за 1 июня 2015 года, отсортированные в хронологическом порядке:

http://saransktoday.ru/api/1.0/eventslist/?date=2015-06-01&order=asc

События за первую неделю июля 2015 года, отсортированные в обратном порядке:

http://saransktoday.ru/api/1.0/eventslist/?period_start=2015-07-01&period_end=2015-07-07&order=desc

Примечание: period_start и period_end не обязаны использоваться одновременно. Интервалы могут быть открытыми.

event

Этот тип запроса содержит одну обязательную опцию:

  • id — число; берётся из результатов eventslist.

Реализация клиента на PHP