Подсказки по адресу (REST)

Запрос

Для пользователей подсказок DaData.ru:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Token ${API_KEY}" \
  -d '{ "query": "москва серпуховская" }' \
  https://dadata.ru/api/v2/suggest/address

Для пользователей standalone-подсказок:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "query": "москва серпуховская" }' \
  http://ВАШ_СЕРВЕР:ПОРТ/suggestions/api/4_1/rs/suggest/address

Заголовки

Заголовок

Описание

Content-Type

Тип данных в запроосе: application/json или application/xml

Accept

Тип данных в ответе: application/json или application/xml

Authorization

API-ключ в формате: Token ${API_KEY}

Только для пользователей подсказок DaData.ru

Параметры

Параметр	Обязательный?	Описание
`query`	да	Запрос, для которого нужно получить подсказки
count	нет	Количество возвращаемых подсказок (если не указано, используется значение по умолчанию).
locations	нет	Ограничение области поиска.

Ответ

Возвращается список объектов адреса:

Поле	Тип данных	Описание
value	string(1000)	Короткий адрес одной строкой
unrestricted_value	string(1000)	Длинный адрес одной строкой
data.postal_code	string(10)	Индекс
data.country	string(150)	Страна
data.country_iso_code	string(10)	Двухсимвольный код страны ISO 3166 (19.7+)
data.federal_district	string(50)	Федеральный округ (19.5+)
data.region_fias_id	string(50)	ФИАС-код региона для Белоруссии, Узбекистана и Казахстана — код OSM для остальных стран — код Geonames
data.region_kladr_id	string(20)	КЛАДР-код региона
data.region_iso_code	string(10)	Код региона ISO 3166 (19.7+)
data.region_with_type	string(150)	Регион с типом
data.region_type	string(10)	Тип региона (сокращенный)
data.region_type_full	string(50)	Тип региона
data.region	string(150)	Регион
data.area_fias_id	string(50)	ФИАС-код района в регионе для Белоруссии, Узбекистана и Казахстана — код OSM для остальных стран — код Geonames
data.area_kladr_id	string(20)	КЛАДР-код района в регионе
data.area_with_type	string(150)	Район в регионе с типом
data.area_type	string(10)	Тип района в регионе (сокращенный)
data.area_type_full	string(50)	Тип района в регионе
data.area	string(150)	Район в регионе
data.sub_area_fias_id	string(50)	ФИАС-код муниципального поселения (22.3+)
data.sub_area_kladr_id	string(20)	КЛАДР-код муниципального поселения (22.3+)
data.sub_area_with_type	string(150)	Муниципальное поселение с типом (22.3+)
data.sub_area_type	string(10)	Тип муниципального поселения (сокращенный) (22.3+)
data.sub_area_type_full	string(50)	Тип муниципального поселения (22.3+)
data.sub_area	string(150)	Муниципальное поселение (22.3+)
data.city_fias_id	string(50)	ФИАС-код города для Белоруссии, Узбекистана и Казахстана — код OSM для остальных стран — код Geonames
data.city_kladr_id	string(20)	КЛАДР-код города
data.city_with_type	string(150)	Город с типом
data.city_type	string(10)	Тип города (сокращенный)
data.city_type_full	string(50)	Тип города
data.city	string(150)	Город
data.city_district_fias_id	string(50)	Не заполняется
data.city_district_kladr_id	string(20)	Не заполняется
data.city_district_with_type **	string(150)	Адм. район города с типом
data.city_district_type **	string(10)	Тип адм. района города (сокращенный)
data.city_district_type_full **	string(50)	Тип адм. района города
data.city_district **	string(150)	Адм. район города
data.settlement_fias_id	string(50)	ФИАС-код нас. пункта для Белоруссии, Узбекистана и Казахстана — код OSM для остальных стран — код Geonames
data.settlement_kladr_id	string(20)	КЛАДР-код нас. пункта
data.settlement_with_type	string(150)	Населенный пункт с типом
data.settlement_type	string(20)	Тип населенного пункта (сокращенный)
data.settlement_type_full	string(50)	Тип населенного пункта
data.settlement	string(150)	Населенный пункт
data.street_fias_id	string(50)	ФИАС-код улицы для Белоруссии, Узбекистана и Казахстана — код OSM для остальных стран — код Geonames
data.street_kladr_id	string(20)	КЛАДР-код улицы
data.street_with_type	string(150)	Улица с типом
data.street_type	string(10)	Тип улицы (сокращенный)
data.street_type_full	string(50)	Тип улицы
data.street	string(150)	Улица
data.stead_fias_id	string(50)	ФИАС-код участка (21.12+)
data.stead_type	string(10)	Тип участка (сокращенный) (21.12+)
data.stead_type_full	string(50)	Тип участка (21.12+)
data.stead	string(50)	Участок (21.12+)
data.house_fias_id	string(50)	ФИАС-код дома для Белоруссии, Узбекистана и Казахстана — код OSM для остальных стран — код Geonames
data.house_kladr_id	string(20)	КЛАДР-код дома
data.house_flat_count	string(10)	Количество квартир в доме (24.3+)
data.house_type	string(10)	Тип дома (сокращенный)
data.house_type_full	string(50)	Тип дома
data.house	string(50)	Дом
data.block_type	string(10)	Тип корпуса/строения (сокращенный)
data.block_type_full	string(50)	Тип корпуса/строения
data.block	string(50)	Корпус/строение
data.flat_fias_id	string(50)	ФИАС-код квартиры ( 20.10+)
data.flat_type	string(10)	Тип квартиры (сокращенный)
data.flat_type_full	string(50)	Тип квартиры
data.flat	string(50)	Квартира
data.room_fias_id	string(50)	ФИАС-код комнаты (22.8+)
data.room_type	string(10)	Тип комнаты (сокращенный) (22.8+)
data.room_type_full	string(50)	Тип комнаты (22.8+)
data.room	string(50)	Комната (22.8+)
data.postal_box	string(50)	Абонентский ящик
data.fias_id	string(50)	ФИАС-код адреса для Белоруссии, Узбекистана и Казахстана — код OSM для остальных стран — код Geonames
data.fias_level	string(10)	Уровень детализации, до которого адрес найден в ФИАС: 0 — страна 1 — регион 3 — район 4 — город 5 — район города 6 — населенный пункт 7 — улица 8 — дом 9 — квартира (21.4+) 65 — планировочная структура 75 — земельный участок (21.12+) -1 — иностранный или пустой.
data.kladr_id	string(20)	КЛАДР-код адреса
data.geoname_id	string(20)	Идентификатор объекта в международной базе GeoNames.
data.capital_marker	string(10)	Признак центра района или региона: 1 — центр района (Московская обл, Одинцовский р-н, г Одинцово) 2 — центр региона (Новосибирская обл, г Новосибирск) 3 — центр района и региона (Томская обл, г Томск) 4 — центральный район региона (Тюменская обл, Тюменский р-н) 0 — ничего из перечисленного (Московская обл, г Балашиха)
data.okato	string(20)	Код ОКАТО
data.oktmo	string(20)	Код ОКТМО
data.tax_office	string(10)	Код ИФНС для физических лиц
data.tax_office_legal	string(10)	Код ИФНС для организаций
data.source	string(250)	Для организаций — адрес как в ЕГРЮЛ. Для банков — адрес как в справочнике БИК. В остальных случаях — пустое.
data.history_values[ ]	string[](250)	Список исторических названий объекта нижнего уровня. Если подсказка до улицы — это прошлые названия этой улицы, если до города — города.
Дополнительные поля, заполняются в зависимости от тарифа «Дадаты» *
Все тарифы «Дадаты»
data.geo_lat	string(20)	Координаты: широта
data.geo_lon	string(20)	Координаты: долгота
data.qc_geo	string(10)	Код точности координат: 0 — точные координаты 1 — ближайший дом 2 — улица 3 — населенный пункт 4 — город 5 — координаты не определены, отсутствуют в справочнике 6 — не загружен справочник с геокоординатами
data.fias_actuality_state	string(10)	Признак актуальности адреса в ФИАС: 0 — актуальный 1–50 — переименован 51 — переподчинен 99 — удален
data.city_area	string(150)	Административный округ (только для Москвы)
Тарифы «Расширенный» и «Максимальный»
data.beltway_hit	string(10)	Внутри кольцевой?
data.beltway_distance	string(10)	Расстояние от кольцевой в километрах
Тариф «Максимальный»
data.stead_cadnum	string(100)	Кадастровый номер участка (22.4+),
data.house_cadnum	string(100)	Кадастровый номер дома (22.4+)
data.flat_cadnum	string(100)	Кадастровый номер квартиры (22.4+)
data.flat_area	string(50)	Площадь квартиры
data.square_meter_price	string(50)	Рыночная стоимость м²
data.flat_price	string(50)	Рыночная стоимость квартиры
data.room_cadnum	string(100)	Кадастровый номер комнаты (22.8+)
data.timezone	string(50)	Часовой пояс
data.metro[ ] ** └ name └ line └ distance	string(50) string(50) double	Ближайшие станции метро (не более 3 станций в радиусе 5 км): — название станции — название линии — расстояние до станции в километрах
Не заполняются
data.entrance	string(10)	Подъезд (21.1+)
data.floor	string(10)	Этаж (21.1+)
data.fias_code	string(50)	Классификационный код ФИАС
data.qc_complete	string(10)	Код пригодности к рассылке
data.qc_house	string(10)	Код проверки дома
data.qc	string(10)	Код проверки
data.unparsed_parts	string(250)	Нераспознанная часть адреса
data.divisions	{}	Поля адреса в Административно-территориальном и Муниципальном деленииях (22.3+)
data.custom	[ ]	Зарезервировано (23.5+)

