API: стандартизация адресов
✔️ Разбивает адрес по отдельным полям (регион, город, улица, дом, квартира).
✔️ Рассчитывает корректный индекс по данным Почты России.
✔️ Определяет координаты.
✔️ Показывает округ и район города, ближайшее метро, площадь и стоимость квартиры.
✔️ Достает коды КЛАДР, ФИАС (ГАР), ОКАТО, ОКТМО и ИФНС.
Только для России.
Как вызвать
Чтобы вызвать метод, зарегистрируйтесь и подтвердите почту.
Пример запроса:
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 за ваш счет.