API от Surprise.me

В данном документе содержится список API методов, которые доступны при работе с программой Surprise.me

API позволяет получить данные о квест-экскурсиях Surprise Me, языках квест-экскурсий и городах, доступных на сайте в данный момент.

URL запроса и формат ответа

Все запросы отправляются на адрес https://app.surprizeme.ru/api с добавлением ендпоинта.

Формат ответа: Content-Type: application/json; charset=utf-8

Информационные запросы

Список языков

GET /languages/

Пример ответа

{
   "data":[
      {
         "id":1,
         "name":"Russian",
         "code":"ru"
      },
      {
         "id":2,
         "name":"English",
         "code":"en"
      },
      {
         "id":5,
         "name":"Spanish",
         "code":"es"
      }
   ]
}

Список городов

GET /cities/

Параметры запроса

  • lang - задаёт язык ответа (название, описание). Используется значение поля code из запроса GET /languages/.

Пример ответа

{
   "data":[
      {
         "id":1,
         "name":"Saint Petersburg",
         "slug":"saint-petersburg",
         "bg_image":"https://app.surprizeme.ru/media/world/Saint_Petersburg_Surprise_Me.jpg",
         "preview_image":"https://app.surprizeme.ru/media/CACHE/images/world/Saint_Petersburg_Surprise_Me/a3ca495104075ec257b05fc2814fec47.jpg",
         "country":{
            "name":"Russia",
            "code":"RU"
         },
         "meta_title":"",
         "meta_description":"",
         "description":"<h2>Northern capital</h2>\r\n\r\n The northern capital is rich in architectural beauties and historical places, where every stone keeps a memory of great people and events. St. Petersburg is a symbol of the imperial power of Russia, the center of three revolutions, survived floods, fires and blockade and did not lose its charm after so many hardships. \r\n\r\n Great streets were walking along these streets ", 
"cover_position":60,
"items_count":3
}]
}

Поиск города по частичному совпадению имени

Укажите в параметре query три символа названия города или более.

GET /search/?query=Мос

Параметры запроса

  • lang - задаёт язык ответа (название). Используется значение поля code из запроса GET /languages/.

Пример ответа

{
   "data":[
      {
         "name":"Moscow",
         "language_code":"en",
         "city":{
            "id":524901,
            "slug":"moscow"
         },
         "region":{
            "name":"Moscow",
            "code":"48"
         },
         "country":{
            "name":"Russia",
            "code":"RU"
         }
      }
   ]
}

Коллекции для города

GET /collections/

Параметры запроса

  • city - название города из запроса Список городов.

Пример запроса

https://app.surprizeme.ru/api/collections/?city=moscow

Пример ответа

{
   "data":[
      {
         "category":{
            "title":"Sightseeing",
            "slug":"review"
         },
         "description":"<h2>Обзорные экскурсии в столице.</h2>",
         "preview_image":"https://app.surprizeme.ru/media/CACHE/images/world/%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0_%D0%BE%D0%B1%D0%B7%D0%BE%D1%80%D0%BD%D1%8B%D0%B5_%D1%8D%D0%BA%D1%81%D0%BA%D1%83%D1%80%D1%81%D0%B8%D0%B8/78e190c515cb99bb1a20666f06574375.jpg",
         "city":{
            "id":2,
            "name":"Moscow",
            "slug":"moscow",
            "country":{
               "name":"Russia",
               "code":"RU"
            },
            "bg_image":"https://app.surprizeme.ru/media/world/%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0_%D0%BE%D0%B1%D0%B7%D0%BE%D1%80%D0%BD%D1%8B%D0%B5_%D1%8D%D0%BA%D1%81%D0%BA%D1%83%D1%80%D1%81%D0%B8%D0%B8_Uy4lqzE_BUEee4w.jpg",
            "preview_image":"https://app.surprizeme.ru/media/CACHE/images/world/%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0_%D0%BE%D0%B1%D0%B7%D0%BE%D1%80%D0%BD%D1%8B%D0%B5_%D1%8D%D0%BA%D1%81%D0%BA%D1%83%D1%80%D1%81%D0%B8%D0%B8_Uy4lqzE_BUEee4w/d20b67564e46e506e966b4d89f3901aa.jpg"
         },
         "items_count":0,
         "items":[
            
         ]
      }
   ]
}

