Dadata API Client

Data cleansing, enrichment and suggestions via Dadata API

Thin Python wrapper over Dadata API.

Installation

pip install dadata

Requirements:

• Python 3.9+
• httpx

Usage

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.

Usage (async)

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

Options

The default request timeout is 3 seconds. You can change it with the timeout parameter:

with Dadata(token, secret, timeout=1) as dadata:
    ...

Postal Address

Validate and cleanse address

>>> 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': [ ... ],
    ...
}

Geocode address

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,
    ...
}

Reverse geocode address

>>> dadata.geolocate(name="address", lat=55.878, lon=37.653)
[
    { 'value': 'г Москва, ул Сухонская, д 11', ... },
    { 'value': 'г Москва, ул Сухонская, д 11А', ... },
    { 'value': 'г Москва, ул Сухонская, д 13', ... },
    ...
]

GeoIP city

>>> dadata.iplocate("46.226.227.20")
{
    'value': 'г Краснодар',
    'unrestricted_value': '350000, Краснодарский край, г Краснодар',
    'data': { ... }
}

Autocomplete (suggest) address

>>> 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': 'Самарская обл, г Тольятти, ул Автостроителей' ... },
    ...
]

Find address by FIAS ID

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

Find postal office

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': { ... }
    }
]

Get City ID for delivery services

>>> 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'
        }
    }
]

Get address strictly according to FIAS

>>> dadata.find_by_id(name="fias", query="9120b43f-2fae-4838-a144-85e43c2bfb29")
[
    { 'value': 'г Москва, ул Снежная', ... }
]

Suggest country

>>> dadata.suggest(name="country", query="та")
[
    { 'value': 'Таджикистан', ... },
    { 'value': 'Таиланд', ... },
    { 'value': 'Тайвань', ... },
    ...
]

Company or individual enterpreneur

Find company by INN

>>> 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',
            ...
        }
    }
]

Find company by email

>>> dadata.find_by_email(name="company", query="info@dadata.ru")
[
    {
        'value': 'info@dadata.ru',
        'unrestricted_value': 'info@dadata.ru',
        'data': {
            'email': {...},
            'company': {
                'domain': 'dadata.ru',
                'name': 'ООО "ДЕЙТА КЬЮ"',
                'inn': '7721581040',
                ...
            }
        }
    }
]

Suggest company

>>> 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"])

Find affiliated companies

>>> dadata.find_affiliated("7736207543")
[
    { 'value': 'ООО "ДЗЕН.ПЛАТФОРМА"', ... },
    { 'value': 'ООО "ЕДАДИЛ"', ... },
    { 'value': 'ООО "ЗНАНИЕ"', ... },
    ...
]

Search only by manager INN:

>>> dadata.find_affiliated("773006366201", scope=["MANAGERS"])
[
    { 'value': 'ООО "ЯНДЕКС"', ... },
    { 'value': 'МФ "ФОИ"', ... },
    { 'value': 'АНО ДПО "ШАД"', ... },
]

Bank

Find bank by BIC, SWIFT or INN

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

Suggest bank

>>> dadata.suggest(name="bank", query="ти")
[
    { 'value': 'АО «Тимер Банк»', ... },
    { 'value': 'АО «Тинькофф Банк»', ... },
    { 'value': '«Азиатско-Тихоокеанский Банк» (ПАО)', ... },
    ...
]

Personal name

Validate and cleanse name

>>> dadata.clean(name="name", source="Срегей владимерович иванов")
{
    'source': 'Срегей владимерович иванов',
    'result': 'Иванов Сергей Владимирович',
    ...
    'surname': 'Иванов',
    'name': 'Сергей',
    'patronymic': 'Владимирович',
    'gender': 'М',
    'qc': 1
}

Suggest name

>>> dadata.suggest(name="fio", query="викт")
[
    { 'value': 'Виктор', ... },
    { 'value': 'Виктория', ... },
    { 'value': 'Викторова', ... },
    ...
]

Suggest female first name:

>>> dadata.suggest(name="fio", query="викт", parts=["NAME"], gender="FEMALE")
[
    { 'value': 'Виктория', ... },
    { 'value': 'Викторина', ... }
]

Phone

Validate and cleanse phone

>>> 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,
    ...
}

Passport

Validate passport

>>> dadata.clean(name="passport", source="4509 235857")
{
    'source': '4509 235857',
    'series': '45 09',
    'number': '235857',
    'qc': 0
}

Suggest issued by

>>> dadata.suggest(name="fms_unit", query="772 053")
[
    { 'value': 'ОВД ЗЮЗИНО Г. МОСКВЫ', ... },
    { 'value': 'ОВД РАЙОНА ЗЮЗИНО УВД ЮГО-ЗАО Г. МОСКВЫ', ... },
    { 'value': 'ПАСПОРТНО-ВИЗОВЫМ ОТДЕЛЕНИЕМ ОВД РАЙОНА ЗЮЗИНО Г. МОСКВЫ', ... },
    ...
]

Email

Validate email

>>> 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
}

Suggest email

>>> dadata.suggest(name="email", query="maria@")
[
    { 'value': 'maria@mail.ru', ... },
    { 'value': 'maria@gmail.com', ... },
    { 'value': 'maria@yandex.ru', ... },
    ...
]

Other datasets

Tax office

>>> dadata.find_by_id(name="fns_unit", query="5257")
[
    {
        'value': 'Инспекция ФНС России по Канавинскому району г.Нижнего Новгорода',
        'unrestricted_value': 'Инспекция ФНС России по Канавинскому району г.Нижнего Новгорода',
        'data': {
            'code': '5257'
            'oktmo': '22701000',
            'inn': '5257046101',
            'kpp': '525701001',
            ...
        }
    }
]

Regional court

>>> dadata.suggest(name="region_court", query="таганско")
[
    { 'value': 'Судебный участок № 371 Таганского судебного района г. Москвы', ... },
    { 'value': 'Судебный участок № 372 Таганского судебного района г. Москвы', ... },
    { 'value': 'Судебный участок № 373 Таганского судебного района г. Москвы', ... },
    ...
]

Metro station

>>> 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', ... }
]

Car brand

>>> dadata.suggest(name="car_brand", query="фо")
[
    { 'value': 'Volkswagen', ... },
    { 'value': 'Ford', ... },
    { 'value': 'Foton', ... }
]

Currency

>>> dadata.suggest(name="currency", query="руб")
[
    { 'value': 'Белорусский рубль', ... },
    { 'value': 'Российский рубль', ... }
]

OKVED 2

>>> dadata.suggest(name="okved2", query="космических")
[
    { 'value': 'Производство космических аппаратов (в том числе спутников), ракет-носителей', ... },
    { 'value': 'Производство автоматических космических аппаратов', ... },
    { 'value': 'Деятельность космических лабораторий', ... },
    ...
]

OKPD 2

>>> dadata.suggest(name="okpd2", query="калоши")
[
    { 'value': 'Услуги по обрезинованию валенок (рыбацкие калоши)', ... }
]

Profile API

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)'
    }
}

Development setup

$ python3 -m venv env
$ . env/bin/activate
$ make deps
$ tox

Contributing

This project only accepts bug fixes.

Changelog

This library uses CalVer with YY.MM.MICRO schema. See changelog for details specific to each release.

License

MIT