Документация Подсказок

Page tree
Skip to end of metadata
Go to start of metadata

Возможности

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

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

Что умеет:

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

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

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

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

✔️ Возвращает адреса в административном и муниципальном делениях. Раскладывает выбранный адрес на гранулярные части (от региона до квартиры).

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

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

✔️ Учитывает, где вы находитесь (в связке с методом город по 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

API-пробник (21.8+)

Заголовки

ЗаголовокОписание

Content-Type

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

Accept

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

Authorization

API-ключ в формате: Token ВАШ_КЛЮЧ

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

Параметры

ПараметрТипОбязательный?Описание
querystring(300)даЗапрос, для которого нужно получить подсказки

count

intнет
Количество возвращаемых подсказок (по умолчанию — 10, максимум — 20).

language

string(2)нетЯзык отображения адреса в результатах поиска 20.3+
по умолчанию — русский
divisionstring(20)нет

Административное либо муниципальное деление 22.4+
по умолчанию — административное

locations

object[100]нетОграничение области поиска

locations_geo

object[1]нетГеографическое ограничение 20.4+
locations_boostobject[1]нетПриоритет города при ранжировании

from_bound
to_bound

objectнетГранулярные подсказки по адресу

Ответ

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

ПолеТип данныхОписание
valuestring(1000)Короткий адрес одной строкой
unrestricted_valuestring(1000)Длинный адрес одной строкой
data.postal_codestring(10)Индекс
data.countrystring(150)Страна
data.country_iso_codestring(10)Двухсимвольный код страны ISO 3166 (19.7+)
data.federal_districtstring(50)Федеральный округ (19.5+)
data.region_fias_idstring(50)ФИАС-код региона (либо код OSM, начиная с версии 20.7)
data.region_kladr_idstring(20)КЛАДР-код региона
data.region_iso_codestring(10)Код региона ISO 3166 (19.7+)
data.region_with_typestring(150)Регион с типом
data.region_typestring(10)Тип региона (сокращенный)
data.region_type_fullstring(50)Тип региона
data.regionstring(150)Регион
data.area_fias_idstring(50)ФИАС-код района в регионе
для Белоруссии — код OSM
data.area_kladr_idstring(20)КЛАДР-код района в регионе
data.area_with_typestring(150)Район в регионе с типом
data.area_typestring(10)Тип района в регионе (сокращенный)
data.area_type_fullstring(50)Тип района в регионе
data.areastring(150)Район в регионе
data.sub_area_fias_idstring(50)ФИАС-код муниципального поселения (22.3+)
data.sub_area_kladr_idstring(20)КЛАДР-код муниципального поселения (22.3+)
data.sub_area_with_typestring(150)Муниципальное поселение с типом (22.3+)
data.sub_area_typestring(10)Тип муниципального поселения (сокращенный) (22.3+)
data.sub_area_type_fullstring(50)Тип муниципального поселения (22.3+)
data.sub_areastring(150)Муниципальное поселение (22.3+)
data.city_fias_idstring(50)ФИАС-код города
для Белоруссии — код OSM
data.city_kladr_idstring(20)КЛАДР-код города
data.city_with_typestring(150)Город с типом
data.city_typestring(10)Тип города (сокращенный)
data.city_type_fullstring(50)Тип города
data.citystring(150)Город
data.city_district_fias_idstring(50)ФИАС-код адм. района города
для Белоруссии — код OSM
data.city_district_kladr_idstring(20)КЛАДР-код адм. района города
data.city_district_with_typestring(150)Адм. район города с типом
data.city_district_typestring(10)Тип адм. района города (сокращенный)
data.city_district_type_fullstring(50)Тип адм. района города
data.city_districtstring(150)Адм. район города
data.settlement_fias_idstring(50)ФИАС-код нас. пункта
для Белоруссии — код OSM
data.settlement_kladr_idstring(20)КЛАДР-код нас. пункта
data.settlement_with_typestring(150)Населенный пункт с типом
data.settlement_typestring(10)Тип населенного пункта (сокращенный)
data.settlement_type_fullstring(50)Тип населенного пункта
data.settlementstring(150)Населенный пункт
data.street_fias_idstring(50)ФИАС-код улицы
для Белоруссии — код OSM
data.street_kladr_idstring(20)КЛАДР-код улицы
data.street_with_typestring(150)Улица с типом
data.street_typestring(10)Тип улицы (сокращенный)
data.street_type_fullstring(50)Тип улицы
data.streetstring(150)Улица
data.stead_fias_idstring(50)ФИАС-код участка (21.12+)
data.stead_typestring(10)Тип участка (сокращенный) (21.12+)
data.stead_type_fullstring(50)Тип участка (21.12+)
data.steadstring(50)Участок (21.12+)
data.house_fias_idstring(50)ФИАС-код дома
для Белоруссии — код OSM
data.house_kladr_idstring(20)КЛАДР-код дома
data.house_typestring(10)Тип дома (сокращенный)
data.house_type_fullstring(50)Тип дома
data.housestring(50)Дом
data.block_typestring(10)Тип корпуса/строения (сокращенный)
data.block_type_fullstring(50)Тип корпуса/строения
data.blockstring(50)Корпус/строение
data.flat_fias_idstring(50)ФИАС-код квартиры (20.10+)
data.flat_typestring(10)Тип квартиры (сокращенный)
data.flat_type_fullstring(50)Тип квартиры
data.flatstring(50)Квартира
data.room_fias_idstring(50)ФИАС-код комнаты (22.8+)
data.room_typestring(10)Тип комнаты (сокращенный) (22.8+)
data.room_type_fullstring(50)Тип комнаты (22.8+)
data.roomstring(50)Комната (22.8+)
data.postal_boxstring(50)Абонентский ящик
data.fias_idstring(50)

ФИАС-код адреса
для Белоруссии — код OSM

data.fias_levelstring(10)Уровень детализации, до которого адрес найден в ФИАС:
  • 0 — страна
  • 1 — регион
  • 3 — район
  • 4 — город
  • 5 — район города
  • 6 — населенный пункт
  • 7 — улица
  • 8 — дом
  • 9 — квартира (21.4+)
  • 65 — планировочная структура
  • 75 — земельный участок (21.12+)
  • -1 — иностранный или пустой.
data.kladr_idstring(20)КЛАДР-код адреса
data.geoname_idstring(20)Идентификатор объекта в международной базе GeoNames. Для российских адресов не заполняется.
data.capital_markerstring(10)Признак центра района или региона:
  • 1 — центр района (Московская обл, Одинцовский р-н, г Одинцово)
  • 2 — центр региона (Новосибирская обл, г Новосибирск)
  • 3 — центр района и региона (Томская обл, г Томск)
  • 4 — центральный район региона (Тюменская обл, Тюменский р-н)
  • 0 — ничего из перечисленного (Московская обл, г Балашиха)
data.okatostring(20)Код ОКАТО
data.oktmostring(20)Код ОКТМО
data.tax_officestring(10)Код ИФНС для физических лиц
data.tax_office_legalstring(10)Код ИФНС для организаций
data.sourcestring(250)

Для организаций — адрес как в ЕГРЮЛ.
Для банков — адрес как в справочнике БИК.
В остальных случаях — пустое.

data.history_values[ ]string[](250)

Список исторических названий объекта нижнего уровня.
Если подсказка до улицы — это прошлые названия этой улицы, если до города — города.

Дополнительные поля, заполняются в зависимости от тарифа «Дадаты» *

Заполняются при выборе конкретной подсказки или через метод API findById. До этого они пустые.
Все тарифы «Дадаты»
data.geo_latstring(20)Координаты: широта
data.geo_lonstring(20)Координаты: долгота
data.qc_geostring(10)

Код точности координат:

  • 0 — точные координаты

  • 1 — ближайший дом

  • 2 — улица

  • 3 — населенный пункт

  • 4 — город

  • 5 — координаты не определены, отсутствуют в справочнике

  • 6 — не загружен справочник с геокоординатами
data.fias_actuality_statestring(10)

Признак актуальности адреса в ФИАС:

  • 0 — актуальный
  • 1–50 — переименован
  • 51 — переподчинен
  • 99 — удален
data.city_areastring(150)Административный округ (только для Москвы)
Тарифы «Расширенный» и «Максимальный»
data.beltway_hitstring(10)Внутри кольцевой?
data.beltway_distancestring(10)Расстояние от кольцевой в километрах
Тариф «Максимальный»
data.stead_cadnumstring(100)Кадастровый номер участка (22.4+),
data.house_cadnumstring(100)Кадастровый номер дома (22.4+)
data.flat_cadnumstring(100)Кадастровый номер квартиры (22.4+)
data.flat_areastring(50)Площадь квартиры
data.square_meter_pricestring(50)Рыночная стоимость м²
data.flat_pricestring(50)Рыночная стоимость квартиры
data.room_cadnumstring(100)Кадастровый номер комнаты (22.8+)
data.timezonestring(50)Часовой пояс

data.metro[ ]

└ name

└ line

└ distance


string(50)

string(50)

double

Ближайшие станции метро (не более 3 станций в радиусе 5 км):

— название станции

— название линии

— расстояние до станции в километрах

Не заполняются
data.entrancestring(10)Подъезд (21.1+)
data.floorstring(10)Этаж (21.1+)
data.fias_codestring(50)Классификационный код ФИАС
data.qc_completestring(10)Код пригодности к рассылке
data.qc_housestring(10)Код проверки дома
data.qcstring(10)Код проверки
data.unparsed_partsstring(250)Нераспознанная часть адреса
data.divisions{}Поля адреса в Административно-территориальном и Муниципальном деленииях (22.3+)

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

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.sub_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 на него не влияет.

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

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

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

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

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

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

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


Примеры

Запрос

{
    "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>
  • No labels