Чтобы искать адреса только в определенном регионе или городе, укажите их в параметре locations
. Можно указать несколько ограничений.
Ограничение по КЛАДР-коду
Пример (Сахалинская область):
{ "query": "Ватутина", "locations": [{ "kladr_id": "65" }] }
Не рекомендуем использовать для объектов ниже города:
- не слишком надежно для населенных пунктов (КЛАДР-коды н/п довольно часто меняются);
- не работает для план. структур (они появились после того, как была придумана иерархия КЛАДР, и не вписываются в нее);
- очень ненадежно для улиц (КЛАДР-коды улиц часто меняются);
- не работает для домов.
Рекомендуем использовать ограничение по ФИАС-коду.
Ограничение по ФИАС-коду
Подсказки 21.12+
Указывается в параметре locations поле fias_id с ФИАС-кодом региона, области, города, населенного пункта либо улицы:
{ "query": "московское шоссе", "locations": [{ "fias_id": "110d6ad9-0b64-47cf-a2ee-7e935228799c" }] }
Ограничение по fias_id дома не поддерживается.
Подсказки 21.11 и раньше
В параметре locations для каждого уровня необходимо передавать соответствующие поля:
Поле | Описание |
---|---|
region_fias_id | Ограничение по ФИАС-коду региона |
area_fias_id | области |
city_fias_id | города |
settlement_fias_id | населенного пункта |
street_fias_id | улицы |
Пример (г Пушкин):
{ "query": "московское шоссе", "locations": [{ "city_fias_id": "110d6ad9-0b64-47cf-a2ee-7e935228799c" }] }
Ограничение по названию адресного объекта
Поле | Описание |
---|---|
region | Ограничение по названию региона |
area | района |
city | города |
settlement | населенного пункта |
street | улицы |
Москва:
{ "query": "Ботаническая", "locations": [{ "region": "москва" }] }
Несколько регионов:
{ "query": "ростов рассветная", "locations": [{ "region": "адыгея" }, { "region": "астраханская" }, { "region": "волгоградская" }, { "region": "калмыкия" }, { "region": "краснодарский" }, { "region": "ростовская" }] }
Тольятти:
{ "query": "Абрикосовая", "locations": [{ "region": "Самарская", "city": "Тольятти" }] }
Адрес без региона и города
Чтобы адрес одной строкой в ответе (поле value
) не содержал регион / город, заданный в ограничении, добавьте параметр restrict_value = true
:
{ "query": "Турчанинов", "locations": [ { "region": "Москва" } ], "restrict_value": true }
Ответ:
{ "suggestions": [ { "value": "Турчанинов пер", "unrestricted_value": "г Москва, Турчанинов пер", "data": { ... } }, { "value": "Турчанинов пер, д 2", "unrestricted_value": "г Москва, Турчанинов пер, д 2", "data": { ... } }, { "value": "Турчанинов пер, д 2А", "unrestricted_value": "г Москва, Турчанинов пер, д 2А", "data": { ... } }, { "value": "Турчанинов пер, д 3 стр 1", "unrestricted_value": "г Москва, Турчанинов пер, д 3 стр 1", "data": { ... } } ] }
При этом полный адрес тоже возвращается, в поле unrestricted_value
.
Ограничение по типу объекта
Поле | Описание |
---|---|
region_type_full | Ограничение по полному типу региона |
area_type_full | района в регионе |
city_type_full | города |
settlement_type_full | населенного пункта |
street_type_full | улицы |
Пример:
{ "query":"башко", "locations": [ { "region_type_full": "республика" } ] }
Ограничение по стране
Поле | Описание |
---|---|
country | Ограничение по названию страны |
country_iso_code | по коду страны в стандарте ISO 3166 (начиная с версии 19.7). |
Пример (country):
{ "query": "брест", "locations": [ { "country": "Беларусь" }, { "country": "Франция" } ] }
Пример (country_iso_code):
{ "query": "брест", "locations": [ { "country_iso_code": "BY" }, { "country_iso_code": "FR" } ] }
Для поиска по всем странам указывайте спецсимвол — звёздочку:
{ "query": "берлин", "locations": [ { "country": "*" } ] }
{ "query": "париж", "locations": [ { "country_iso_code": "*" } ] }
Ограничение по ISO-коду
Например, ISO-код страны:
{ "query": "бр", "locations": [ { "country_iso_code": "BY" } ] }
Или страны и региона:
{ "query": "бр", "locations": [ { "country_iso_code": "BY", "region_iso_code": "BY-BR" } ] }
Ограничение по радиусу окружности
Работает в «Подсказках» 20.4+. Требует лицензию на модули address и geo.
Ищет адреса в определенном радиусе от заданной точки.
Параметр | Обязательный? | Описание |
---|---|---|
lat | да | Географическая широта |
lon | да | Географическая долгота |
radius_meters | нет | Радиус поиска в метрах (по умолчанию – 100, максимум – 100000) |
Пример запроса:
{ "query": "Сухонская ", "locations_geo": [{ "lat": 59.244634, "lon": 39.913355, "radius_meters": 200 }] }
Ответ:
{ "suggestions": [ { "value": "г Вологда, ул Сухонская", "unrestricted_value": "160019, Вологодская обл, г Вологда, ул Сухонская", "data": { ... } }, { "value": "г Вологда, ул Сухонская, д 1а", "unrestricted_value": "160019, Вологодская обл, г Вологда, ул Сухонская, д 1а", "data": { ... } }, { "value": "г Вологда, ул Сухонская, д 1б", "unrestricted_value": "160019, Вологодская обл, г Вологда, ул Сухонская, д 1б", "data": { ... } } ] }