API: стандартизация адресов

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

✔️ Рассчитывает корректный индекс по данным Почты России.

✔️ Определяет координаты.

✔️ Показывает округ и район города, ближайшее метро, площадь и стоимость квартиры.

✔️ Достает коды КЛАДР, ФИАС (ГАР), ОКАТО, ОКТМО и ИФНС.

Только для России.

Как вызвать

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

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

            
                POST https://cleaner.dadata.ru/api/v1/clean/address
            
            
                
                    [ "мск сухонска 11/-89" ]

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Token ${API_KEY}" \
  -H "X-Secret: ${SECRET_KEY}" \
  -d '[ "мск сухонска 11/-89" ]' \
  https://cleaner.dadata.ru/api/v1/clean/address

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

var token = "${API_KEY}";
var secret = "${SECRET_KEY}";
var api = new CleanClientAsync(token, secret);
var result = await api.Clean<Address>("мск сухонска 11/-89");

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

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

func main() {
    api := dadata.NewCleanApi()
    query := "мск сухонска 11/-89"
    result, err := api.Address(context.Background(), query)
}

var url = "https://cleaner.dadata.ru/api/v1/clean/address";
var token = "${API_KEY}";
var secret = "${SECRET_KEY}";
var query = "мск сухонска 11/-89";

