Data cleansing, enrichment and suggestions via Dadata API
Thin Python wrapper over Dadata API.
pip install dadata
Requirements:
- Python 3.9+
- httpx
Import Dadata client and set API keys:
from dadata import Dadata
token = "Replace with Dadata API key"
secret = "Replace with Dadata secret key"
Use with Dadata()
if you want a context-managed client:
with Dadata(token, secret) as dadata:
...
Alternatively, use dadata.close()
if you want to close a client explicitly:
dadata = Dadata(token, secret)
...
dadata.close()
Call API methods as specified below.
Import Dadata client and set API keys:
from dadata import DadataAsync
token = "Replace with Dadata API key"
secret = "Replace with Dadata secret key"
Use async with DadataAsync()
if you want a context-managed client:
async with DadataAsync(token, secret) as dadata:
...
Alternatively, use await dadata.close()
if you want to close a client explicitly:
dadata = DadataAsync(token, secret)
...
await dadata.close()
Call API methods as specified below (add async
/ await
keywords where applicable).
>>> dadata.clean(name="address", source="мск сухонская 11 89")
{
'source': 'мск сухонская 11 89',
'result': 'г Москва, ул Сухонская, д 11, кв 89',
'postal_code': '127642',
'country': 'Россия',
'region': 'Москва',
'city_area': 'Северо-восточный',
'city_district': 'Северное Медведково',
'street': 'Сухонская',
'house': '11',
'flat': '89',
'flat_area': '34.6',
'flat_price': '6854710',
'fias_id': '5ee84ac0-eb9a-4b42-b814-2f5f7c27c255',
'timezone': 'UTC+3',
'geo_lat': '55.8782557',
'geo_lon': '37.65372',
'qc_geo': 0,
'qc': 0,
'metro': [ ... ],
...
}
Same API method as "validate and cleanse":
>>> dadata.clean(name="address", source="москва сухонская 11")
{
'source': 'мск сухонская 11 89',
'result': 'г Москва, ул Сухонская, д 11, кв 89',
...
'geo_lat': '55.8782557',
'geo_lon': '37.65372',
'beltway_hit': 'IN_MKAD',
'beltway_distance': None,
'qc_geo': 0,
...
}
>>> dadata.geolocate(name="address", lat=55.878, lon=37.653)
[
{ 'value': 'г Москва, ул Сухонская, д 11', ... },
{ 'value': 'г Москва, ул Сухонская, д 11А', ... },
{ 'value': 'г Москва, ул Сухонская, д 13', ... },
...
]
>>> dadata.iplocate("46.226.227.20")
{
'value': 'г Краснодар',
'unrestricted_value': '350000, Краснодарский край, г Краснодар',
'data': { ... }
}
>>> dadata.suggest(name="address", query="самара метал")
[
{ 'value': 'г Самара, пр-кт Металлургов', ... },
{ 'value': 'г Самара, ул Металлистов', ... },
{ 'value': 'г Самара, поселок Зубчаниновка, ул Металлургическая', ... },
...
]
Show suggestions in English:
>>> dadata.suggest(name="address", query="samara metal", language="en")
[
{ 'value': 'Russia, gorod Samara, prospekt Metallurgov', ... },
{ 'value': 'Russia, gorod Samara, ulitsa Metallistov', ... },
{ 'value': 'Russia, gorod Samara, poselok Zubchaninovka, ulitsa Metallurgicheskaya', ... },
...
]
Constrain by city (Yuzhno-Sakhalinsk):
>>> locations = [{ "kladr_id": "6500000100000" }]
>>> dadata.suggest(name="address", query="Ватутина", locations=locations)
[
{'value': 'г Южно-Сахалинск, ул Ватутина' ... }
]
Constrain by specific geo point and radius (in Vologda city):
>>> geo = [{ "lat": 59.244634, "lon": 39.913355, "radius_meters": 200 }]
>>> dadata.suggest(name="address", query="сухонская", locations_geo=geo)
[
{'value': 'г Вологда, ул Сухонская' ... }
]
Boost city to top (Toliatti):
>>> boost = [{ "kladr_id": "6300000700000" }]
>>> dadata.suggest(name="address", query="авто", locations_boost=boost)
[
{'value': 'Самарская обл, г Тольятти, Автозаводское шоссе' ... },
{'value': 'Самарская обл, г Тольятти, ул Автомобилистов' ... },
{'value': 'Самарская обл, г Тольятти, ул Автостроителей' ... },
...
]
>>> dadata.find_by_id(name="address", query="9120b43f-2fae-4838-a144-85e43c2bfb29")
[
{ 'value': 'г Москва, ул Снежная', ... }
]
Find by KLADR ID:
>>> dadata.find_by_id(name="address", query="77000000000268400")
Suggest postal office by address or code:
>>> dadata.suggest(name="postal_unit", query="дежнева 2а")
[
{
'value': '127642',
'unrestricted_value': 'г Москва, проезд Дежнёва, д 2А',
'data': { ... }
}
]
Find postal office by code:
>>> dadata.find_by_id(name="postal_unit", query="127642")
[
{
'value': '127642',
'unrestricted_value': 'г Москва, проезд Дежнёва, д 2А',
'data': { ... }
}
]
Find nearest postal office:
>>> dadata.geolocate(name="postal_unit", lat=55.878, lon=37.653, radius_meters=1000)
[
{
'value': '127642',
'unrestricted_value': 'г Москва, проезд Дежнёва, д 2А',
'data': { ... }
}
]
>>> dadata.find_by_id(name="delivery", query="3100400100000")
[
{
'value': '3100400100000',
'unrestricted_value': 'fe7eea4a-875a-4235-aa61-81c2a37a0440',
'data': {
...
'boxberry_id': '01929',
'cdek_id': '344',
'dpd_id': '196006461'
}
}
]
>>> dadata.find_by_id(name="fias", query="9120b43f-2fae-4838-a144-85e43c2bfb29")
[
{ 'value': 'г Москва, ул Снежная', ... }
]
>>> dadata.suggest(name="country", query="та")
[
{ 'value': 'Таджикистан', ... },
{ 'value': 'Таиланд', ... },
{ 'value': 'Тайвань', ... },
...
]
>>> dadata.find_by_id(name="party", query="7707083893")
[
{
'value': 'ПАО СБЕРБАНК',
'unrestricted_value': 'ПАО СБЕРБАНК',
'data': {
'inn': '7707083893',
'kpp': '773601001',
...
}
},
...
]
Find by INN and KPP:
>>> dadata.find_by_id(name="party", query="7707083893", kpp="540602001")
[
{
'value': 'СИБИРСКИЙ БАНК ПАО СБЕРБАНК',
'unrestricted_value': 'СИБИРСКИЙ БАНК ПАО СБЕРБАНК',
'data': {
'inn': '7707083893',
'kpp': '540602001',
...
}
}
]
>>> dadata.suggest(name="party", query="сбер")
[
{ 'value': 'ПАО СБЕРБАНК', ... },
{ 'value': 'АО "СБЕРБРОКЕР"', ... },
{ 'value': 'АО "СБЕРИНВЕСТКАПИТАЛ"', ... },
...
]
Constrain by specific regions (Saint Petersburg and Leningradskaya oblast):
>>> locations = [{ "kladr_id": "7800000000000" }, { "kladr_id": "4700000000000"}]
>>> dadata.suggest(name="party", query="сбер", locations=locations)
Constrain by active companies:
>>> dadata.suggest(name="party", query="сбер", status=["ACTIVE"])
Constrain by individual entrepreneurs:
>>> dadata.suggest(name="party", query="сбер", type="INDIVIDUAL")
Constrain by head companies, no branches:
>>> dadata.suggest(name="party", query="сбер", branch_type=["MAIN"])
>>> dadata.find_affiliated("7736207543")
[
{ 'value': 'ООО "ДЗЕН.ПЛАТФОРМА"', ... },
{ 'value': 'ООО "ЕДАДИЛ"', ... },
{ 'value': 'ООО "ЗНАНИЕ"', ... },
...
]
Search only by manager INN:
>>> dadata.find_affiliated("773006366201", scope=["MANAGERS"])
[
{ 'value': 'ООО "ЯНДЕКС"', ... },
{ 'value': 'МФ "ФОИ"', ... },
{ 'value': 'АНО ДПО "ШАД"', ... },
]
>>> dadata.find_by_id(name="bank", query="044525225")
[
{
'value': 'ПАО Сбербанк',
'unrestricted_value': 'ПАО Сбербанк',
'data': {
'bic': '044525225',
'swift': 'SABRRUMM',
'inn': '7707083893',
...
}
}
]
Find by SWIFT code:
>>> dadata.find_by_id(name="bank", query="SABRRUMM")
Find by INN:
>>> dadata.find_by_id(name="bank", query="7728168971")
Find by INN and KPP:
>>> dadata.find_by_id(name="bank", query="7728168971", kpp="667102002")
Find by registration number:
>>> dadata.find_by_id(name="bank", query="1481")
>>> dadata.suggest(name="bank", query="ти")
[
{ 'value': 'АО «Тимер Банк»', ... },
{ 'value': 'АО «Тинькофф Банк»', ... },
{ 'value': '«Азиатско-Тихоокеанский Банк» (ПАО)', ... },
...
]
>>> dadata.clean(name="name", source="Срегей владимерович иванов")
{
'source': 'Срегей владимерович иванов',
'result': 'Иванов Сергей Владимирович',
...
'surname': 'Иванов',
'name': 'Сергей',
'patronymic': 'Владимирович',
'gender': 'М',
'qc': 1
}
>>> dadata.suggest(name="fio", query="викт")
[
{ 'value': 'Виктор', ... },
{ 'value': 'Виктория', ... },
{ 'value': 'Викторова', ... },
...
]
Suggest female first name:
>>> dadata.suggest(name="fio", query="викт", parts=["NAME"], gender="FEMALE")
[
{ 'value': 'Виктория', ... },
{ 'value': 'Викторина', ... }
]
>>> dadata.clean(name="phone", source="9168-233-454")
{
'source': '9168-233-454',
'type': 'Мобильный',
'phone': '+7 916 823-34-54',
'provider': 'ПАО "Мобильные ТелеСистемы"',
'country': 'Россия',
'region': 'Москва и Московская область',
'timezone': 'UTC+3',
'qc': 0,
...
}
>>> dadata.clean(name="passport", source="4509 235857")
{
'source': '4509 235857',
'series': '45 09',
'number': '235857',
'qc': 0
}
>>> dadata.suggest(name="fms_unit", query="772 053")
[
{ 'value': 'ОВД ЗЮЗИНО Г. МОСКВЫ', ... },
{ 'value': 'ОВД РАЙОНА ЗЮЗИНО УВД ЮГО-ЗАО Г. МОСКВЫ', ... },
{ 'value': 'ПАСПОРТНО-ВИЗОВЫМ ОТДЕЛЕНИЕМ ОВД РАЙОНА ЗЮЗИНО Г. МОСКВЫ', ... },
...
]
>>> dadata.clean(name="email", source="serega@yandex/ru")
{
'source': 'serega@yandex/ru',
'email': 'serega@yandex.ru',
'local': 'serega',
'domain': 'yandex.ru',
'type': 'PERSONAL',
'qc': 4
}
>>> dadata.suggest(name="email", query="maria@")
[
{ 'value': 'maria@mail.ru', ... },
{ 'value': 'maria@gmail.com', ... },
{ 'value': 'maria@yandex.ru', ... },
...
]
>>> dadata.find_by_id(name="fns_unit", query="5257")
[
{
'value': 'Инспекция ФНС России по Канавинскому району г.Нижнего Новгорода',
'unrestricted_value': 'Инспекция ФНС России по Канавинскому району г.Нижнего Новгорода',
'data': {
'code': '5257'
'oktmo': '22701000',
'inn': '5257046101',
'kpp': '525701001',
...
}
}
]
>>> dadata.suggest(name="region_court", query="таганско")
[
{ 'value': 'Судебный участок № 371 Таганского судебного района г. Москвы', ... },
{ 'value': 'Судебный участок № 372 Таганского судебного района г. Москвы', ... },
{ 'value': 'Судебный участок № 373 Таганского судебного района г. Москвы', ... },
...
]
>>> dadata.suggest(name="metro", query="алек")
[
{ 'value': 'Александровский сад', ... },
{ 'value': 'Алексеевская', ... },
{ 'value': 'Площадь Александра Невского 1', ... },
...
]
Constrain by city (Saint Petersburg):
>>> filters = [{ "city": "Санкт-Петербург" }]
>>> dadata.suggest(name="metro", query="алек", filters=filters)
[
{ 'value': 'Площадь Александра Невского 1', ... },
{ 'value': 'Площадь Александра Невского 2', ... }
]
>>> dadata.suggest(name="car_brand", query="фо")
[
{ 'value': 'Volkswagen', ... },
{ 'value': 'Ford', ... },
{ 'value': 'Foton', ... }
]
>>> dadata.suggest(name="currency", query="руб")
[
{ 'value': 'Белорусский рубль', ... },
{ 'value': 'Российский рубль', ... }
]
>>> dadata.suggest(name="okved2", query="космических")
[
{ 'value': 'Производство космических аппаратов (в том числе спутников), ракет-носителей', ... },
{ 'value': 'Производство автоматических космических аппаратов', ... },
{ 'value': 'Деятельность космических лабораторий', ... },
...
]
>>> dadata.suggest(name="okpd2", query="калоши")
[
{ 'value': 'Услуги по обрезинованию валенок (рыбацкие калоши)', ... }
]
Balance:
>>> dadata.get_balance()
150.00
Usage stats:
>>> dadata.get_daily_stats()
{
'date': '2024-10-10',
'services': {
'clean': 200,
'company': 0,
'company_similar': 0,
'merging': 0,
'suggestions': 15000,
},
'remaining': {
'clean': 800,
'company': 50,
'company_similar': 0,
'merging': 15000,
'suggestions': 185000
}
}
Dataset versions:
>>> dadata.get_versions()
{
'dadata': { 'version': 'stable (9048:bf33b2acc8ba)' },
'factor': {
'resources': { ... },
'version': '20.06 (eb70078e)'
},
'suggestions': {
'resources': { ... },
'version': '20.5 (b55eb7c4)'
}
}
$ python3 -m venv env
$ . env/bin/activate
$ make deps
$ tox
This project only accepts bug fixes.
This library uses CalVer with YY.MM.MICRO schema. See changelog for details specific to each release.