AlterGeo – это новый взгляд на твой город!

AlterGeo

Места в твоем смартфоне

Open API - для разработчиков

Введение

Это API даёт возможность разработчикам сторонних приложений взаимодействовать с платформой AlterGeo. Ещё один способ отмечаться в заведениях и получать информацию об активности пользователей AlterGeo.

Аутентификация

Для большинства действий необходима или рекомендуется Basic HTTP аутентификация. То есть Вы должны отправлять логин и пароль пользователя в HTTP заголовках. Например, с помощью утилиты curl это можно сделать вот так:

curl -u PHONE_OR_EMAIL:PASSWORD http://altergeo.ru/openapi/v1/places/search

Формат

Запрос

URL запроса содержит вызываемый метод и желаемый вид ответа. Например, для поиска мест используется:

http://altergeo.ru/openapi/v1/places/search/

в котором v1 - версия OpenApi.

Остальные параметры передаются либо параметрами GET, либо POST. Требования по передаче параметров описаны для каждого вызова в этом документе.

Данные в запросе должны быть в кодировке utf-8.

В тех запросах, где необходимо передавать параметры методом POST обязательно в заголовках передавать Content-type: application/x-www-form-urlencoded (если не указано иное в описании конкретного вызова).

JSONP

Для получения данных в формате JSONP необходимо методом GET в параметре jsonp передать имя callback функции.

Пример запроса: http://altergeo.ru/openapi/v1/places/search?jsonp=parseResponse

Возможность использования JSONP указано в описании каждого вызова.

Ответ

Ответ от OpenApi можно получить либо в XML, либо в JSON. Для того, чтобы указать желаемый формат, необходимо в HTTP-заголовках передать Accept:

application/json
application/xml

По умолчанию установлен формат XML.

Для описания примеров, ответы в дальнейшем будем рассматривать в формате XML. В формате JSON структура ответа будет аналогичной.

Для удобства описания методов API в дальнейшем мы не будем приводить примеры ответов полностью, будут опущены блоки с описанием стандартных объектов:

Объект place

Объект описывает место (кафе, ресторан, банк или любое другое заведение) и его параметры. Один из общепринятых терминов - POI (Places Of Interest).

XML:

<place>
    <id>9297</id>
    <title>Coffee Point</title>
    <type>
        Объект type
    </type>
    <lat>55.7448551</lat>
    <lng>37.636697</lng>
    <image>http://altergeo.ru/pictures/thumbs/100x100/predefined/photo.gif</image>
    <about>VIP-зал,  еда на вынос,  завтраки,  карта вин,  проведение банкетов,  шведский стол</about>
    <country>Россия</country>
    <city>Москва</city>
    <street>Садовническая, 42, стр. 1</street>
    <phones>
        <phone>74959536726</phone>
    </phones>
    <distance>1081</distance>
    <checkin_count>0</checkin_count>
    <rating>4.7</rating>
    <rating_vote_count>5</rating_vote_count>
    <mayor>
        <user>
            Объект User
        </user>
    </mayor>
</place>

Значения полей в ответе:

id - (integer) уникальный идентификатор места.
title - (string; max=255) название места
type - объект type
lat - (float) широта
lng - (float) долгота
image - (string) URL на логотип места
about - (string) описание
country - (string; max=255) страна
city - (string; max=255) город
street - (string; max=255) улица
url - (string) ссылка на страницу в AlterGeo
phones - набор тегов phone с телефонами. Отсутствует, если не указаны телефоны
distance - (integer) расстояние до места в метрах. Рассчитывается только тогда, когда выборка идёт по координатам lat и lng. Отсутствует, если невозможно рассчитать дистанцию.
checkin_count - (integer) количество людей отметившихся в этом месте (количество посетителей)
rating - (float) рейтинг места сформированный по оценкам пользователей AlterGeo
rating_vote_count - (integer) количество пользователей оценивших это место
mayor - объект User. Пользователь, который является Легендой этого места
redirect - (integer), присутствует, если место удалено. Если место склеено с другим местом содержит ID места, информацию о котором надо запрашивать вместо удалённого.

Объект type

Объект описывает тип (категорию) места.

XML:

<type>
    <id>1</id>
    <title>Автомобильное</title>
    <logo>http://altergeo.ru/pictures/type/1.png</logo>
</type>

Значения полей в ответе:

id - (integer) уникальный идентификатор категории.
title - (string; max=255) название категории
logo - (string) URL на логотип категории

Объект user

Объект описывает пользователя и его параметры.

XML:

<user>
    <id>10241</id>
    <first_name>Арташес</first_name>
    <last_name>Хатламаджиян</last_name>
    <image>http://altergeo.ru/pictures/thumbs/100x100/1/49.908885.jpeg</image>
    <sex>M</sex>
    <birth_date>1985-03-04</birth_date>
    <about>
        На московских изогнутых улицах.
        Помереть, знать, судил мне Бог. (Есенин)
    </about>
    <lat>55.747314</lat>
    <lng>37.622749</lng>
    <postime>2010-09-24 13:04:48</postime>
    <country>Россия</country>
    <city>Москва</city>
    <street>Болотная улица, 12</street>
    <status_string>Пляжный волейбол. SWATCH FIVB World Tour 2010. Grand Slam.</status_string>
    <checkin_count>357</checkin_count>
    <relation>friend</relation>
</user>

