↑ Все API

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

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

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

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

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

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

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

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

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

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

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

Не умеет:

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

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

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

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

Как вызвать

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

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

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Token ${API_KEY}" \
-d '{ "query": "москва хабар" }' \
https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address
// https://github.com/hflabs/dadata-csharp

var token = "${API_KEY}";
var api = new SuggestClientAsync(token);
var result = await api.SuggestAddress("москва хабар");
// https://github.com/webdeskltd/dadata

token := "${API_KEY}"
dadata := dadata.NewDaData(token, "")
params := dadata.SuggestRequestParams{Query: "москва хабар"}
result, err := dadata.SuggestAddresses(params)
var url = "https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address";
var token = "${API_KEY}";
var query = "москва хабар";

var options = {
    method: "POST",
    mode: "cors",
    headers: {
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Authorization": "Token " + token
    },
    body: JSON.stringify({query: query})
}

fetch(url, options)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log("error", error));
// https://github.com/hflabs/dadata-php

$token = "${API_KEY}";
$dadata = new \Dadata\DadataClient($token, null);
$result = $dadata->suggest("address", "москва хабар");
# https://github.com/hflabs/dadata-py

from dadata import DadataAsync
token = "${API_KEY}"
dadata = DadataAsync(token)
result = await dadata.suggest("address", "москва хабар")

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

  • Content-Type: application/json или application/xml.
  • Accept — аналогично.
  • ${API_KEY} — API-ключ.

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

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

Название Тип Обяз.? По умолч. Описание
query string Текст запроса
count number 10 Количество результатов (максимум — 20)
language string ru На каком языке вернуть результат (ru / en)
locations array [object] Ограничение по родителю (страна, регион, район, город, улица)
locations_geo array [object] Ограничение по радиусу окружности
locations_boost array [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": "Хабаровская",
                "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": "32fcb102-2a50-44c9-a00e-806420f448ea",
                "fias_code": null,
                "fias_level": "7",
                "fias_actuality_state": null,
                "kladr_id": "77000000000713400",
                "geoname_id": null,
                "capital_marker": "0",
                "okato": "45263564000",
                "oktmo": "45305000",
                "tax_office": "7718",
                "tax_office_legal": "7718",
                "timezone": null,
                "geo_lat": null,
                "geo_lon": null,
                "beltway_hit": null,
                "beltway_distance": null,
                "metro": null,
                "qc_geo": null,
                "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_code ISO-код страны (двухсимвольный)
data.federal_district Федеральный округ
data.region_fias_id Код ФИАС региона
data.region_kladr_id Код КЛАДР региона
data.region_iso_code ISO-код региона
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.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.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.flat_type Тип квартиры (сокращенный)
data.flat_type_full Тип квартиры
data.flat Квартира
data.postal_box Абонентский ящик
data.fias_id Код ФИАС:
  • HOUSE.HOUSEGUID, если дом найден в ФИАС по точному совпадению;
  • ADDROBJ.AOGUID в противном случае.
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.history_values[ ] Список исторических названий объекта нижнего уровня.
Если подсказка до улицы — это прошлые названия этой улицы, если до города — города.
Дополнительные поля, заполняются в зависимости от тарифа
Заполняются при выборе конкретной подсказки. До этого они пустые.
Все тарифы
data.geo_lat Координаты: широта
data.geo_lon Координаты: долгота
data.qc_geo Код точности координат:
  0 — точные координаты
  1 — ближайший дом
  2 — улица
  3 — населенный пункт
  4 — город
  5 — координаты не определены
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 — расстояние до станции в километрах
Зарезервированы для автоматической обработки адресов через API стандартизации
data.qc_complete
data.qc_house
data.qc
data.source
data.unparsed_parts

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

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

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

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

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 символов.

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

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

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

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

По адресам

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

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

{
    "query": "гомель",
    "locations": [
        {
            "country": "*"
        }
    ]
}
Как включить подсказки на английском языке (транслитом)?

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

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

Обычно — один раз в неделю, на выходных. Но с июня 2020 года обновление остановлено.

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

Дадата работает по объединенному справочнику налоговой службы (ФИАС) и Почты России. В нем исправлены более 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 запросов считаются суммарно по всем видам подсказок: адреса, ФИО, организации, банки, емейлы...

Как защитить API-ключ от злоумышленников?

Если вы используете jQuery-плагин Подсказок, то API-ключ можно посмотреть в исходном коде страниц вашего сайта. Чтобы злоумышленник не мог воспользоваться вашим ключом, можно привязать его к конкретному домену в личном кабинете.

Если вы подключили Подсказки не через jQuery-плагин, а из программы через API, злоумышленник не сможет подсмотреть ключ. В этом случае привязка к домену не требуется.

Если вы используете и jQuery-плагин, и работу через API — привязку к домену придётся отключить (иначе она «не пропустит» API-запросы). Мы рекомендуем использовать что-то одно — или плагин, или API — но не оба способа одновременно.

Стоимость

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

ajax-spinner

Зарегистрируйтесь, чтобы подключить подсказки

до 10 тыс. запросов в день — бесплатно

чтобы обращаться к вам в письмах

Регистрируясь, вы принимаете публичную оферту

Уже зарегистрированы? Войти