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

Помогает человеку быстро ввести корректный адрес на веб-форме или в приложении. Для России и всего мира.

Ищет адреса по любой части адреса от региона до дома («тверская нижний 12» → «Нижегородская обл, г Нижний Новгород, ул Тверская, д 12»). Также ищет по почтовому индексу («105568» → «г Москва, ул Магнитогорская»).

Что умеет:

✔️ Работает по всем странам мира (по России и Белоруссии до дома, по остальным странам — до города). Ищет и показывает результаты как на русском языке («Самара, пр-кт Металлургов»), так и на английском («Russia, gorod Samara, prospekt Metallurgov»).

✔️ Находит актуальные адреса по историческим названиям (Свердловск → Екатеринбург) и синонимам (Питер → Санкт-Петербург).

✔️ Ищет по частичному совпадению («москва болот» → «г Москва, Болотная наб»), но только в последнем слове запроса («мос болот» не найдет).

✔️ Исправляет опечатки («самара авиционная») и запросы в неправильной раскладке («vjcrdf» → «москва»).

✔️ Раскладывает выбранный адрес на гранулярные части (от региона до квартиры).

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

✔️ Подсказывает адреса в конкретных регионах, районах, городах и населенных пунктах. Понимает названия («Петергоф»), коды КЛАДР («7800000800000») и ФИАС («8f238984-812b-4bb1-850b-49749fb5c56d»).

✔️ Учитывает, где вы находитесь (в связке с методом город по IP-адресу).

Не умеет:

❌ Автоматически (без участия человека) обработать адреса из базы или файла.

❌ Транслитерировать (moskva suhonskaja 11 → 127642, г Москва, ул Сухонская, д 11).

Подсказки не подходят для автоматической обработки адресов. Они предлагают варианты, но не гарантируют, что угадали правильно. Поэтому окончательное решение всегда должен принимать человек.

Запрос

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 ВАШ_КЛЮЧ

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

Параметры

Параметр	Обязательный?	Описание
`query`	да	Запрос, для которого нужно получить подсказки
count	нет	Количество возвращаемых подсказок (по умолчанию — 10, максимум — 20).
locations	нет	Ограничение области поиска
locations_geo	нет	Географическое ограничение 20.4+
`locations_boost`	нет	Приоритет города при ранжировании
`from_bound` `to_bound`	нет	Гранулярные подсказки по адресу
language	нет	Язык отображения адреса в результатах поиска (en/ru) 20.3+

Ответ

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

Показать

