Skip to main content

Data cleansing and enrichment via Dadata API.

Project description

Dadata API Client

Data cleansing, enrichment and suggestions via Dadata API

Thin Python wrapper over Dadata API.

Installation

pip install dadata

Requirements:

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

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

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

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Make sure to add or update tests as appropriate.

Use Black for code formatting and Conventional Commits for commit messages.

Changelog

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

License

MIT

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dadata-24.10.0.tar.gz (17.6 kB view details)

Uploaded Source

Built Distribution

dadata-24.10.0-py3-none-any.whl (10.7 kB view details)

Uploaded Python 3

File details

Details for the file dadata-24.10.0.tar.gz.

File metadata

  • Download URL: dadata-24.10.0.tar.gz
  • Upload date:
  • Size: 17.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.32.3

File hashes

Hashes for dadata-24.10.0.tar.gz
Algorithm Hash digest
SHA256 0b6f98a9ef576ec9eebd4b8ca9c6d50f5531685833637bc20fbd5d7b523ede76
MD5 fd5b0256fd68b952e71a078c4458fc67
BLAKE2b-256 a4d98a3d515156e0131f4d4994ea5e8e9160a661ba234fdc8c4547301a2a75fe

See more details on using hashes here.

File details

Details for the file dadata-24.10.0-py3-none-any.whl.

File metadata

  • Download URL: dadata-24.10.0-py3-none-any.whl
  • Upload date:
  • Size: 10.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.32.3

File hashes

Hashes for dadata-24.10.0-py3-none-any.whl
Algorithm Hash digest
SHA256 588a449625435c6d9370f10a15ac669105d974154d077833eddaa38eb933a15b
MD5 6956744a2d13d24bf30afd5e79e10d4a
BLAKE2b-256 8a3c5a80379f5b426203032ef59389d7a84b2a0a7e7b03653f79a25d97540c10

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page