↑ Все API

API: подсказки по адресам

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

Что умеет и не умеет

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

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

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

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

✔️ Находит адреса по кадастровому номеру («77:02:0004008:4143») и ФИАС-коду («f26b876b-6857-4951-b060-ec6559f04a9a»).

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

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

✔️ Знает земельные участки («казань красная участок 109в» → «420025, Респ Татарстан, г Казань, Советский р-н, ул Большая Красная (Малые Клыки), уч 109в»)

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

Не умеет:

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

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

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

Для автоматической обработки и транслитерации используйте API Стандартизации

Как вызвать

Чтобы вызвать метод, и подтвердите почту.

Пример запроса:

            
                POST http://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address
            
            
{ "query": "москва хабар" }

Укажите при вызове:

  • Content-Type: application/json.
  • Accept: application/json.
  • ${API_KEY} — API-ключ.

Тело запроса передавайте в кодировке UTF-8.

Параметры запроса

НазваниеТипОбяз.?Описание
querystringТекст запроса
countnumber Количество результатов
по умолчанию — 10, максимум — 20
languagestring На каком языке вернуть результат
по умолчанию — русский
divisionstring Административное либо муниципальное деление
по умолчанию — административное
locationsarray [object] Ограничение по родителю
locations_geoarray [object] Ограничение по радиусу окружности
locations_boostarray [object] Приоритет города при ранжировании
from_bound
to_bound
object Гранулярные подсказки

Что в ответе

Объект с массивом подсказок в поле suggestions:

Пример ответа
{
    "suggestions": [
        {
            "value": "г Москва, ул Хабаровская",
            "unrestricted_value": "г Москва, ул Хабаровская",
            "data": {
                "postal_code": null,
                "country": "Россия",
                "country_iso_code": "RU",
                "federal_district": null,
                "region_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
                "region_kladr_id": "7700000000000",
                "region_iso_code": "RU-MOW",
                "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": "32fcb102-2a50-44c9-a00e-806420f448ea",
                "street_kladr_id": "77000000000713400",
                "street_with_type": "ул Хабаровская",
                "street_type": "ул",
                "street_type_full": "улица",
                "street": "Хабаровская",
                "stead_fias_id": null,
                "stead_cadnum": null,
                "stead_type": null,
                "stead_type_full": null,
                "stead": null,
                "house_fias_id": null,
                "house_kladr_id": null,
                "house_cadnum": null,
                "house_flat_count": null,
                "house_type": null,
                "house_type_full": null,
                "house": null,
                "block_type": null,
                "block_type_full": null,
                "block": null,
                "entrance": null,
                "floor": null,
                "flat_fias_id": null,
                "flat_cadnum": 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": "32fcb102-2a50-44c9-a00e-806420f448ea",
                "fias_code": null,
                "fias_level": "7",
                "fias_actuality_state": "0",
                "kladr_id": "77000000000713400",
                "geoname_id": "524901",
                "capital_marker": "0",
                "okato": "45263564000",
                "oktmo": "45305000",
                "tax_office": "7718",
                "tax_office_legal": "7718",
                "timezone": null,
                "geo_lat": "55.821168",
                "geo_lon": "37.82608",
                "beltway_hit": null,
                "beltway_distance": null,
                "metro": null,
                "divisions": null,
                "qc_geo": "2",
                "qc_complete": null,
                "qc_house": null,
                "history_values": [
                    "ул Черненко"
                ],
                "unparsed_parts": null,
                "source": null,
                "qc": null
            }
        },
        ...
    ]
}
Название Описание
Базовые поля, заполняются для всех тарифов
valueАдрес одной строкой (как показывается в списке подсказок)
unrestricted_valueАдрес одной строкой (полный, с индексом)
data.postal_codeИндекс
data.countryСтрана
data.country_iso_codeISO-код страны (двухсимвольный)
data.federal_districtФедеральный округ
data.region_fias_idФИАС-код региона
data.region_kladr_idКЛАДР-код региона
data.region_iso_codeISO-код региона
data.region_with_typeРегион с типом
data.region_typeТип региона (сокращенный)
data.region_type_fullТип региона
data.regionРегион
data.area_fias_idФИАС-код района в регионе
data.area_kladr_idКЛАДР-код района в регионе
data.area_with_typeРайон в регионе с типом
data.area_typeТип района в регионе (сокращенный)
data.area_type_fullТип района в регионе
data.areaРайон в регионе
data.sub_area_fias_idФИАС-код мун. поселения
data.sub_area_kladr_idКЛАДР-код мун. поселения
data.sub_area_with_typeМун. поселение с типом
data.sub_area_typeТип мун. поселения (сокращенный)
data.sub_area_type_fullТип мун. поселения
data.sub_areaМун. поселение
data.city_fias_idФИАС-код города
data.city_kladr_idКЛАДР-код города
data.city_with_typeГород с типом
data.city_typeТип города (сокращенный)
data.city_type_fullТип города
data.cityГород
data.city_district_fias_idФИАС-код адм. района города
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ФИАС-код нас. пункта
data.settlement_kladr_idКЛАДР-код нас. пункта
data.settlement_with_typeНаселенный пункт с типом
data.settlement_typeТип населенного пункта (сокращенный)
data.settlement_type_fullТип населенного пункта
data.settlementНаселенный пункт
data.street_fias_idФИАС-код улицы
data.street_kladr_idКЛАДР-код улицы
data.street_with_typeУлица с типом
data.street_typeТип улицы (сокращенный)
data.street_type_fullТип улицы
data.streetУлица
data.stead_fias_idФИАС-код земельного участка
data.stead_kladr_idКЛАДР-код земельного участка
data.stead_type = «уч»
data.stead_type_full = «участок»
data.steadномер земельного участка
data.house_fias_idФИАС-код дома
data.house_kladr_idКЛАДР-код дома
data.house_typeТип дома (сокращенный)
data.house_type_fullТип дома
data.houseДом
data.block_typeТип корпуса/строения (сокращенный)
data.block_type_fullТип корпуса/строения
data.blockКорпус/строение
data.entrance не заполняется
data.floor не заполняется
data.flat_fias_idФИАС-код квартиры
data.flat_typeТип квартиры (сокращенный)
data.flat_type_fullТип квартиры
data.flatКвартира
data.room_fias_idФИАС-код комнаты
data.room_typeТип комнаты (сокращенный)
data.room_type_fullТип комнаты
data.roomКомната
data.postal_boxАбонентский ящик
data.fias_id

