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

Установи мобильное приложение Установи мобильное приложение дляiPhone / Android
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. Пользователь, который является Легендой этого места

Объект 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>