Поле	Описание
value	Короткий адрес одной строкой
unrestricted_value	Длинный адрес одной строкой
data.postal_code	Индекс
data.country	Страна
data.country_iso_code	Двухсимвольный код страны ISO 3166 (19.7+)
data.federal_district	Федеральный округ (19.5+)
data.region_fias_id	Код ФИАС региона (либо код OSM, начиная с версии 20.7)
data.region_kladr_id	Код КЛАДР региона
data.region_iso_code	Код региона ISO 3166 (19.7+)
data.region_with_type	Регион с типом
data.region_type	Тип региона (сокращенный)
data.region_type_full	Тип региона
data.region	Регион
data.area_fias_id	Код ФИАС района в регионе (либо код OSM, начиная с версии 20.7)
data.area_kladr_id	Код КЛАДР района в регионе
data.area_with_type	Район в регионе с типом
data.area_type	Тип района в регионе (сокращенный)
data.area_type_full	Тип района в регионе
data.area	Район в регионе
data.city_fias_id	Код ФИАС города (либо код OSM, начиная с версии 20.7)
data.city_kladr_id	Код КЛАДР города
data.city_with_type	Город с типом
data.city_type	Тип города (сокращенный)
data.city_type_full	Тип города
data.city	Город
data.city_district_fias_id	Код ФИАС района города (либо код OSM, начиная с версии 20.7)
data.city_district_kladr_id	Код КЛАДР района города
data.city_district_with_type	Район города с типом
data.city_district_type	Тип района города (сокращенный)
data.city_district_type_full	Тип района города
data.city_district	Район города
data.settlement_fias_id	Код ФИАС нас. пункта (либо код OSM, начиная с версии 20.7)
data.settlement_kladr_id	Код КЛАДР нас. пункта
data.settlement_with_type	Населенный пункт с типом
data.settlement_type	Тип населенного пункта (сокращенный)
data.settlement_type_full	Тип населенного пункта
data.settlement	Населенный пункт
data.street_fias_id	Код ФИАС улицы (либо код OSM, начиная с версии 20.7)
data.street_kladr_id	Код КЛАДР улицы
data.street_with_type	Улица с типом
data.street_type	Тип улицы (сокращенный)
data.street_type_full	Тип улицы
data.street	Улица
data.house_fias_id	Код ФИАС дома (либо код OSM, начиная с версии 20.7)
data.house_kladr_id	Код КЛАДР дома
data.house_type	Тип дома (сокращенный)
data.house_type_full	Тип дома
data.house	Дом
data.block_type	Тип корпуса/строения (сокращенный)
data.block_type_full	Тип корпуса/строения
data.block	Корпус/строение
data.flat_fias_id	Код ФИАС квартиры (20.10+)
data.flat_type	Тип квартиры (сокращенный)
data.flat_type_full	Тип квартиры
data.flat	Квартира
data.postal_box	Абонентский ящик
data.fias_id	Код ФИАС: `HOUSE.HOUSEGUID`, если дом найден в ФИАС по точному совпадению; `ADDROBJ.AOGUID` в противном случае. Либо код OSM (начиная с версии 20.7)
data.fias_level	Уровень детализации, до которого адрес найден в ФИАС: 0 — страна 1 — регион 3 — район 4 — город 5 — район города 6 — населенный пункт 7 — улица 8 — дом 65 — планировочная структура -1 — иностранный или пустой.
data.kladr_id	Код КЛАДР
data.geoname_id	Идентификатор объекта в международной базе GeoNames. Для российских адресов не заполняется.
data.capital_marker	Признак центра района или региона: 1 — центр района (Московская обл, Одинцовский р-н, г Одинцово) 2 — центр региона (Новосибирская обл, г Новосибирск) 3 — центр района и региона (Томская обл, г Томск) 4 — центральный район региона (Тюменская обл, Тюменский р-н) 0 — ничего из перечисленного (Московская обл, г Балашиха)
data.okato	Код ОКАТО
data.oktmo	Код ОКТМО
data.tax_office	Код ИФНС для физических лиц
data.tax_office_legal	Код ИФНС для организаций
data.source	Для организаций — адрес как в ЕГРЮЛ. Для банков — адрес как в справочнике БИК. В остальных случаях — пустое.
data.history_values[ ]	Список исторических названий объекта нижнего уровня. Если подсказка до улицы — это прошлые названия этой улицы, если до города — города.
Дополнительные поля, заполняются в зависимости от тарифа «Дадаты» *
Заполняются при выборе конкретной подсказки или через метод API findById. До этого они пустые.
Все тарифы «Дадаты»
data.geo_lat	Координаты: широта
data.geo_lon	Координаты: долгота
data.qc_geo	Код точности координат: 0 — точные координаты 1 — ближайший дом 2 — улица 3 — населенный пункт 4 — город 5 — координаты не определены, отсутствуют в справочнике 6 — не загружен справочник с геокоординатами
data.fias_code	Иерархический код адреса в ФИАС (СС+РРР+ГГГ+ППП+СССС+УУУУ+ДДДД)
data.fias_actuality_state	Признак актуальности адреса в ФИАС: 0 — актуальный 1–50 — переименован 51 — переподчинен 99 — удален
data.city_area	Административный округ (только для Москвы)
Тарифы «Расширенный» и «Максимальный»
data.beltway_hit	Внутри кольцевой?
data.beltway_distance	Расстояние от кольцевой в километрах
Тариф «Максимальный»
data.flat_area	Площадь квартиры
data.square_meter_price	Рыночная стоимость м²
data.flat_price	Рыночная стоимость квартиры
data.timezone	Часовой пояс
data.metro[ ] └ name └ line └ distance	Ближайшие станции метро (не более 3 станций в радиусе 5 км): — название станции — название линии — расстояние до станции в километрах
Не заполняются
data.entrance	Подъезд (21.1+)
data.floor	Этаж (21.1+)
data.qc_complete	Код пригодности к рассылке
data.qc_house	Код проверки дома
data.qc	Код проверки
data.unparsed_parts	Нераспознанная часть адреса

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

