Фильтрация экскурсий

1 Параметры запроса
2 Структура ответа
- 2.1 Пример ответа API
3 Описание ответа
- 3.1 Основные параметры
- 3.2 Дополнительные параметры

API позволяет искать подходящие экскурсии, используя различные фильтры. Для поиска экскурсий используйте метод https://experience.tripster.ru/api/search/experiences/.

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

Фильтры
- city – обязательный параметр, фильтр по ID города
- citytag фильтр по ID рубрики, либо group/special_offers
- query поиск по тексту
- persons_count количество человек
- start_price минимальная стоимость
- end_price максимальная стоимость
- start_date дата "от" включительно в формате YYYY-MM-DD
- end_date дата "по" включительно в формате YYYY-MM-DD
Сортировка
- sorting возможные варианты: '-popularity' (по популярности, по умолчанию), '-rating' (по рейтингу отзывов, по убыванию) , 'price' (по цене, по возрастанию). При передаче параметра query доступен и используется по умолчанию 'relevance'.
Набор данных
- detailed=false сокращенный набор полей. Используйте для загрузки списка экскурсий и отображения его у себя в реальном времени.
- detailed=true расширенный набор полей. Используйте для загрузки полных данных по экскурсиям к себе в БД, а также для отображения одной экскурсии в реальном времени.
Запрос обновленных данных
- updated_after=YYYY-MM-DD или YYYY-MM-DD HH:MM:SS будут возвращены экскурсии, которые изменились с этого времени
Доп. параметры
- need_results - отдавать результаты поиска. По умолчанию true
- need_aggregations - отдавать агрегированные данные по умолчанию false
Стандартные параметры format и page_size, прочитайте про постраничную загрузку данных

Структура ответа

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