ФИАС-код (он же код ГАР) адреса для России.
Идентификатор OpenStreetMap для Беларуси, Казахстана и Узбекистана.
Для остальных стран — идентификатор объекта в базе GeoNames.

data.fias_code Не заполняется, используйте fias_id
data.fias_level Уровень детализации, до которого адрес найден в ФИАС (ГАР):
  0 — страна
  1 — регион
  3 — район
  4 — город
  5 — район города
  6 — населенный пункт
  7 — улица
  8 — дом
  9 — квартира или комната
 65 — планировочная структура
 75 — земельный участок
 -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.history_values[ ] Список исторических названий объекта нижнего уровня.
Если подсказка до улицы — это прошлые названия этой улицы, если до города — города.
Дополнительные поля, заполняются в зависимости от тарифа
Заполняются при выборе конкретной подсказки. До этого они пустые.
Все тарифы
data.geo_latКоординаты: широта
data.geo_lonКоординаты: долгота
data.qc_geo Код точности координат:
  0 — точные координаты
  1 — ближайший дом
  2 — улица
  3 — населенный пункт
  4 — город
  5 — координаты не определены
data.fias_actuality_state Признак актуальности адреса в ФИАС
  0    — актуальный
  1–50 — переименован
  51   — переподчинен
  99   — удален
data.city_areaАдминистративный округ (только для Москвы)
«Расширенный» и «Максимальный»
data.beltway_hitВнутри кольцевой?
data.beltway_distanceРасстояние от кольцевой в километрах
Только «Максимальный»
data.stead_cadnumКадастровый номер земельного участка
data.house_cadnumКадастровый номер дома
data.flat_cadnumКадастровый номер квартиры
data.room_cadnumКадастровый номер комнаты
data.house_flat_countКоличество квартир в доме
data.flat_areaПлощадь квартиры
data.square_meter_priceРыночная стоимость м²
data.flat_priceРыночная стоимость квартиры
data.timezoneЧасовой пояс
data.metro[ ] Список ближайших станций метро (до трёх штук)
└ name— название станции
└ line— название линии
└ distance— расстояние до станции в километрах
Зарезервированы для автоматической обработки адресов через API стандартизации
data.qc_complete не заполняется
data.qc_house не заполняется
data.qc не заполняется
data.source не заполняется
data.unparsed_parts не заполняется

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

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

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

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

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

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

Координаты, площадь и стоимость

Координаты есть у 97% домов в Москве, 91% в Санкт-Петербурге, 69% в других городах-миллиониках и 47% по остальной России.

Площадь и стоимость есть у 70% квартир в России.

Источники данных

