↑ Все 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 Стандартизации

Как вызвать

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

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

Песочница

{ "query": "москва хабар" }

cURL

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

.NET

// https://github.com/hflabs/dadata-csharp

var token = "${API_KEY}";
var api = new SuggestClientAsync(token);
var result = await api.SuggestAddress("москва хабар");

// https://github.com/ekomobile/dadata
// Использует API-ключ из переменной окружения DADATA_API_KEY

import (
    "context"
    dadata "github.com/ekomobile/dadata/v2"
    "github.com/ekomobile/dadata/v2/api/suggest"
)

func main() {
    api := dadata.NewSuggestApi()
    params := suggest.RequestParams{Query: "москва хабар"}
    result, err := api.Address(context.Background(), &params)
}

JavaScript

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));

PHP

// https://github.com/hflabs/dadata-php

$token = "${API_KEY}";
$dadata = new \Dadata\DadataClient($token, null);
$result = $dadata->suggest("address", "москва хабар");

Python

# https://github.com/hflabs/dadata-py

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

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

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

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

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

Название	Тип	Обяз.?	Описание
query	string	✓	Текст запроса
count	number		Количество результатов по умолчанию — 10, максимум — 20
language	string		На каком языке вернуть результат по умолчанию — русский
division	string		Административное либо муниципальное деление по умолчанию — административное
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": "Хабаровская",
                "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_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_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.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 для Белоруссии. Для остальных стран — не заполняется.
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.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 тысяч запросов в день. Больше — в составе годовой подписки.