README

Typed PHP SDK for Dadata API generated from OpenAPI schemas.

The package exposes two generated clients:

• Glook\Dadata\Generated\Suggestions\Client for Suggestions API.
• Glook\Dadata\Generated\Clear\Client for Cleaner API.

For normal usage, create clients through the package factories instead of wiring HTTP clients and authentication plugins by hand.

Installation

composer require glook/dadata-php-sdk

Requirements:

• PHP 7.4 or newer
• ext-json
• A PSR-18 HTTP client available through php-http/discovery

If your application does not already provide a PSR-18 client, install one explicitly:

composer require symfony/http-client

Authentication

Dadata requires an API token and a secret key.

The factories add both generated authentication plugins automatically:

new AuthenticationRegistry([
    new DadataAuthorizationAuthentication('Token '.$token),
    new DadataSecretAuthentication($secret),
])

You only need to pass raw credentials:

use Glook\Dadata\DadataClientFactory;

$token = 'Replace with Dadata API key';
$secret = 'Replace with Dadata secret key';

$suggestions = DadataClientFactory::createSuggestionsClient($token, $secret);
$clear = DadataClientFactory::createClearClient($token, $secret);

HTTP Plugins

Factories accept an optional list of extra Http\Client\Common\Plugin instances. Authentication is always registered first, then your plugins are appended.

use Glook\Dadata\DadataClientFactory;
use Http\Client\Common\Plugin\HeaderDefaultsPlugin;
use Http\Client\Common\Plugin\RetryPlugin;

$client = DadataClientFactory::createSuggestionsClient($token, $secret, [
    new RetryPlugin(['retries' => 2]),
    new HeaderDefaultsPlugin([
        'User-Agent' => 'my-application/1.0',
    ]),
]);

This is the recommended extension point for retries, logging, caching, tracing, rate limiting, custom headers, and framework-specific integrations.

Fetch Modes

Generated methods return typed model objects by default:

$response = $client->suggestAddress($request);

To get the raw PSR-7 response instead, pass Client::FETCH_RESPONSE:

use Glook\Dadata\Generated\Suggestions\Client;

$response = $client->suggestAddress($request, Client::FETCH_RESPONSE);

Suggestions API

Create a Suggestions client:

use Glook\Dadata\DadataClientFactory;

$client = DadataClientFactory::createSuggestionsClient($token, $secret);

Suggest Address

use Glook\Dadata\Generated\Suggestions\Model\SuggestAddressRequest;

$request = (new SuggestAddressRequest())
    ->setQuery('самара метал')
    ->setCount(5);

$response = $client->suggestAddress($request);

foreach ($response->getSuggestions() ?? [] as $suggestion) {
    echo $suggestion->getValue().PHP_EOL;
}

Suggest Address in English

use Glook\Dadata\Generated\Suggestions\Model\SuggestAddressRequest;

$request = (new SuggestAddressRequest())
    ->setQuery('samara metal')
    ->setCount(5)
    ->setLanguage('en');

$response = $client->suggestAddress($request);

Find Address by FIAS or KLADR ID

use Glook\Dadata\Generated\Suggestions\Model\FindAddressByIdRequest;

$request = (new FindAddressByIdRequest())
    ->setQuery('9120b43f-2fae-4838-a144-85e43c2bfb29')
    ->setCount(1);

$response = $client->findByIdAddress($request);

Reverse Geocode Address

use Glook\Dadata\Generated\Suggestions\Model\GeoLocateAddressRequest;

$request = (new GeoLocateAddressRequest())
    ->setLat(55.878)
    ->setLon(37.653)
    ->setRadiusMeters(1000)
    ->setCount(5);

$response = $client->geoLocateAddress($request);

Find Company by INN

use Glook\Dadata\Generated\Suggestions\Model\FindPartyByIdRequest;

$request = (new FindPartyByIdRequest())
    ->setQuery('7707083893')
    ->setCount(5);

$response = $client->findByIdParty($request);

Find by INN and KPP:

$request = (new FindPartyByIdRequest())
    ->setQuery('7707083893')
    ->setKpp('540602001')
    ->setCount(1);

$response = $client->findByIdParty($request);

Suggest Company

use Glook\Dadata\Generated\Suggestions\Model\SuggestPartyRequest;

$request = (new SuggestPartyRequest())
    ->setQuery('сбер')
    ->setCount(5);

$response = $client->suggestParty($request);

Suggest Bank

use Glook\Dadata\Generated\Suggestions\Model\SuggestBankRequest;

$request = (new SuggestBankRequest())
    ->setQuery('ти')
    ->setCount(5);

$response = $client->suggestBank($request);

Suggest Email

use Glook\Dadata\Generated\Suggestions\Model\SuggestRequest;