results [
{
    "count": 216,
    "next": "https://experience.tripster.ru/api/search/experiences/?city=3&page=2",
    "previous": null,
    "results": [
        {
            "id": 13530,
            "title": "Монастырь на Казбеке — «высоко над семьею гор»",
            "tagline": "Побывать в месте, воспетом Пушкиным и ставшим одним из символов Грузии",
            "url": "https://experience.tripster.ru/experience/13530/",
            "is_new": false,
            "type": "group",
            "instant_booking": true,
            "child_friendly": true,
            "max_persons": 20,
            "duration": 10.0,
            "meeting_point": {
                "text": "в районе площади Мейдан"
            },
            "price": {
                "value": 25.0,
                "currency": "EUR",
                "price_from": false,
                "unit_string": "за человека",
                "value_string": "€25 за человека",
                "discount": {
                    "value": 0.4,
                    "expiration_date": "2019-07-07",
                    "expiration_text": "",
                    "original_price": 41.0
                }
            },
            "review_count": 463,
            "rating": 4.78,
            "popularity": 103170,
            "guide": {
                "id": 136254,
                "first_name": "Давид",
                "url": "https://experience.tripster.ru/guide/136254/",
                "avatar": {
                    "small": "https://experience-ireland.s3.amazonaws.com/avatar/65484e1c-7312-11e8-b3c5-6e714efd800d.31x31.jpg",
                    "medium": "https://experience-ireland.s3.amazonaws.com/avatar/653e91d8-7312-11e8-b3c5-6e714efd800d.150x150.jpg"
                },
                "rating": 4.68,
                "review_count": 772,
                "avg_reaction_delay": null,
                "links": {
                    "reviews": "https://experience.tripster.ru/api/guides/136254/reviews/"
                }
            },
            "photos": [
                {
                    "thumbnail": "https://experience-ireland.s3.amazonaws.com/thumbs2/07ac3232-852d-11e8-9de2-0ac55974a77a.384x289.jpg",
                    "medium": "https://experience-ireland.s3.amazonaws.com/thumbs2/bd68c2fa-852c-11e8-9de2-0ac55974a77a.800x600.jpg"
                }
            ],
            "links": {
                "reviews": "https://experience.tripster.ru/api/experiences/13530/reviews/",
                "schedule": "https://experience.tripster.ru/api/experiences/13530/schedule/"
            },
            "status": "active"
        },

...

],
    "aggregations": {
        "date": [
            "2019-04-22T17:30:00",
            "2019-10-19T00:00:00"
        ],
        "price": {
            "histogram_interval": 0.164,
            "range": [
                20.0,
                720.0
            ],
            "histogram": {
                "20": 3,
                "23": 2,
                "27": 7,
                "32": 7,
                "37": 2,
                "44": 11,
                "52": 7,
                "61": 10,
                "72": 13,
                "84": 17,
                "99": 14,
                "117": 38,
                "138": 27,
                "162": 18,
                "191": 8,
                "225": 16,
                "265": 7,
                "312": 4,
                "367": 1,
                "432": 1,
                "509": 0,
                "600": 2,
                "707": 1
            },
            "persons_count": 1
        },
        "availability": {
            "1": 216,
            "2": 215,
            "3": 213,
            "4": 196,
            "5": 173,
            "6": 145,
            "7": 98,
            "8": 89,
            "9": 59,
            "10": 55
        },
        "tags": {
            "all": 216,
            "25": 61,
            "193": 58,
            "23": 40,
            "310": 37,
            "group": 30,
            "194": 24,
            "16": 20,
            "18": 14,
            "7641": 12,
            "19": 10,
            "special_offers": 10,
            "7326": 9,
            "21": 7,
            "324": 7,
            "6522": 7,
            "3249": 2,
            "311": 1,
            "3248": 1
        }
    }
}

Описание ответа

Основные параметры

Параметр	Описание	Тип

Параметр	Описание	Тип
id	ID экскурсии в Трипстере	Число
title	Название экскурсии	Строка
tagline	Пояснение к названию для вывода в списке экскурсии	Строка
url	Ссылка на страницу экскурсии на Трипстере (прочитайте про правила формирования ссылок)	Строка
type	Тип экскурсии: private – индивидуальная, group – групповая	Строка
instant_booking	Возможно ли моментальное бронирование экскурсии: true или false	Boolean
child_friendly	Подходит ли экскурсия детям: true или false	Boolean
max_persons	Максимальное число участников экскурсии	Число
duration	Продолжительность экскурсии в часах	Float
meeting_point	Объект с данными о месте встречи	Объект
meeting_point.text	Строка с описанием места встречи. Может быть пустой строкой ""	Строка
price	Объект с данными о цене экскурсии (посмотрите на картинку с объяснением параметров)	Объект
price.value	Цена экскурсии	Float
price.currency	Валюта экскурсии, совпадает с валютой страны	Строка
price.price_from	Точная ли цена или это "цена от": false – точная, true – цена "от"	Boolean
price.unit_string	Тип цены "за человека" или "за экскурсию"	Строка
price.value_string	Сформированная строка с описанием цены экскурсии, по которой можно проверить понимание остальных параметров	Строка
price.discount	Объект со скидкой на экскурсию, или null, если скидки нет	Объект
price.discount.value	Размер скидки, "0.3" значит скидку 30%	Float
price.discount.expiration_date	Дата окончания действия скидки, скидка предоставляется для всех заказов, сделанных до этой даты	Дата в формате YYYY-MM-DD
price.discount.expiration_text	Подсказка о скором завершении действии скидки. Например, "еще 3 дня"	Строка
price.discount.original_price	Оригинальная цена до скидки, чтобы показать ее зачеркнутой	Float
review_count	Количество отзывов	Число
rating	Рейтинг экскурсий от 0 до 5	Float
popularity	Индекс популярности, его можно использовать для самостоятельной сортировке экскурсий по популярности	Число
guide	Объект с данными о гиде	Объект
schedule	Объект расписания экскурсии. Отображается, если передать параметр detailed=true	Объект
schedule.text	Расписание экскурсии "ежедневно в 10:00". Отображается, если передать параметр detailed=true	Строка
photos	Список фотографий экскурсии, первая в списке фотография – для использования в листинге экскурсий. Если передать параметр detailed=true, отобразятся все фотографии. Если detailed=false – только первая.	Список
photos.thumbnail	Ссылка на картинку-превьюшку города размером 384x289px	Строка
photos.medium	Ссылка на картинку-превьюшку города размером 800x600px	Строка
links.reviews	Ссылка на api отзывов для данной экскурсии	Строка

Дополнительные параметры

Aggregations, если передан need_aggregations=true, отдаёт дополнительные данные, которые можно использовать в фильтрах по дате, цене, количеству человек, рубрикам.

Параметр	Описание	Тип

Параметр	Описание	Тип
date	Массив из двух дат, в пределах которых возможен поиск экскурсий. Например, "date": [ "2019-04-22T17:30:00", "2019-10-19T00:00:00" ],	Массив дат в формате YYYY-MM-DDTHH:MM:SS
price	Объект, содержащий информацию о цене	Объект
price.range	Массив из двух дат, в пределах которых возможен поиск по ценам.	Массив Float
price.histogram	Позволяет построить график цен на экскурсии в логарифмической шкале. Объект, содержащий пары ключ-значение (например, {"20": 3, "23": 2}).	Массив ключ (строка) значение (Float)
price.persons_count	Количество людей, для которых произведён подсчёт цен	Число
availability	Позволяет узнать количество экскурсий в выдаче, если изменить количество человек в поиске. Объект, содержащий пары ключ-значение (например, {"1": 216, "2": 180}).	Массив ключ (строка) значение (Float)
tags	Позволяет узнать количество экскурсий в выдаче при выборе другой рубрики. Объект, содержащий пары ключ-значение (например, {"all": 216, "25": 61, "group": 30})	Массив ключ (строка) значение (Число)