Skip to content

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

Request

Выполняет поиск мастеров с поддержкой текстового поиска, фильтрации по категории, диапазону цен и одному географическому режиму.

Особенности:

  • q необязателен; пустое значение считается отсутствующим
  • category_id включает выбранную категорию и все её подкатегории; для конечной категории ищется только она
  • одновременно разрешён только один географический режим: точка, адрес, метро или районы
  • режим по профилю: если георежим не передан, используется геолокация профиля и сортировка от ближайших
  • режим точки: lat + lon + radius_m; мастера фильтруются по радиусу и сортируются согласно sort
  • один мастер может иметь до трёх локаций: AT_MASTER_PLACE, IN_SALON, CLIENT_PLACE; наружу всегда возвращается один результат на user_id
  • для AT_MASTER_PLACE и IN_SALON в режиме точки применяется переданный radius_m в метрах (100..10000)
  • для CLIENT_PLACE точка пользователя должна находиться внутри собственного radius_km мастера (1, 5, 10 или 20 км); переданный radius_m эту локацию не ограничивает
  • варианты одного мастера устраняются по user_id; поля address, distance_meters, service_location, salon_name и radius_km относятся к выбранному варианту
  • при RELEVANCE, сортировке по цене или рейтингу вариант выбирается по приоритету AT_MASTER_PLACE → IN_SALON → CLIENT_PLACE; при DISTANCE_ASC/DISTANCE_DESC сначала учитывается расстояние в выбранном направлении, затем приоритет
  • режим адреса: address; адрес геокодируется, а найденная точка используется для сортировки от ближайших
  • режим метро: city + один или несколько параметров metro; metro_minutes необязателен
  • если metro_minutes передан, вокруг каждой станции применяется радиус metro_minutes * 80 метров; без него мастера только сортируются по близости
  • при нескольких метро расстояние мастера равно минимуму расстояний до выбранных станций; результаты объединяются без дублей
  • режим районов: city + один или несколько параметров district
  • для метро и районов можно передать любое количество значений, в том числе все значения города
  • несуществующая станция, район или город не игнорируются: возвращается 400 invalid_body
  • несколько метро поддерживают только сортировки RELEVANCE и DISTANCE_ASC
  • для поиска по районам сортировки DISTANCE_ASC и DISTANCE_DESC недоступны, а distance_meters равен null
  • районная принадлежность вычисляется по полигонам и хранится во внутреннем districtIds
  • если гео профиля отсутствует и явный георежим не передан, возвращается 400 invalid_body
  • для каждого мастера возвращается ближайшая дата и все свободные часовые слоты этой даты в пределах 60 дней (сегодня и следующие 59 дней)
  • часовые слоты рассчитываются по календарю мастера без привязки к длительности конкретной услуги
  • price_to должен быть больше или равен price_from
  • требуется JWT
  • при превышении лимита поиска возвращается 429 too_many_request с data.TTL
Security
bearerAuth or jwtCookie
Query
qstring, <= 80 characters

Необязательный поисковый запрос. Пустая строка считается отсутствующим значением.

Example:q=hair
category_idinteger, (int64), >= 1

Идентификатор категории услуги второго уровня, которую оказывает мастер.

Example:category_id=10
latnumber, (double), [ -90 .. 90 ]

Широта пользовательской точки. Передаётся только вместе с lon и radius_m.

Example:lat=53.9
lonnumber, (double), [ -180 .. 180 ]

Долгота пользовательской точки. Передаётся только вместе с lat и radius_m.

Example:lon=27.56
radius_minteger, [ 100 .. 10000 ]

Радиус поиска в метрах для AT_MASTER_PLACE и IN_SALON. Допустим только вместе с lat и lon. Для CLIENT_PLACE используется собственный радиус мастера radius_km.

Example:radius_m=5000
addressstring, <= 300 characters

Адрес, который будет геокодирован и использован как точка сортировки.

Example:address=Москва, Тверская улица, 10
citystring, <= 100 characters

Город выбранных метро или районов.

Example:city=Москва
metroArray of strings

Названия выбранных станций. Параметр можно повторять без ограничения; можно передать все станции выбранного города.

Example:metro=Курская&metro=Бауманская
metro_minutesinteger, [ 5 .. 30 ]

Радиус вокруг каждой станции в минутах, одна минута равна 80 метрам.

Example:metro_minutes=15
districtArray of strings

Названия выбранных районов. Параметр можно повторять без ограничения; районы объединяются через OR.

Example:district=Арбат&district=Хамовники
price_frominteger, >= 0

Минимальная цена услуг мастера.

Example:price_from=1000
price_tointeger, >= 0

Максимальная цена услуг мастера. Должна быть больше или равна price_from.

Example:price_to=6000
sortstring(MasterSearchSort)

Порядок сортировки результата.

Enum:"RELEVANCE""PRICE_ASC""PRICE_DESC""RATING_ASC""RATING_DESC""DISTANCE_ASC""DISTANCE_DESC"
Example:sort=PRICE_ASC
offsetinteger, >= 0

Сколько записей пропустить.

Default:0
Example:offset=0
limitinteger, [ 1 .. 50 ]

Сколько мастеров вернуть.

Default:20
Example:limit=20
curl -i -X GET \
  'https://felmee.com/api/search/masters?q=hair&category_id=10&lat=53.9&lon=27.56&radius_m=5000&address=%D0%9C%D0%BE%D1%81%D0%BA%D0%B2%D0%B0%2C%20%D0%A2%D0%B2%D0%B5%D1%80%D1%81%D0%BA%D0%B0%D1%8F%20%D1%83%D0%BB%D0%B8%D1%86%D0%B0%2C%2010&city=%D0%9C%D0%BE%D1%81%D0%BA%D0%B2%D0%B0&metro=%D0%9A%D1%83%D1%80%D1%81%D0%BA%D0%B0%D1%8F%2C%D0%91%D0%B0%D1%83%D0%BC%D0%B0%D0%BD%D1%81%D0%BA%D0%B0%D1%8F&metro_minutes=15&district=%D0%90%D1%80%D0%B1%D0%B0%D1%82%2C%D0%A5%D0%B0%D0%BC%D0%BE%D0%B2%D0%BD%D0%B8%D0%BA%D0%B8&price_from=1000&price_to=6000&sort=PRICE_ASC&offset=0&limit=20' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Мастера успешно найдены

Bodyapplication/json
codeErrorstring or nullrequired

Устаревший camelCase-alias поля error_code; при ошибке оба поля содержат одинаковое значение.

successbooleanrequired

Флаг успешного выполнения запроса

messagestringrequired

Человекочитаемое описание результата

error_codestring or null(ERROR_CODE)required

Код ошибки. Для успешных ответов всегда null.

Enum:"invalid_body""unauthorized""not_found""conflict""object_modified_by_another_thread""action_too_late""too_many_request""code_is_gone""forbidden""user_blocked"
dataobject or nullrequired

Полезная нагрузка. Может быть объектом, массивом или null.

Response
{
  "success": true,
  "message": "Masters retrieved successfully",
  "error_code": null,
  "data": {
    "items": [ … ],
    "has_more": true
  }
}