$request = (new SuggestRequest())
    ->setQuery('maria@')
    ->setCount(5);

$response = $client->suggestEmail($request);

Suggestions Methods

Method	Dadata area
suggestAddress(SuggestAddressRequest $request)	Address suggestions
suggestParty(SuggestPartyRequest $request)	Company suggestions
suggestBank(SuggestBankRequest $request)	Bank suggestions
suggestEmail(SuggestRequest $request)	Email suggestions
suggestFio(SuggestFioRequest $request)	Personal name suggestions
suggestFias(SuggestFiasRequest $request)	FIAS suggestions
suggestOutward(string $name, SuggestOutwardRequest $request)	Generic suggest endpoint
findByIdAddress(FindAddressByIdRequest $request)	Find address by ID
findByIdParty(FindPartyByIdRequest $request)	Find company by INN/OGRN
findByIdBank(FindBankByIdRequest $request)	Find bank by BIC, SWIFT, INN, or registration number
findByIdFias(FindFiasByIdRequest $request)	Find address strictly by FIAS
findByIdDelivery(SuggestRequest $request)	Delivery city IDs
findByEmailCompany(SuggestRequest $request)	Find company by email
findAffiliatedParty(FindAffiliatedPartyRequest $request)	Find affiliated companies
geoLocateAddress(GeoLocateAddressRequest $request)	Reverse geocode address
geoLocateOutward(string $name, GeoLocateOutwardRequest $request)	Generic geolocate endpoint
ipLocateAddress(IpLocateAddressRequest $request)	GeoIP address lookup
findByIdOutward(string $name, SuggestRequest $request)	Generic find-by-id endpoint

Cleaner API

Create a Cleaner client:

use Glook\Dadata\DadataClientFactory;

$client = DadataClientFactory::createClearClient($token, $secret);

Clean Address

Cleaner methods accept arrays of strings and return arrays of typed result models.

$addresses = $client->cleanAddress([
    'мск сухонская 11 89',
]);

foreach ($addresses ?? [] as $address) {
    echo $address->getResult().PHP_EOL;
    echo $address->getPostalCode().PHP_EOL;
}

Clean Name

$names = $client->cleanName([
    'Срегей владимерович иванов',
]);

foreach ($names ?? [] as $name) {
    echo $name->getResult().PHP_EOL;
}

Clean Phone

$phones = $client->cleanPhone([
    '9168-233-454',
]);

foreach ($phones ?? [] as $phone) {
    echo $phone->getPhone().PHP_EOL;
}

Clean Email

$emails = $client->cleanEmail([
    'serega@yandex/ru',
]);

foreach ($emails ?? [] as $email) {
    echo $email->getEmail().PHP_EOL;
}

Clean Composite Record

Use cleanRecord() when one input row contains multiple fields.

use Glook\Dadata\Generated\Clear\Model\RecordString;

$request = (new RecordString())
    ->setStructure(['NAME', 'PHONE', 'EMAIL'])
    ->setData([
        ['Срегей владимерович иванов', '9168-233-454', 'serega@yandex/ru'],
    ]);

$response = $client->cleanRecord($request);

Cleaner Methods

Method	Dadata area
cleanAddress(array $values)	Address cleansing and geocoding
cleanName(array $values)	Personal name cleansing
cleanPhone(array $values)	Phone cleansing
cleanEmail(array $values)	Email cleansing
cleanBirthdate(array $values)	Birthdate cleansing
cleanPassport(array $values)	Passport cleansing
cleanVehicle(array $values)	Vehicle cleansing
cleanAsIs(array $values)	Return values without cleansing
cleanRecord(RecordString $request)	Composite record cleansing

Error Handling

Generated methods throw UnexpectedStatusCodeException when Dadata returns an unexpected HTTP status code.

use Glook\Dadata\Generated\Suggestions\Exception\UnexpectedStatusCodeException;

try {
    $response = $client->suggestAddress($request);
} catch (UnexpectedStatusCodeException $exception) {
    $statusCode = $exception->getCode();
}

For Cleaner API imports, use Glook\Dadata\Generated\Clear\Exception\UnexpectedStatusCodeException.

Project Structure

src/
  DadataClientFactory.php
generated/
  clear/
  suggestions/
schemas/
  clear.yml
  suggestions.yml
config/
  clear-config.php
  suggestions-config.php

• src/ contains hand-written public entry points.
• generated/ contains JanePHP-generated SDK code and is committed to the package.
• schemas/ contains OpenAPI schemas used for generation.
• config/ contains JanePHP generator configuration.

Development

Install dependencies:

composer install

Run checks:

composer check

Run unit tests:

composer test

Regenerate clients from schemas:

composer generate:all

Generate only one client:

composer generate:suggestions
composer generate:clear

After generation, review generated code and commit it together with schema/config changes.

License

MIT