Ограничение сектора поиска адреса (API)

Чтобы искать адреса только в определенном регионе или городе, укажите их в параметре locations. Можно указать несколько ограничений.

Ограничение по КЛАДР-коду

Указывается в параметре 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"
    }]
}

Ограничение по названию адресного объекта

Указывается в параметре locations:

Поле	Описание
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.

Ограничение по типу объекта

Указывается в параметре locations:

Поле	Описание
region_type_full	Ограничение по полному типу региона
area_type_full	района в регионе
city_type_full	города
settlement_type_full	населенного пункта
street_type_full	улицы

Пример:

Запрос

{
	"query":"башко", 
	"locations": [
		{
			"region_type_full": "республика"
		}
	]
}

Ограничение по стране

По умолчанию подсказываются только адреса в России. Чтобы искать по другим странам, укажите ограничение в параметре запроса locations:

Поле	Описание
country	Ограничение по названию страны
country_iso_code	по коду страны в стандарте ISO 3166 (начиная с версии 19.7).

Пример (country):

{
    "query": "брест", 
    "locations": [
        {
            "country": "Беларусь"
        },
        {
            "country": "Франция"
        }
    ]
}

Пример (country_iso_code):

Начиная с версии 19.7

{
	"query": "брест", 
	"locations": [
		{
			"country_iso_code": "BY"
		},
		{
            "country_iso_code": "FR"
        }

	]
}

Для поиска по всем странам указывайте спецсимвол — звёздочку:

{
    "query": "берлин", 
    "locations": [
        {
            "country": "*"
        }
    ]
}

Начиная с версии 19.7

{
    "query": "париж", 
    "locations": [
        {
            "country_iso_code": "*"
        }
    ]
}

Ограничение по ISO-коду

Если подключены подсказки по всем странам мира, а не только по России, то удобно использовать 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
    }]
}