^* Для «коробки» заполненность полей зависит от лицензии. Уточните детали в технической поддержке.

** Поля заполняются при выборе конкретной подсказки или через метод API findById. До этого они пустые.

value

Поле value содержит адрес одной строкой от региона до квартиры. Склеивается из полей:

data.region_with_type (регион с типом),
data.area_with_type (район в регионе с типом),
data.city_with_type (город с типом),
data.settlement_with_type (населенный пункт с типом),
data.street_with_type (улица с типом),
data.stead_type (тип участка),
data.stead (участок),
data.house_type (тип дома),
data.house (дом),
data.block_type (тип корпуса/строения),
data.block (корпус/строение),
data.flat_type (тип квартиры),
data.flat (квартира),
data.room_type (тип комнаты),
data.room (комната).

При этом применяются правила сокращения адреса для деловой переписки:

если город — областной центр, область не пишется (Новосибирская обл, г Новосибирск → г Новосибирск);
если город — центр района, не пишется район (Респ Татарстан, Верхнеуслонский р-н, село Верхний Услон → Респ Татарстан, село Верхний Услон).

Для адресов в муниципальном делении действуют более сложные правила, которые записывают адрес в удобочитаемом виде (мун. деление в оригинале очень громоздкое). Примеры:

region_with_type: Московская обл
area_with_type: г.о. Одинцовский
city_with_type: г Одинцово
→ value = Московская обл, г Одинцово