value

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

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

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

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

Если в запросе к 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.city_with_type (город с типом),
data.city_district_with_type (район города с типом),
data.settlement_with_type (населенный пункт с типом),
data.street_with_type (улица с типом),
data.house_type (тип дома),
data.house (дом),
data.block_type (тип корпуса/строения),
data.block (корпус/строение),
data.flat_type (тип квартиры),
data.flat (квартира).

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

Примеры

Запрос

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

Ответ:

Показать

{
    "suggestions": [
    {
      "value": "г Москва, ул Серпуховская Б.",
      "unrestricted_value": "г Москва, ул Серпуховская Б.",
      "data": {
        "postal_code": "115093",
        "country": "Россия",
        "region_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
        "region_kladr_id": "7700000000000",
        "region_with_type": "г Москва",
        "region_type": "г",
        "region_type_full": "город",
        "region": "Москва",
        "area_fias_id": null,
        "area_kladr_id": null,
        "area_with_type": null,
        "area_type": null,
        "area_type_full": null,
        "area": null,
        "city_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
        "city_kladr_id": "7700000000000",
        "city_with_type": "г Москва",
        "city_type": "г",
        "city_type_full": "город",
        "city": "Москва",
        "city_area": null,
        "city_district_fias_id": null,
        "city_district_kladr_id": null,
        "city_district_with_type": null,
        "city_district_type": null,
        "city_district_type_full": null,
        "city_district": null,
        "settlement_fias_id": null,
        "settlement_kladr_id": null,
        "settlement_with_type": null,
        "settlement_type": null,
        "settlement_type_full": null,
        "settlement": null,
        "street_fias_id": "601875e2-717a-4c30-a3c4-1fb49e67d93f",
        "street_kladr_id": "77000000000262500",
        "street_with_type": "ул Серпуховская Б.",
        "street_type": "ул",
        "street_type_full": "улица",
        "street": "Серпуховская Б.",
        "house_fias_id": null,
        "house_kladr_id": null,
        "house_type": null,
        "house_type_full": null,
        "house": null,
        "block_type": null,
        "block_type_full": null,
        "block": null,
        "flat_type": null,
        "flat_type_full": null,
        "flat": null,
        "flat_area": null,
        "square_meter_price": null,
        "flat_price": null,
        "postal_box": null,
        "fias_id": "601875e2-717a-4c30-a3c4-1fb49e67d93f",
        "fias_level": "7",
        "kladr_id": "77000000000262500",
        "capital_marker": "0",
        "okato": null,
        "oktmo": null,
        "tax_office": null,
        "tax_office_legal": null,
        "timezone": null,
        "geo_lat": null,
        "geo_lon": null,
        "beltway_hit": null,
        "beltway_distance": null,
        "qc_geo": null,
        "qc_complete": null,
        "qc_house": null,
        "unparsed_parts": null,
        "qc": null
      }
    },
    {
      "value": "г Москва, Серпуховская пл",
      "unrestricted_value": "г Москва, Серпуховская пл",
      "data": {
        "postal_code": "115184",
        "country": "Россия",
        "region_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
        "region_kladr_id": "7700000000000",
        "region_with_type": "г Москва",
        "region_type": "г",
        "region_type_full": "город",
        "region": "Москва",
        "area_fias_id": null,
        "area_kladr_id": null,
        "area_with_type": null,
        "area_type": null,
        "area_type_full": null,
        "area": null,
        "city_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
        "city_kladr_id": "7700000000000",
        "city_with_type": "г Москва",
        "city_type": "г",
        "city_type_full": "город",
        "city": "Москва",
        "city_area": null,
        "city_district_fias_id": null,
        "city_district_kladr_id": null,
        "city_district_with_type": null,
        "city_district_type": null,
        "city_district_type_full": null,
        "city_district": null,
        "settlement_fias_id": null,
        "settlement_kladr_id": null,
        "settlement_with_type": null,
        "settlement_type": null,
        "settlement_type_full": null,
        "settlement": null,
        "street_fias_id": "6fe35e69-360a-4d75-8061-066a5c9e669c",
        "street_kladr_id": "77000000000702000",
        "street_with_type": "Серпуховская пл",
        "street_type": "пл",
        "street_type_full": "площадь",
        "street": "Серпуховская",
        "house_fias_id": null,
        "house_kladr_id": null,
        "house_type": null,
        "house_type_full": null,
        "house": null,
        "block_type": null,
        "block_type_full": null,
        "block": null,
        "flat_type": null,
        "flat_type_full": null,
        "flat": null,
        "flat_area": null,
        "square_meter_price": null,
        "flat_price": null,
        "postal_box": null,
        "fias_id": "6fe35e69-360a-4d75-8061-066a5c9e669c",
        "fias_level": "7",
        "kladr_id": "77000000000702000",
        "capital_marker": "0",
        "okato": "45286560000",
        "oktmo": "45376000",
        "tax_office": "7705",
        "tax_office_legal": null,
        "timezone": null,
        "geo_lat": null,
        "geo_lon": null,
        "beltway_hit": null,
        "beltway_distance": null,
        "qc_geo": null,
        "qc_complete": null,
        "qc_house": null,
        "unparsed_parts": null,
        "qc": null
      }
    }
  ]
}