var options = {
    method: "POST",
    mode: "cors",
    headers: {
        "Content-Type": "application/json",
        "Authorization": "Token " + token,
        "X-Secret": secret
    },
    body: JSON.stringify([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}";
$secret = "${SECRET_KEY}";
$dadata = new \Dadata\DadataClient($token, $secret);
$result = $dadata->clean("address", "мск сухонска 11/-89");

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

from dadata import Dadata
token = "${API_KEY}"
secret = "${SECRET_KEY}"
dadata = Dadata(token, secret)
result = dadata.clean("address", "мск сухонска 11/-89")

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

Content-Type: application/json.
Accept: application/json.
${API_KEY} — API-ключ.
${SECRET_KEY} — секретный ключ.

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

Что в ответе

Стандартизованный объект:

Пример ответа

[
{
    "source": "мск сухонска 11/-89",
    "result": "г Москва, ул Сухонская, д 11, кв 89",
    "postal_code": "127642",
    "country": "Россия",
    "country_iso_code": "RU",
    "federal_district": "Центральный",
    "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": null,
    "city_kladr_id": null,
    "city_with_type": null,
    "city_type": null,
    "city_type_full": null,
    "city": null,
    "city_area": "Северо-восточный",
    "city_district_fias_id": null,
    "city_district_kladr_id": null,
    "city_district_with_type": "р-н Северное Медведково",
    "city_district_type": "р-н",
    "city_district_type_full": "район",
    "city_district": "Северное Медведково",
    "settlement_fias_id": null,
    "settlement_kladr_id": null,
    "settlement_with_type": null,
    "settlement_type": null,
    "settlement_type_full": null,
    "settlement": null,
    "street_fias_id": "95dbf7fb-0dd4-4a04-8100-4f6c847564b5",
    "street_kladr_id": "77000000000283600",
    "street_with_type": "ул Сухонская",
    "street_type": "ул",
    "street_type_full": "улица",
    "street": "Сухонская",
    "stead_fias_id": null,
    "stead_kladr_id": null,
    "stead_cadnum": null,
    "stead_type": null,
    "stead_type_full": null,
    "stead": null,
    "house_fias_id": "5ee84ac0-eb9a-4b42-b814-2f5f7c27c255",
    "house_kladr_id": "7700000000028360004",
    "house_cadnum": "77:02:0004008:1017",
    "house_type": "д",
    "house_type_full": "дом",
    "house": "11",
    "house_flat_count": "105",
    "block_type": null,
    "block_type_full": null,
    "block": null,
    "entrance": null,
    "floor": null,
    "flat_fias_id": "f26b876b-6857-4951-b060-ec6559f04a9a",
    "flat_cadnum": "77:02:0004008:4143",
    "flat_type": "кв",
    "flat_type_full": "квартира",
    "flat": "89",
    "flat_area": "34.6",
    "square_meter_price": "248273",
    "flat_price": "8590246",
    "postal_box": null,
    "room_type": null,
    "room_type_full": null,
    "room": null,
    "fias_id": "f26b876b-6857-4951-b060-ec6559f04a9a",
    "fias_code": "77000000000000028360004",
    "fias_level": "9",
    "fias_actuality_state": "0",
    "kladr_id": "7700000000028360004",
    "geoname_id": "524901",
    "capital_marker": "0",
    "okato": "45280583000",
    "oktmo": "45362000",
    "tax_office": "7715",
    "tax_office_legal": "7715",
    "timezone": "UTC+3",
    "geo_lat": "55.8783089",
    "geo_lon": "37.6537862",
    "beltway_hit": "IN_MKAD",
    "beltway_distance": null,
    "qc_geo": 0,
    "qc_complete": 0,
    "qc_house": 2,
    "qc": 0,
    "unparsed_parts": null,
    "metro": [
        {
            "distance": 1.1,
            "line": "Калужско-Рижская",
            "name": "Бабушкинская"
        },
        {
            "distance": 1.2,
            "line": "Калужско-Рижская",
            "name": "Медведково"
        },
        {
            "distance": 2.5,
            "line": "Калужско-Рижская",
            "name": "Свиблово"
        }
    ],
    "divisions": {
        "administrative": {
            "area": null,
            "city": null,
            "city_district": {
                "fias_id": null,
                "kladr_id": null,
                "type": "р-н",
                "type_full": "район",
                "name": "Северное Медведково",
                "name_with_type": "р-н Северное Медведково"
            },
            "settlement": null,
            "planning_structure": null
        }
    }
}
]

Название	Тип	Описание
source	string(250)	Исходный адрес одной строкой
result	string(500)	Стандартизованный адрес одной строкой
postal_code	string(10)	Индекс
country	string(150)	Страна
country_iso_code	string(10)	ISO-код страны
federal_district	string(20)	Федеральный округ
region_fias_id	string(50)	ФИАС-код региона
region_kladr_id	string(20)	КЛАДР-код региона
region_iso_code	string(10)	ISO-код региона
region_with_type	string(150)	Регион с типом
region_type	string(10)	Тип региона (сокращенный)
region_type_full	string(50)	Тип региона
region	string(150)	Регион
area_fias_id	string(50)	ФИАС-код района
area_kladr_id	string(20)	КЛАДР-код района
area_with_type	string(150)	Район в регионе с типом
area_type	string(10)	Тип района в регионе (сокращенный)
area_type_full	string(50)	Тип района в регионе
area	string(150)	Район в регионе
city_fias_id	string(50)	ФИАС-код города
city_kladr_id	string(20)	КЛАДР-код города
city_with_type	string(150)	Город с типом
city_type	string(10)	Тип города (сокращенный)
city_type_full	string(50)	Тип города
city	string(150)	Город
city_area	string(150)	Административный округ (только для Москвы)
city_district_fias_id	string(50)	ФИАС-код района города (заполняется, только если район есть в ФИАС)
city_district_kladr_id	string(20)	КЛАДР-код района города (не заполняется)
city_district_with_type	string(150)	Район города с типом
city_district_type	string(10)	Тип района города (сокращенный)
city_district_type_full	string(50)	Тип района города
city_district	string(150)	Район города
settlement_fias_id	string(50)	ФИАС-код населенного пункта
settlement_kladr_id	string(20)	КЛАДР-код населенного пункта
settlement_with_type	string(150)	Населенный пункт с типом
settlement_type	string(10)	Тип населенного пункта (сокращенный)
settlement_type_full	string(50)	Тип населенного пункта
settlement	string(150)	Населенный пункт
street_fias_id	string(50)	ФИАС-код улицы
street_kladr_id	string(20)	КЛАДР-код улицы
street_with_type	string(150)	Улица с типом
street_type	string(10)	Тип улицы (сокращенный)
street_type_full	string(50)	Тип улицы
street	string(150)	Улица
stead_fias_id	string(50)	ФИАС-код земельного участка
stead_kladr_id	string(20)	КЛАДР-код земельного участка
stead_cadnum	string(50)	Кадастровый номер земельного участка
stead_type	string(10)	= «уч»
stead_type_full	string(50)	= «участок»
stead	string(50)	Номер земельного участка
house_fias_id	string(50)	ФИАС-код дома
house_kladr_id	string(20)	КЛАДР-код дома
house_cadnum	string(50)	Кадастровый номер дома
house_type	string(10)	Тип дома (сокращенный)
house_type_full	string(50)	Тип дома
house	string(50)	Дом
house_flat_count	string(10)	Количество квартир в доме
block_type	string(10)	Тип корпуса/строения (сокращенный)
block_type_full	string(50)	Тип корпуса/строения
block	string(50)	Корпус/строение
entrance	string(10)	Подъезд
floor	string(10)	Этаж
flat_fias_id	string(50)	ФИАС-код квартиры
flat_cadnum	string(50)	Кадастровый номер квартиры
flat_type	string(10)	Тип квартиры (сокращенный)
flat_type_full	string(50)	Тип квартиры
flat	string(50)	Квартира
flat_area	string(50)	Площадь квартиры
square_meter_price	string(50)	Рыночная стоимость м²
flat_price	string(50)	Рыночная стоимость квартиры
postal_box	string(50)	Абонентский ящик
room_type	string(10)	Тип комнаты (сокращенный)
room_type_full	string(50)	Тип комнаты
room	string(50)	Комната
fias_id	string(50)	ФИАС-код адреса (идентификатор ФИАС) ROOM.ROOMGUID — если квартира найдена в ФИАС HOUSE.HOUSEGUID — если дом найден в ФИАС ADDROBJ.AOGUID — в противном случае
fias_code		Не заполняется, используйте fias_id
fias_level	string(10)	Уровень детализации, до которого адрес найден в ФИАС 0 — страна 1 — регион 3 — район 4 — город 5 — район города 6 — населенный пункт 7 — улица 8 — дом 9 — квартира 65 — планировочная структура 90 — доп. территория 91 — улица в доп. территории -1 — иностранный или пустой
fias_actuality_state	string(10)	Признак актуальности адреса в ФИАС 0 — актуальный 1-50 — переименован 51 — переподчинен 99 — удален
kladr_id	string(20)	КЛАДР-код адреса
geoname_id	string(20)	Идентификатор объекта в международной базе GeoNames
capital_marker	string(10)	Признак центра района или региона 1 — центр района (Московская обл, Одинцовский р-н, г Одинцово) 2 — центр региона (Новосибирская обл, г Новосибирск) 3 — центр района и региона (Томская обл, г Томск) 4 — центральный район региона (Тюменская обл, Тюменский р-н) 0 — ничего из перечисленного (Московская обл, г Балашиха)
okato	string(20)	Код ОКАТО
oktmo	string(20)	Код ОКТМО
tax_office	string(10)	Код ИФНС для физических лиц
tax_office_legal	string(10)	Код ИФНС для организаций
timezone	string(50)	Часовой пояс города для России, часовой пояс страны — для иностранных адресов. Если у страны несколько поясов, вернёт минимальный и максимальный через слеш: UTC+5/UTC+6
geo_lat	string(20)	Координаты: широта
geo_lon	string(20)	Координаты: долгота
beltway_hit	string(10)	Внутри кольцевой? IN_MKAD — внутри МКАД (Москва) OUT_MKAD — за МКАД (Москва и область) IN_KAD — внутри КАД (Санкт-Петербург) OUT_KAD — за КАД (Санкт-Петербург и область) пусто — в остальных случаях
beltway_distance	string(10)	Расстояние от кольцевой в км. Заполнено, только если beltway_hit : OUT_MKAD или OUT_KAD, иначе пустое
qc_geo	number	Код точности координат
qc_complete	number	Код пригодности к рассылке
qc_house	number	Признак наличия дома в ФИАС
qc	number	Код проверки адреса
unparsed_parts	string(250)	Нераспознанная часть адреса. Для адреса «Москва, Митинская улица, 40, вход с торца» вернет «ВХОД, С, ТОРЦА»
metro	array	Список ближайших станций метро (до трёх штук)
divisions	object	Компоненты адреса в административном делении

Ближайшее метро

Поле metro содержит список ближайших станций метро. Каждая станция — объект следующей структуры:

Название	Тип	Описание
name	string(50)	Название станции
line	string(50)	Название линии
distance	number	Расстояние до станции в километрах

Пример:

[
    {
        "distance": 1.1,
        "line": "Калужско-Рижская",
        "name": "Бабушкинская"
    },
    {
        "distance": 1.2,
        "line": "Калужско-Рижская",
        "name": "Медведково"
    },
    {
        "distance": 2.5,
        "line": "Калужско-Рижская",
        "name": "Свиблово"
    }
]

Административное деление

Поле divisions содержит единственное поле administrative. Оно, в свою очередь, содержит компоненты адреса в административном делении:

area — район региона;
city — город;
city_district — район города;
settlement — населенный пункт;
planning_structure — планировочная структура.

Каждый из компонентов содержит следующие поля:

Название	Тип	Описание
fias_id	string(50)	ФИАС-код
kladr_id	string(20)	КЛАДР-код
type	string(10)	Тип (сокращенный)
type_full	string(50)	Тип
name	string(150)	Название
name_with_type	string(150)	Название с типом

Пример:

{
    "administrative": {
        "area": null,
        "city": null,
        "city_district": {
            "fias_id": null,
            "kladr_id": null,
            "type": "р-н",
            "type_full": "район",
            "name": "Печатники",
            "name_with_type": "р-н Печатники"
        },
        "settlement": null,
        "planning_structure": {
            "fias_id": "0198c177-cda4-4a29-94fa-c24118a197ed",
            "kladr_id": "77000000000789500",
            "type": "наб",
            "type_full": "набережная",
            "name": "Курьяновская",
            "name_with_type": "наб Курьяновская"
        }
    }
}

У района города коды kladr_id и fias_id пустые, потому что в справочнике налоговой они отсутствуют.

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

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

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

Коды качества

Код проверки `qc`

Нужно ли вручную проверить распознанный адрес:

Код qc	Описание	Нужно проверить вручную?
0	Адрес распознан уверенно	Нет
2	Адрес пустой или заведомо «мусорный»	Нет
1	Остались «лишние» части. Пример: «109341 Тверская область Москва Верхние Поля» — здесь лишняя «Тверская область». Либо в исходном адресе недостаточно данных для уверенного разбора. Пример: «Сходня Красная 12» — здесь нет региона и города.	Да
3	Есть альтернативные варианты. Пример: «Москва Тверская-Ямская» — в Москве четыре Тверских-Ямских улицы.	Да

Код пригодности к рассылке `qc_complete`

Годится ли адрес для доставки корреспонденции:

Код qc_complete	Подходит для рассылки?	Описание
0	Да	Пригоден для почтовой рассылки
10	Под вопросом	Дома нет в ФИАС
5	Под вопросом	Нет квартиры. Подходит для юридических лиц или частных владений
8	Под вопросом	До почтового отделения — абонентский ящик или адрес до востребования. Подходит для писем, но не для курьерской доставки.
9	Под вопросом	Сначала проверьте, правильно ли Дадата разобрала исходный адрес
1	Нет	Нет региона
2	Нет	Нет города
3	Нет	Нет улицы
4	Нет	Нет дома
6	Нет	Адрес неполный
7	Нет	Иностранный адрес

Признак наличия дома в ФИАС `qc_house` и код точности координат `qc_geo`

Уточняют вероятность успешной доставки письма:

Код qc_house	Код qc_geo	Вероятность доставки	Описание
2	любой	Высокая	Дом найден в ФИАС
10	0	Высокая	Дом не найден в ФИАС, но есть на картах
10	1	Средняя	Дом не найден в ФИАС, но есть похожий на картах
10	≥ 2	Низкая	Дом не найден в ФИАС и на картах

Код точности координат `qc_geo`

Точность координат адреса для курьерской доставки:

Код qc_geo	Описание
0	Точные координаты
1	Ближайший дом
2	Улица
3	Населенный пункт
4	Город
5	Координаты не определены

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

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

Примеры и интеграции

Ограничения

В запросе разрешено передавать только один адрес.

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

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

Дадата не поддерживает вызов этого метода из браузерного JavaScript. Иначе злоумышленник мог бы похитить секретный ключ и использовать API за ваш счет.

Стоимость

20 копеек за запись