region_with_type: г Москва
area_with_type: вн.тер.г. городской округ Щербинка
city_with_type: г Щербинка
street_with_type: Остафьевское шоссе
→ value = г Москва, г Щербинка, Остафьевское шоссе

region_with_type: г Москва
area_with_type: вн.тер.г. муниципальный округ Северное Медведково
street_with_type: ул Сухонская
house_type: д
house: 11
→ value = г Москва, ул Сухонская, д 11

region_with_type: Самарская обл
area_with_type: г.о. Самара
sub_area_with_type: вн.р-н Железнодорожный
city_with_type: г Самара
street_with_type: ул Сакко и Ванцетти
house_type: д
house: 20
→ value = Самарская обл, г Самара, ул Сакко и Ванцетти, д 20

Если в запросе к API указан параметр restrict_value, то в поле value возвращается только часть адреса, которая подходит под ограничение. Например:

region = Москва, restrict_value = false, query = сакко
→ value = г Самара, ул Сакко и Ванцетти

region = Москва, restrict_value = true, query = сакко
→ value = ул Сакко и Ванцетти

unrestricted_value

Поле unrestricted_value содержит адрес одной строкой от индекса до квартиры. Оно склеивается из полей:

data.postal_code (индекс),
data.region_with_type (регион с типом),
data.area_with_type (район в регионе с типом),
data.sub_area_with_type (мун. поселение с типом),
data.city_with_type (город с типом),
data.city_district_with_type (адм. район города с типом),
data.settlement_with_type (населенный пункт с типом),
data.street_with_type (улица с типом),
data.stead_type (тип участка),
data.stead (участок),
data.house_type (тип дома),
data.house (дом),
data.block_type (тип корпуса/строения),
data.block (корпус/строение),
data.flat_type (тип квартиры),
data.flat (квартира),
data.room_type (тип комнаты),
data.room (комната).