Федеральная информационная адресная система (ФИАС) Налоговой службы

Справочник индексов Почты России

Gazetteer Data и Postal Code Data от GeoNames

OpenStreetMap

ISO 3166

Коды ответа на запрос

HTTP-код ответаОписание
200Запрос успешно обработан
400Некорректный запрос (невалидный JSON или XML)
401В запросе отсутствует API-ключ
403 В запросе указан несуществующий API-ключ
Или не подтверждена почта
Или исчерпан дневной лимит по количеству запросов
405Запрос сделан с методом, отличным от POST
413Слишком большая длина запроса или слишком много условий
429Слишком много запросов в секунду или новых соединений в минуту
5xxПроизошла внутренняя ошибка сервиса

Примеры вызова

Заголовки и параметры

На каком языке вернуть результат

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

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

Приоритет города при ранжировании

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


Ограничения

Для иностранных адресов заполнен ограниченный набор полей, вне зависимости от тарифного плана: почтовый индекс, страна, регион, населенный пункт, часовой пояс и геокоординаты. Прочие поля — пустые.

При работе через API «пользователь выбрал конкретный адрес» — это запрос с параметром count = 1. При этом текст запроса должен быть результатом одного из предыдущих запросов (значением поля unrestricted_value).

Количество условий в параметрах locations и locations_boost — не более 10.

Длина запроса (параметр query) — не более 300 символов.

Количество запросов в день — в соответствии с тарифным планом.

Максимальная частота запросов — 30 в секунду с одного IP-адреса.

Максимальная частота создания новых соединений — 60 в минуту с одного IP-адреса.

Частые вопросы

По адресам

Есть ли подсказки по адресам Украины, Беларуси и Казахстана?

Да, есть подсказки по всем городам мира. Чтобы их включить, передайте параметр country = "*":

{
    "query": "гомель",
    "locations": [
        {
            "country": "*"
        }
    ]
}
Поддерживаете ли вы государственный адресный реестр (ГАР)?

Да. Значение в поле fias_id — это код адреса согласно ГАР (object GUID). В ГАР есть еще целочисленный код (object ID), но регулятор его не требует, так что «Дадата» его не возвращает.

Как включить подсказки на английском языке (транслитом)?

Передайте параметр language = "en":

{
    "query": "samara",
    "language": "en"
}
Как часто обновляется справочник адресов?

Один раз в неделю, на выходных.

Почему индекс неправильный — не такой, как у Почты России?

Дадата работает по объединенному справочнику налоговой службы ФИАС (ГАР) и Почты России. В нем исправлены более 7 000 некорректных и отсутствующих индексов.

К сожалению, справочник индексов Почты детализирован только до населенных пунктов. Привязки к улицам и домам нет. Поэтому все-все индексы исправить не удалось.

Если получили от Дадаты неправильный индекс — отправьте адрес через специальную форму. Мы исправляем ошибки ежемесячно.

Почему подсказки не возвращают геокоординаты и район города?

Подсказки возвращают геокоординаты и район после того, как человек выбрал конкретный адрес из списка.

В API это запрос с параметром count = 1. При этом текст запроса должен быть результатом одного из предыдущих запросов (значением поля unrestricted_value). Например:

{ "query": "127642, г Москва, ул Сухонская, д 11", "count": 1 }
Почему подсказки не возвращают площадь квартиры, ближайшее метро и часовой пояс?

Эти поля возвращаются только для тарифа «Максимальный».

Причём после того, как человек выбрал конкретный адрес из списка. В API это запрос с параметром count = 1.

Почему подсказки не возвращают коды качества?

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

Почему на картах дом есть, а в подсказках — нет?

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

Чтобы добавить дом в подсказки, отправьте его через специальную форму. Мы пополняем справочник ежемесячно.

Общие

Подсказки не работают: ошибка 403 Forbidden (Feature SUGGESTIONS disabled for token)

Возможные причины:

  • Не подтверждён адрес эл. почты. Проверьте в личном кабинете. Если почта не подтверждена — посмотрите почтовый ящик и папку «спам», там должно быть письмо от «Дадаты».
  • В запросе указан неправильный API-ключ. Проверьте в личном кабинете
  • Исчерпан лимит запросов на день. Проверьте в личном кабинете
Что будет, если превысить 10 000 бесплатных запросов в день?

Подсказки перестанут подсказывать ツ До начала нового дня, затем снова заработают.

10 000 запросов считаются суммарно по всем видам подсказок: адреса, ФИО, организации, банки, емейлы...

Стоимость

Бесплатно до 10 тысяч запросов в день. Больше — в составе годовой подписки.