Запрос:

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

Ответ:

Показать

<SuggestResponse>
    <suggestions>
        <value>г Москва, ул Серпуховская Б.</value>
        <unrestricted_value>г Москва, ул Серпуховская Б.</unrestricted_value>
        <data>
            <postal_code>115093</postal_code>
            <country>Россия</country>
            <region_fias_id>0c5b2444-70a0-4932-980c-b4dc0d3f02b5</region_fias_id>
            <region_kladr_id>7700000000000</region_kladr_id>
            <region_with_type>г Москва</region_with_type>
            <region_type>г</region_type>
            <region_type_full>город</region_type_full>
            <region>Москва</region>
            <area_fias_id/>
            <area_kladr_id/>
            <area_with_type/>
            <area_type/>
            <area_type_full/>
            <area/>
            <city_fias_id>0c5b2444-70a0-4932-980c-b4dc0d3f02b5</city_fias_id>
            <city_kladr_id>7700000000000</city_kladr_id>
            <city_with_type>г Москва</city_with_type>
            <city_type>г</city_type>
            <city_type_full>город</city_type_full>
            <city>Москва</city>
            <city_area/>
            <city_district_fias_id/>
            <city_district_kladr_id/>
            <city_district_with_type/>
            <city_district_type/>
            <city_district_type_full/>
            <city_district/>
            <settlement_fias_id/>
            <settlement_kladr_id/>
            <settlement_with_type/>
            <settlement_type/>
            <settlement_type_full/>
            <settlement/>
            <street_fias_id>601875e2-717a-4c30-a3c4-1fb49e67d93f</street_fias_id>
            <street_kladr_id>77000000000262500</street_kladr_id>
            <street_with_type>ул Серпуховская Б.</street_with_type>
            <street_type>ул</street_type>
            <street_type_full>улица</street_type_full>
            <street>Серпуховская Б.</street>
            <house_fias_id/>
            <house_kladr_id/>
            <house_type/>
            <house_type_full/>
            <house/>
            <block_type/>
            <block_type_full/>
            <block/>
            <flat_type/>
            <flat_type_full/>
            <flat/>
            <flat_area/>
            <square_meter_price/>
            <flat_price/>
            <postal_box/>
            <fias_id>601875e2-717a-4c30-a3c4-1fb49e67d93f</fias_id>
            <fias_level>7</fias_level>
            <kladr_id>77000000000262500</kladr_id>
            <capital_marker>0</capital_marker>
            <okato/>
            <oktmo/>
            <tax_office/>
            <tax_office_legal/>
            <timezone/>
            <geo_lat/>
            <geo_lon/>
            <beltway_hit/>
            <beltway_distance/>
            <qc_geo/>
            <qc_complete/>
            <qc_house/>
            <unparsed_parts/>
            <qc/>
        </data>
    </suggestions>
    <suggestions>
        <value>г Москва, Серпуховская пл</value>
        <unrestricted_value>г Москва, Серпуховская пл</unrestricted_value>
        <data>
            <postal_code>115184</postal_code>
            <country>Россия</country>
            <region_fias_id>0c5b2444-70a0-4932-980c-b4dc0d3f02b5</region_fias_id>
            <region_kladr_id>7700000000000</region_kladr_id>
            <region_with_type>г Москва</region_with_type>
            <region_type>г</region_type>
            <region_type_full>город</region_type_full>
            <region>Москва</region>
            <area_fias_id/>
            <area_kladr_id/>
            <area_with_type/>
            <area_type/>
            <area_type_full/>
            <area/>
            <city_fias_id>0c5b2444-70a0-4932-980c-b4dc0d3f02b5</city_fias_id>
            <city_kladr_id>7700000000000</city_kladr_id>
            <city_with_type>г Москва</city_with_type>
            <city_type>г</city_type>
            <city_type_full>город</city_type_full>
            <city>Москва</city>
            <city_area/>
            <city_district_fias_id/>
            <city_district_kladr_id/>
            <city_district_with_type/>
            <city_district_type/>
            <city_district_type_full/>
            <city_district/>
            <settlement_fias_id/>
            <settlement_kladr_id/>
            <settlement_with_type/>
            <settlement_type/>
            <settlement_type_full/>
            <settlement/>
            <street_fias_id>6fe35e69-360a-4d75-8061-066a5c9e669c</street_fias_id>
            <street_kladr_id>77000000000702000</street_kladr_id>
            <street_with_type>Серпуховская пл</street_with_type>
            <street_type>пл</street_type>
            <street_type_full>площадь</street_type_full>
            <street>Серпуховская</street>
            <house_fias_id/>
            <house_kladr_id/>
            <house_type/>
            <house_type_full/>
            <house/>
            <block_type/>
            <block_type_full/>
            <block/>
            <flat_type/>
            <flat_type_full/>
            <flat/>
            <flat_area/>
            <square_meter_price/>
            <flat_price/>
            <postal_box/>
            <fias_id>6fe35e69-360a-4d75-8061-066a5c9e669c</fias_id>
            <fias_level>7</fias_level>
            <kladr_id>77000000000702000</kladr_id>
            <capital_marker>0</capital_marker>
            <okato>45286560000</okato>
            <oktmo>45376000</oktmo>
            <tax_office>7705</tax_office>
            <tax_office_legal/>
            <timezone/>
            <geo_lat/>
            <geo_lon/>
            <beltway_hit/>
            <beltway_distance/>
            <qc_geo/>
            <qc_complete/>
            <qc_house/>
            <unparsed_parts/>
            <qc/>
        </data>
    </suggestions>
</SuggestResponse>

Page tree

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

Запрос

Заголовки

Параметры

Ответ

value

unrestricted_value

Примеры