Сокращение по правилам деловой переписки к unrestricted_value не применяется и параметр restrict_value на него не влияет.

Административное и муниципальное деление

Работает в «Подсказках» 22.4+

Подсказки могут возвращать адрес в административном либо в муниципальном делении. Это регулирует параметр запроса division:

administrative — административное;
municipal — муниципальное.

Если параметр не задан, используется административное деление.

В муниципальном делении возвращаются поля area* (муниципальный район) и sub_area* (муниципальное поселение). Поля city_district* (административный район города), напротив, скрываются.

В административном делении возвращаются поля area* (административный район региона) и city_district* (административный район города). Поля sub_area* (муниципальное поселение), напротив, скрываются.

Примеры

Запрос

{
  "query": "москва серпуховская" 
}

Ответ:

{
    "suggestions": [
        {
            "value": "г Москва, Серпуховская пл",
            "unrestricted_value": "г Москва, Серпуховская пл",
            "data": {
                "qc_complete": null,
                "qc_house": null,
                "postal_code": "115184",
                "postal_box": null,
                "country": "Россия",
                "region_type": "г",
                "region_type_full": "город",
                "region": "Москва",
                "area_type": null,
                "area_type_full": null,
                "area": null,
                "city_type": null,
                "city_type_full": null,
                "city": null,
                "settlement_type": null,
                "settlement_type_full": null,
                "settlement": null,
                "street_type": "пл",
                "street_type_full": "площадь",
                "street": "Серпуховская",
                "house_type": null,
                "house_type_full": null,
                "house": null,
                "block_type": null,
                "block": null,
                "flat_area": null,
                "flat_type": null,
                "flat": null,
                "tax_office": "7705",
                "kladr_id": "77000000000702000",
                "okato": "45286560000",
                "oktmo": null,
                "unparsed_parts": null,
                "qc": null
            }
        },
        {
            "value": "г Москва, ул Серпуховская Б.",
            "unrestricted_value": "г Москва, ул Серпуховская Б.",
            "data": {
                "qc_complete": null,
                "qc_house": null,
                "postal_code": "115093",
                "postal_box": null,
                "country": "Россия",
                "region_type": "г",
                "region_type_full": "город",
                "region": "Москва",
                "area_type": null,
                "area_type_full": null,
                "area": null,
                "city_type": null,
                "city_type_full": null,
                "city": null,
                "settlement_type": null,
                "settlement_type_full": null,
                "settlement": null,
                "street_type": "ул",
                "street_type_full": "улица",
                "street": "Серпуховская Б.",
                "house_type": null,
                "house_type_full": null,
                "house": null,
                "block_type": null,
                "block": null,
                "flat_area": null,
                "flat_type": null,
                "flat": null,
                "tax_office": "",
                "kladr_id": "77000000000262500",
                "okato": "",
                "oktmo": null,
                "unparsed_parts": null,
                "qc": null
            }
        },
        {
            "value": "г Москва, пл Серпуховская Застава",
            "unrestricted_value": "г Москва, пл Серпуховская Застава",
            "data": {
                "qc_complete": null,
                "qc_house": null,
                "postal_code": "115191",
                "postal_box": null,
                "country": "Россия",
                "region_type": "г",
                "region_type_full": "город",
                "region": "Москва",
                "area_type": null,
                "area_type_full": null,
                "area": null,
                "city_type": null,
                "city_type_full": null,
                "city": null,
                "settlement_type": null,
                "settlement_type_full": null,
                "settlement": null,
                "street_type": "пл",
                "street_type_full": "площадь",
                "street": "Серпуховская Застава",
                "house_type": null,
                "house_type_full": null,
                "house": null,
                "block_type": null,
                "block": null,
                "flat_area": null,
                "flat_type": null,
                "flat": null,
                "tax_office": "7725",
                "kladr_id": "77000000000262600",
                "okato": "45296559000",
                "oktmo": null,
                "unparsed_parts": null,
                "qc": null
            }
        }
  ]
}