Товары

GET /products/?city=moscow&lang=ru

Параметры запроса

  • lang - язык ответа. Используется значение поля code из запроса GET /languages/;
  • city - уникальный идентификатор города. Используется значение поля slug из GET /search/ или GET /cities/.

Пример ответа

Декодированный ответ: под ключом data массив объектов, представляющих товар
{  
   "data":[  
        {
          "id": 7,
          "slug": "romanticheskaya-progulka", // Уникальный идентификатор товара
          "name": "Романтическая прогулка",
          "short_caption": "Романтическая беззаботная прогулка по уютному центру ...",
          "caption": "Романтическая беззаботная прогулка по уютному центру ...", // Полное описание маршрута
          "distance": "3 км", // Суммарное растояние, которые проходят пользователи маршрута
          "complexity": "easy", // Сложность маршрута ("easy", "medium", "hard"). *Subject to change.*
          "locale": {  // Язык маршрута
            "code": "ru", // Код языка
            "name": "Русский" // Локализованное название языка
          },
          "city": {
              "name": "Санкт-Петербург", // Локализованное название города
              "slug": "saint_petersburg", // Слаг
              "country": {
                  "name": "Россия", // Локализованное название страны
                  "code": "RU" // Код страны, верхний регистр, (TODO: RFC)
              }
          },
          "start_location": "Триумфальная арка", // Описание места начала маршрута
          "duration": "1-1,5 часа", // Время прохождения маршрута
          "price": "1290", // Цена
          "exprice": null, // Предыдущая цена. Отображать только, если не null и больше 0 – используется для акций
          "currency": { // Валюта в которой представлена цена товар
              "rate": 1,
              "code": "RUB",
              "symbol": "₽"
          },
          "bg_image": "https://app.surprizeme.ru/media/store/453_8jnsxX3.jpg", // Обложка товара, большая (до 2500пк)
          "preview_image": "https://app.surprizeme.ru/media/CACHE/images/store/453_8jnsxX3/4645de6eb27ef980adbbc7ca9bd5f825.jpg", // Обложка товара, превью (500×500пк)
          "author": { // Автор маршрута и пару слов об авторе
              "name": "Александр Головатый",
              "bio": ""
          },
          "reviews": [ // Отзывы 
              {
                  "name": "Ксения",
                  "text": "По дороге нашли много интересных мест поесть-попить) приятно провели время!)",
                  "avatar": null,
                  "rating": 0, // 1..5, 0 — если не указан
                  "date": "2017-10-02T11:46:00.548260Z"
              }
          ],
          "rating": null, // Рейтинг *Нестабильная фича, дорабатывается*
          "location_geo": { // Координаты места начала маршрута *Нестабильная фича, дорабатывается*
              "type": "Point",
              "coordinates": [
                  30.317885021179066,
                  59.9377545111065
              ]
          },
          "types": "citys", // *Нестабильная фича, дорабатывается*
      },
      ...
   ]
}

Создание ссылок

Для создания партнёрских ссылок на квест-экскурсии, вам понадобятся значения полей:

  • locale.code - код страны из запроса Товары;
  • city.slug - название города из запроса Товары;
  • category.slug - название категории из запроса Коллекции для города;
  • slug - уникальный идентификатор экскурсии из запроса Товары.

Сформируйте ссылку вида:

https://surprizeme.ru/<locale.code>/<city.slug>/<categor.slug>/<slug>/?sub_id=<sub_id>

где sub_id - ваш партнёрский маркер в Travelpayouts.

Пример для квест-экскурсии «Романтическая прогулка»:

https://surprizeme.ru/ru/sevastopol/popular/legendarnyij-sevastopol/?sub_id=78606

Была ли эта статья полезной?

Еще есть вопросы? Отправить запрос