Картинки

В ответах API ссылки на изображения выглядят так:

http://altergeo.ru/pictures/thumbs/100x100/3/2019.323972.jpeg

Вместо 100x100 Вы можете подставить другие варианты разрешений:

16x16
44x44
52x52
128x128
160x160
320x240
320x480
480x320
500x500
800x600

Ошибки

В случае возникновения ошибки мы возвращаем HTTP ответ с кодом, соответствующим этой ошибке. Вот список основных используемых нами HTTP кодов.

400: вызов несуществующего метода
401: запрос требует аутентификации
403: данный пользователь не может выполнить запрошенное действие (чекин, например) или получить запрошенную информацию в настоящий момент
404: запрашиваемый объект или информация не найдена

При возникновении ошибки ответ будет содержать единственный элемент error, в котором будет детальное описание ошибки.

Например:

    <error>Не переданы параметры для авторизации</error>

JSONP

Для JSONP в случае ошибки всегда возвращается код 200, но в ответе детальное описание ошибки будет присутствовать.

Ограничения

На использование API установлены следующие ограничения:

Не более 300 запросов в течение часа
Не более 10 запросов в течение минуты

Ограничения устанавливаются на код авторизации (в случае, если пользователь успешно залогинен), либо на IP адрес, если пользователь не прошёл авторизацию.

Язык

Для указания желаемого языка необходимо в HTTP-заголовках передать Accept-Language. В настоящий момент поддерживаются 2 языка:

русский (ru)
английский (en)

Места

Получение списка мест

URL: http://altergeo.ru/openapi/v1/places/search/

Метод запроса: POST, GET (только для JSONP)

Аутентификация требуется: нет, но желательна

Возможность использования JSONP: да

Параметры:

lat - широта
lng - и долгота местоположения пользователя, опциональные параметры, но желательные, т.к. дают возможность выбрать места, находящиеся поблизости от пользователя
distance - дистанция (в метрах). Используется только при передаче lat и lng. По умолчанию: 1000.
upper_left_lat - широта верхнего левого угла. Опционально.
upper_left_lng - долгота верхнего левого угла. Опционально.
lower_right_lat - широта нижнего правого угла. Опционально.
lower_right_lng - долгота нижнего угла. Опционально. (В случае передачи lat и lng эти параметры игнорируется)
query - поисковый запрос, опционально
place_types - ID категорий. Опционально. Возможно перечисление через запятую нескольких.
order - сортировка. Опционально. Имеет 2 состояния: distance - актуально только при передачах координат; relevancy - актуально при передаче поисковой фразы.
limit - максимальное число выбираемых объектов, опционально. По умолчанию: 50.
offset - смещение. По умолчанию: 0.

Примечание. Для получения списка мест необходимо передать хотя бы один из следующих параметров (набора параметров):

lat, lng
upper_left_lat, upper_left_lng, lower_right_lat, lower_right_lng
query
place_types

Ответ:

<places>
   <place>
      ...
   </place>
   <place>
      ...
   </place>
   <offset>0</offset>
   <limit>5</limit>
   <count>22</count>
</places>

Работа с единичным местом

Получение информации о месте

URL: http://altergeo.ru/openapi/v1/place/profile/

Метод запроса: POST

Аутентификация требуется: нет, но желательна

Возможность использования JSONP: нет

Параметры:

place_id - ID места
lat - широта
lng - и долгота местоположения пользователя, опциональные параметры, но желательные, если необходимо рассчитать дистанцию до места

Ответ:

<place>
    Place object
</place>

Отметиться (checkin)

URL: http://altergeo.ru/openapi/v1/place/checkin/

Метод запроса: POST

Аутентификация требуется: да

Возможность использования JSONP: нет

Параметры:

place_id - ID места
text - Сопровождающий текст (опционально)

Ответ:

<text>
    Поздравляем! Вы получили 1 очко! В следующий раз Вы сможете отметиться через 5 мин.
</text>

Типы (категории) мест

Получение списка категорий

URL: http://altergeo.ru/openapi/v1/types/list/

Аутентификация требуется: нет, но желательна

Возможность использования JSONP: нет

Ответ:

<types>
    <type>
        Type object
    </type>
    <type>
        Type object
    </type>
    ...
    <count>17</count>
</types>

Пользователь

Получение списка посещённых мест

URL: http://altergeo.ru/openapi/v1/user/get_checkin_places/

Аутентификация требуется: да

Возможность использования JSONP: нет

Параметры:

limit - максимальное число выбираемых объектов, опционально. По умолчанию: 20.
offset - смещение. По умолчанию: 0.

Ответ:

<places>
   <place>
      Объект Place
   </place>
   <place>
      Объект Place
   </place>
   <offset>0</offset>
   <limit>5</limit>
   <count>22</count>
</places>

Получение списка отметок

URL: http://altergeo.ru/openapi/v1/user/get_checkins/

Аутентификация требуется: да

Возможность использования JSONP: нет

Параметры:

limit - максимальное число выбираемых объектов, опционально. По умолчанию: 20.
offset - смещение. По умолчанию: 0.

Ответ:

<checkins>
   <checkin>
      <place>
           Объект Place
      </place>
      <id>12976</id>
      <datetime>1297609297</datetime>
      <text></text>
   </checkin>
   <offset>4</offset>
   <limit>1</limit>
   <count>331</count>
</checkins>