Запрос:

<req>
  <query>москва серпуховская</query>
</req>

Ответ:

<SuggestAddressResponse>
    <suggestions>
        <value>г Москва, Серпуховская пл</value>
        <unrestricted_value>г Москва, Серпуховская пл</unrestricted_value>
        <data>
            <qc_complete/>
            <qc_house/>
            <postal_code>115184</postal_code>
            <postal_box/>
            <country>Россия</country>
            <region_type>г</region_type>
            <region_type_full>город</region_type_full>
            <region>Москва</region>
            <area_type/>
            <area_type_full/>
            <area/>
            <city_type/>
            <city_type_full/>
            <city/>
            <settlement_type/>
            <settlement_type_full/>
            <settlement/>
            <street_type>пл</street_type>
            <street_type_full>площадь</street_type_full>
            <street>Серпуховская</street>
            <house_type/>
            <house_type_full/>
            <house/>
            <block_type/>
            <block/>
            <flat_area/>
            <flat_type/>
            <flat/>
            <tax_office>7705</tax_office>
            <kladr_id>77000000000702000</kladr_id>
            <okato>45286560000</okato>
            <oktmo/>
            <unparsed_parts/>
            <qc/>
        </data>
    </suggestions>
    <suggestions>
        <value>г Москва, ул Серпуховская Б.</value>
        <unrestricted_value>г Москва, ул Серпуховская Б.</unrestricted_value>
        <data>
            <qc_complete/>
            <qc_house/>
            <postal_code>115093</postal_code>
            <postal_box/>
            <country>Россия</country>
            <region_type>г</region_type>
            <region_type_full>город</region_type_full>
            <region>Москва</region>
            <area_type/>
            <area_type_full/>
            <area/>
            <city_type/>
            <city_type_full/>
            <city/>
            <settlement_type/>
            <settlement_type_full/>
            <settlement/>
            <street_type>ул</street_type>
            <street_type_full>улица</street_type_full>
            <street>Серпуховская Б.</street>
            <house_type/>
            <house_type_full/>
            <house/>
            <block_type/>
            <block/>
            <flat_area/>
            <flat_type/>
            <flat/>
            <tax_office></tax_office>
            <kladr_id>77000000000262500</kladr_id>
            <okato></okato>
            <oktmo/>
            <unparsed_parts/>
            <qc/>
        </data>
    </suggestions>
    <suggestions>
        <value>г Москва, пл Серпуховская Застава</value>
        <unrestricted_value>г Москва, пл Серпуховская Застава</unrestricted_value>
        <data>
            <qc_complete/>
            <qc_house/>
            <postal_code>115191</postal_code>
            <postal_box/>
            <country>Россия</country>
            <region_type>г</region_type>
            <region_type_full>город</region_type_full>
            <region>Москва</region>
            <area_type/>
            <area_type_full/>
            <area/>
            <city_type/>
            <city_type_full/>
            <city/>
            <settlement_type/>
            <settlement_type_full/>
            <settlement/>
            <street_type>пл</street_type>
            <street_type_full>площадь</street_type_full>
            <street>Серпуховская Застава</street>
            <house_type/>
            <house_type_full/>
            <house/>
            <block_type/>
            <block/>
            <flat_area/>
            <flat_type/>
            <flat/>
            <tax_office>7725</tax_office>
            <kladr_id>77000000000262600</kladr_id>
            <okato>45296559000</okato>
            <oktmo/>
            <unparsed_parts/>
            <qc/>
        </data>
    </suggestions>
</SuggestAddressResponse>

Дерево страниц

Подсказки по адресу (REST)

Запрос

Заголовки

Параметры

Ответ

value

unrestricted_value

Административное и муниципальное деление

Примеры