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",
    "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": "242314",
    "flat_price": "8384065",
    "postal_box": null,
    "fias_id": "f26b876b-6857-4951-b060-ec6559f04a9a",
    "fias_code": "77000000000000028360004",
    "fias_level": "9",
    "fias_actuality_state": "0",
    "kladr_id": "7700000000028360004",
    "capital_marker": "0",
    "okato": "45280583000",
    "oktmo": "45362000",
    "tax_office": "7715",
    "tax_office_legal": "7715",
    "timezone": "UTC+3",
    "geo_lat": "55.8782557",
    "geo_lon": "37.65372",
    "beltway_hit": "IN_MKAD",
    "beltway_distance": null,
    "qc_geo": 0,
    "qc_complete": 0,
    "qc_house": 2,
    "qc": 0,
    "unparsed_parts": null,
    "metro": [
        {
            "name": "Бабушкинская",
            "line": "Калужско-Рижская",
            "distance": 1.1
        },
        {
            "name": "Медведково",
            "line": "Калужско-Рижская",
            "distance": 1.2
        },
        {
            "name": "Свиблово",
            "line": "Калужско-Рижская",
            "distance": 2.5
        }
    ]
}
]

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

Координаты есть у 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 за ваш счет.

Стоимость

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