PHPackages                             ex3mm/dadata - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. ex3mm/dadata

ActiveLibrary[API Development](/categories/api)

ex3mm/dadata
============

DaData.ru API client for Laravel 12+ and standalone PHP 8.5+

01—0%PHP

Since Mar 12Pushed 2mo agoCompare

[ Source](https://github.com/ex3mm/dadata)[ Packagist](https://packagist.org/packages/ex3mm/dadata)[ RSS](/packages/ex3mm-dadata/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

ex3mm/dadata
============

[](#ex3mmdadata)

Production-ready Laravel-пакет для интеграции с DaData.ru API.

Возможности
-----------

[](#возможности)

- Типобезопасная работа с DaData API (PHP 8.5 + strict types)
- Поддержка Laravel 12 и standalone PHP
- Кеширование успешных ответов
- Rate limiting с алгоритмом Sliding Window
- Retry с exponential backoff
- Полная маскировка API-ключей в логах
- Lazy initialization HTTP-клиента
- PSR-3 (логирование)
- PSR-16 (кеширование)

Требования
----------

[](#требования)

- PHP ^8.5
- Laravel ^12.0 (опционально)

Установка
---------

[](#установка)

### Laravel

[](#laravel)

```
composer require ex3mm/dadata
```

Опубликуйте конфигурацию:

```
php artisan vendor:publish --tag=dadata-config
```

Добавьте в `.env`:

```
DADATA_API_KEY=your_api_key_here
DADATA_SECRET_KEY=your_secret_key_here
```

### Standalone PHP

[](#standalone-php)

```
composer require ex3mm/dadata
```

Быстрый старт
-------------

[](#быстрый-старт)

### Laravel

[](#laravel-1)

```
use Ex3mm\Dadata\Laravel\Facades\Dadata;

// Подсказки по адресам
$response = Dadata::suggestAddress()
    ->query('Москва, Тверская')
    ->count(5)
    ->send();

foreach ($response->suggestions as $suggestion) {
    echo $suggestion->value . PHP_EOL;
}
```

### Standalone

[](#standalone)

```
use Ex3mm\Dadata\DadataFactory;

$client = DadataFactory::create(
    apiKey: 'your_api_key',
    secretKey: 'your_secret_key'
);

$response = $client->suggestAddress()
    ->query('Москва, Тверская')
    ->send();
```

Конфигурация
------------

[](#конфигурация)

Все параметры настраиваются через `config/dadata.php` или переменные окружения:

```
# Credentials
DADATA_API_KEY=
DADATA_SECRET_KEY=

# HTTP
DADATA_CONNECT_TIMEOUT=10
DADATA_TIMEOUT=30

# Retry
DADATA_RETRY_ATTEMPTS=3
DADATA_RETRY_DELAY=100

# Cache
DADATA_CACHE_ENABLED=true
DADATA_CACHE_TTL=3600
DADATA_CACHE_STORE=

# Logging
DADATA_LOG_LEVEL=info
DADATA_LOG_REQUEST_BODY=false
DADATA_LOG_RESPONSE_BODY=false

# Rate Limiting
DADATA_RATE_LIMIT_ENABLED=true
DADATA_RATE_LIMIT=20
```

### ⚠️ Важно: Кеширование в production

[](#️-важно-кеширование-в-production)

По умолчанию пакет использует `InMemoryCache`, который **не подходит для production** из-за:

- Потери данных при перезапуске приложения
- Race condition при параллельных запросах
- Отсутствия синхронизации между процессами

**Для production рекомендуется использовать Redis:**

```
# .env
DADATA_CACHE_STORE=redis
```

```
// config/dadata.php
'cache_store' => env('DADATA_CACHE_STORE', 'redis'),
```

Убедитесь, что Redis настроен в `config/cache.php`:

```
'stores' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'cache',
    ],
],
```

API Endpoints
-------------

[](#api-endpoints)

### 1. Стандартизация адресов (Clean Address)

[](#1-стандартизация-адресов-clean-address)

```
$response = Dadata::cleanAddress()
    ->address('мск сухонская 11 89')
    ->send();

echo $response->result; // Москва, ул Сухонская, д 11, кв 89
```

### 2. Подсказки по адресам (Suggest Address)

[](#2-подсказки-по-адресам-suggest-address)

```
$response = Dadata::suggestAddress()
    ->query('Москва, Тверская')
    ->count(10)
    ->fromBound(AddressBound::STREET)
    ->toBound(AddressBound::HOUSE)
    ->send();
```

### 3. Подсказки по организациям (Suggest Party)

[](#3-подсказки-по-организациям-suggest-party)

```
$response = Dadata::suggestParty()
    ->query('Сбербанк')
    ->count(5)
    ->status(PartyStatus::ACTIVE)
    ->send();
```

### 4. Поиск организации по ИНН/ОГРН (Find Party)

[](#4-поиск-организации-по-инногрн-find-party)

```
$response = Dadata::findParty()
    ->query('7707083893') // ИНН
    ->send();
```

### 5. Произвольный запрос (Raw)

[](#5-произвольный-запрос-raw)

```
$response = Dadata::raw()
    ->url('https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/bank')
    ->method('POST')
    ->body(['query' => 'Сбербанк'])
    ->send();
```

Детальное описание API методов
------------------------------

[](#детальное-описание-api-методов)

### SuggestAddressRequest - Подсказки по адресам

[](#suggestaddressrequest---подсказки-по-адресам)

Fluent builder для получения подсказок адресов от DaData API.

#### Методы

[](#методы)

**query(string $query): static**

- Устанавливает поисковый запрос
- Обязательный параметр
- Пример: `->query('Москва, Тверская')`

**count(int $count): static**

- Устанавливает количество подсказок (1-20)
- По умолчанию: 10
- Пример: `->count(5)`

**fromBound(AddressBound $bound): static**

- Устанавливает нижнюю границу детализации адреса
- Опциональный параметр
- Пример: `->fromBound(AddressBound::STREET)`

**toBound(AddressBound $bound): static**

- Устанавливает верхнюю границу детализации адреса
- Опциональный параметр
- Пример: `->toBound(AddressBound::HOUSE)`

**language(Language $language): static**

- Устанавливает язык подсказок
- По умолчанию: Language::RU
- Пример: `->language(Language::EN)`

**locations(array $locations): static**

- Устанавливает географические ограничения для поиска
- Опциональный параметр
- Пример: `->locations(['region' => 'Москва'])`

**send(): SuggestAddressResponse**

- Отправляет запрос и возвращает типизированный ответ
- Бросает исключения при ошибках

#### Пример использования

[](#пример-использования)

```
use Ex3mm\Dadata\DTO\Enums\AddressBound;
use Ex3mm\Dadata\DTO\Enums\Language;
use Ex3mm\Dadata\Laravel\Facades\Dadata;

$response = Dadata::suggestAddress()
    ->query('Москва, Тверская')
    ->count(10)
    ->fromBound(AddressBound::STREET)
    ->toBound(AddressBound::HOUSE)
    ->language(Language::RU)
    ->send();

foreach ($response->suggestions as $suggestion) {
    echo $suggestion->value . PHP_EOL;
    echo $suggestion->data->city . PHP_EOL;
}
```

---

### SuggestPartyRequest - Подсказки по организациям

[](#suggestpartyrequest---подсказки-по-организациям)

Fluent builder для получения подсказок организаций от DaData API.

#### Методы

[](#методы-1)

**query(string $query): static**

- Устанавливает поисковый запрос (название, ИНН, ОГРН)
- Обязательный параметр
- Пример: `->query('Сбербанк')`

**count(int $count): static**

- Устанавливает количество подсказок
- По умолчанию: 10
- Пример: `->count(5)`

**status(PartyStatus $status): static**

- Фильтрует по статусу организации
- Опциональный параметр
- Пример: `->status(PartyStatus::ACTIVE)`

**type(PartyType $type): static**

- Фильтрует по типу организации
- Опциональный параметр
- Пример: `->type(PartyType::LEGAL)`

**send(): SuggestPartyResponse**

- Отправляет запрос и возвращает типизированный ответ
- Бросает исключения при ошибках

#### Пример использования

[](#пример-использования-1)

```
use Ex3mm\Dadata\DTO\Enums\PartyStatus;
use Ex3mm\Dadata\DTO\Enums\PartyType;
use Ex3mm\Dadata\Laravel\Facades\Dadata;

$response = Dadata::suggestParty()
    ->query('Сбербанк')
    ->count(5)
    ->status(PartyStatus::ACTIVE)
    ->type(PartyType::LEGAL)
    ->send();

foreach ($response->suggestions as $suggestion) {
    echo $suggestion->value . PHP_EOL;
    echo 'ИНН: ' . $suggestion->data->inn . PHP_EOL;
}
```

---

### CleanAddressRequest - Стандартизация адресов

[](#cleanaddressrequest---стандартизация-адресов)

Fluent builder для стандартизации и очистки адресов.

#### Методы

[](#методы-2)

**address(string $address): static**

- Устанавливает адрес для стандартизации
- Обязательный параметр
- Пример: `->address('мск сухонская 11 89')`

**send(): CleanAddressResponse**

- Отправляет запрос и возвращает типизированный ответ
- Бросает исключения при ошибках

#### Пример использования

[](#пример-использования-2)

```
use Ex3mm\Dadata\Laravel\Facades\Dadata;

$response = Dadata::cleanAddress()
    ->address('мск сухонская 11 89')
    ->send();

echo $response->result; // Москва, ул Сухонская, д 11, кв 89
echo $response->postalCode; // 127642
echo $response->fiasId; // UUID адреса в ФИАС
```

---

### FindPartyRequest - Поиск организации по ИНН/ОГРН

[](#findpartyrequest---поиск-организации-по-инногрн)

Fluent builder для точного поиска организаций по идентификаторам.

#### Методы

[](#методы-3)

**query(string $innOrOgrn): static**

- Устанавливает ИНН (10 или 12 цифр) или ОГРН (13 или 15 цифр)
- Обязательный параметр
- Валидирует формат идентификатора
- Пример: `->query('7707083893')`

**count(int $count): static**

- Устанавливает количество результатов
- По умолчанию: 10
- Пример: `->count(1)`

**type(PartyType $type): static**

- Фильтрует по типу организации
- Опциональный параметр
- Пример: `->type(PartyType::LEGAL)`

**send(): FindPartyResponse**

- Отправляет запрос и возвращает типизированный ответ
- Бросает исключения при ошибках

#### Пример использования

[](#пример-использования-3)

```
use Ex3mm\Dadata\DTO\Enums\PartyType;
use Ex3mm\Dadata\Laravel\Facades\Dadata;

$response = Dadata::findParty()
    ->query('7707083893') // ИНН Сбербанка
    ->count(1)
    ->type(PartyType::LEGAL)
    ->send();

if (!empty($response->suggestions)) {
    $party = $response->suggestions[0];
    echo $party->value . PHP_EOL;
    echo 'ОГРН: ' . $party->data->ogrn . PHP_EOL;
    echo 'Адрес: ' . $party->data->address->value . PHP_EOL;
}
```

---

### RawRequest - Произвольный запрос

[](#rawrequest---произвольный-запрос)

Fluent builder для выполнения произвольных запросов к DaData API.

#### Методы

[](#методы-4)

**url(string $url): static**

- Устанавливает полный URL для запроса
- Обязательный параметр
- Пример: `->url('https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/bank')`

**method(string $method): static**

- Устанавливает HTTP-метод
- По умолчанию: POST
- Пример: `->method('POST')`

**body(array $body): static**

- Устанавливает тело запроса
- Опциональный параметр
- Пример: `->body(['query' => 'Сбербанк'])`

**withHeaders(array $headers): static**

- Добавляет дополнительные заголовки
- Опциональный параметр
- Пример: `->withHeaders(['X-Custom-Header' => 'value'])`

**send(): RawResponse**

- Отправляет запрос и возвращает сырой ответ
- Бросает исключения при ошибках

#### Пример использования

[](#пример-использования-4)

```
use Ex3mm\Dadata\Laravel\Facades\Dadata;

$response = Dadata::raw()
    ->url('https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/bank')
    ->method('POST')
    ->body(['query' => 'Сбербанк', 'count' => 5])
    ->send();

$data = $response->data; // Массив с результатами
```

Enum значения
-------------

[](#enum-значения)

Пакет предоставляет типизированные Enum для параметров запросов.

### AddressBound - Уровни детализации адреса

[](#addressbound---уровни-детализации-адреса)

Используется для ограничения детализации подсказок адресов через методы `fromBound()` и `toBound()`.

ЗначениеОписаниеПример использования`AddressBound::COUNTRY`Страна`->fromBound(AddressBound::COUNTRY)``AddressBound::REGION`Регион`->fromBound(AddressBound::REGION)``AddressBound::AREA`Район`->fromBound(AddressBound::AREA)``AddressBound::CITY`Город`->fromBound(AddressBound::CITY)``AddressBound::CITY_DISTRICT`Район города`->fromBound(AddressBound::CITY_DISTRICT)``AddressBound::SETTLEMENT`Населённый пункт`->fromBound(AddressBound::SETTLEMENT)``AddressBound::STREET`Улица`->fromBound(AddressBound::STREET)``AddressBound::HOUSE`Дом`->toBound(AddressBound::HOUSE)``AddressBound::FLAT`Квартира`->toBound(AddressBound::FLAT)`#### Примеры

[](#примеры)

```
// Только улицы и дома (без квартир)
$response = Dadata::suggestAddress()
    ->query('Москва, Тверская')
    ->fromBound(AddressBound::STREET)
    ->toBound(AddressBound::HOUSE)
    ->send();

// Только города (без улиц)
$response = Dadata::suggestAddress()
    ->query('Москва')
    ->fromBound(AddressBound::CITY)
    ->toBound(AddressBound::CITY)
    ->send();

// От региона до улицы
$response = Dadata::suggestAddress()
    ->query('Московская область')
    ->fromBound(AddressBound::REGION)
    ->toBound(AddressBound::STREET)
    ->send();
```

---

### PartyType - Тип организации

[](#partytype---тип-организации)

Используется для фильтрации организаций по типу в методах `suggestParty()` и `findParty()`.

ЗначениеОписаниеПример использования`PartyType::LEGAL`Юридическое лицо (ООО, АО, ПАО и т.д.)`->type(PartyType::LEGAL)``PartyType::INDIVIDUAL`Индивидуальный предприниматель (ИП)`->type(PartyType::INDIVIDUAL)`#### Примеры

[](#примеры-1)

```
// Только юридические лица
$response = Dadata::suggestParty()
    ->query('Сбербанк')
    ->type(PartyType::LEGAL)
    ->send();

// Только ИП
$response = Dadata::suggestParty()
    ->query('Иванов')
    ->type(PartyType::INDIVIDUAL)
    ->send();
```

---

### PartyStatus - Статус организации

[](#partystatus---статус-организации)

Используется для фильтрации организаций по статусу в методе `suggestParty()`.

ЗначениеОписаниеПример использования`PartyStatus::ACTIVE`Действующая организация`->status(PartyStatus::ACTIVE)``PartyStatus::LIQUIDATING`Организация в процессе ликвидации`->status(PartyStatus::LIQUIDATING)``PartyStatus::LIQUIDATED`Ликвидированная организация`->status(PartyStatus::LIQUIDATED)``PartyStatus::BANKRUPT`Организация в процессе банкротства`->status(PartyStatus::BANKRUPT)``PartyStatus::REORGANIZING`Организация в процессе реорганизации`->status(PartyStatus::REORGANIZING)`#### Примеры

[](#примеры-2)

```
// Только действующие организации
$response = Dadata::suggestParty()
    ->query('Сбербанк')
    ->status(PartyStatus::ACTIVE)
    ->send();

// Ликвидированные организации
$response = Dadata::suggestParty()
    ->query('Старая компания')
    ->status(PartyStatus::LIQUIDATED)
    ->send();

// Комбинация фильтров
$response = Dadata::suggestParty()
    ->query('ООО')
    ->type(PartyType::LEGAL)
    ->status(PartyStatus::ACTIVE)
    ->send();
```

---

### Language - Язык подсказок

[](#language---язык-подсказок)

Используется для выбора языка подсказок адресов в методе `suggestAddress()`.

ЗначениеОписаниеПример использования`Language::RU`Русский язык (по умолчанию)`->language(Language::RU)``Language::EN`Английский язык`->language(Language::EN)`#### Примеры

[](#примеры-3)

```
// Подсказки на русском (по умолчанию)
$response = Dadata::suggestAddress()
    ->query('Москва')
    ->language(Language::RU)
    ->send();
// Результат: "г Москва"

// Подсказки на английском
$response = Dadata::suggestAddress()
    ->query('Moscow')
    ->language(Language::EN)
    ->send();
// Результат: "Moscow"
```

---

### AddressFiasLevel - Уровень ФИАС

[](#addressfiaslevel---уровень-фиас)

Enum для работы с уровнями классификатора ФИАС. Используется в DTO ответов для определения уровня детализации адреса.

ЗначениеКодОписание`AddressFiasLevel::UNKNOWN`-1Неизвестный уровень`AddressFiasLevel::COUNTRY`0Страна`AddressFiasLevel::REGION`1Регион`AddressFiasLevel::AREA`3Район`AddressFiasLevel::CITY`4Город`AddressFiasLevel::CITY_DISTRICT`5Район города`AddressFiasLevel::SETTLEMENT`6Населённый пункт`AddressFiasLevel::STREET`7Улица`AddressFiasLevel::HOUSE`8Дом`AddressFiasLevel::FLAT`9Квартира#### Пример использования

[](#пример-использования-5)

```
use Ex3mm\Dadata\DTO\Enums\AddressFiasLevel;
use Ex3mm\Dadata\Laravel\Facades\Dadata;

$response = Dadata::suggestAddress()
    ->query('Москва, Тверская, 1')
    ->send();

foreach ($response->suggestions as $suggestion) {
    $fiasLevel = $suggestion->data->fiasLevel;

    if ($fiasLevel === AddressFiasLevel::HOUSE) {
        echo "Адрес детализирован до дома: {$suggestion->value}" . PHP_EOL;
    } elseif ($fiasLevel === AddressFiasLevel::STREET) {
        echo "Адрес детализирован до улицы: {$suggestion->value}" . PHP_EOL;
    }
}
```

Обработка исключений
--------------------

[](#обработка-исключений)

Пакет предоставляет специализированные исключения для различных типов ошибок:

### Иерархия исключений

[](#иерархия-исключений)

```
DadataException (базовое исключение)
├── ApiException (HTTP 4xx/5xx от API)
├── NetworkException (сетевые ошибки: timeout, connection refused)
├── AuthenticationException (401/403)
├── RateLimitException (429, превышение лимита)
└── ConfigurationException (невалидная конфигурация)

```

### Примеры обработки

[](#примеры-обработки)

#### ApiException — ошибки API

[](#apiexception--ошибки-api)

```
use Ex3mm\Dadata\Exceptions\ApiException;
use Illuminate\Support\Facades\Log;

try {
    $response = Dadata::cleanAddress()
        ->address('невалидный адрес')
        ->send();
} catch (ApiException $e) {
    Log::error('Ошибка DaData API', [
        'status' => $e->getStatusCode(),
        'message' => $e->getMessage(),
        'raw_response' => $e->getRawResponse(),
    ]);

    // Обработка в зависимости от статуса
    if ($e->getStatusCode() === 400) {
        return response()->json(['error' => 'Невалидный адрес'], 400);
    }
}
```

#### RateLimitException — превышение лимита запросов

[](#ratelimitexception--превышение-лимита-запросов)

```
use Ex3mm\Dadata\Exceptions\RateLimitException;

try {
    $response = Dadata::suggestAddress()
        ->query('Москва')
        ->send();
} catch (RateLimitException $e) {
    // Получаем время до следующей попытки
    $retryAfter = $e->getRetryAfter();

    Log::warning("Rate limit exceeded, retry after {$retryAfter}s");

    // Ждём и повторяем
    sleep($retryAfter);
    $response = Dadata::suggestAddress()->query('Москва')->send();
}
```

#### NetworkException — сетевые ошибки

[](#networkexception--сетевые-ошибки)

```
use Ex3mm\Dadata\Exceptions\NetworkException;

try {
    $response = Dadata::findParty()
        ->query('7707083893')
        ->send();
} catch (NetworkException $e) {
    Log::error('Сетевая ошибка DaData', [
        'message' => $e->getMessage(),
        'previous' => $e->getPrevious()?->getMessage(),
    ]);

    // Fallback или повторная попытка
    return $this->fallbackPartySearch($inn);
}
```

#### AuthenticationException — ошибки авторизации

[](#authenticationexception--ошибки-авторизации)

```
use Ex3mm\Dadata\Exceptions\AuthenticationException;
use Illuminate\Support\Facades\Notification;

try {
    $response = Dadata::suggestParty()
        ->query('Сбербанк')
        ->send();
} catch (AuthenticationException $e) {
    // Критическая ошибка — уведомляем администратора
    Log::critical('Ошибка авторизации DaData', [
        'code' => $e->getCode(),
        'message' => $e->getMessage(),
    ]);

    Notification::send($admin, new DadataAuthFailedNotification($e));

    throw $e; // Пробрасываем дальше
}
```

#### Обработка всех исключений

[](#обработка-всех-исключений)

```
use Ex3mm\Dadata\Exceptions\DadataException;

try {
    $response = Dadata::cleanAddress()
        ->address($address)
        ->send();
} catch (DadataException $e) {
    // Обрабатываем любое исключение пакета
    Log::error('DaData error', [
        'type' => get_class($e),
        'message' => $e->getMessage(),
        'code' => $e->getCode(),
    ]);

    return null; // Или fallback-значение
}
```

Безопасность
------------

[](#безопасность)

API-ключи автоматически маскируются во всех логах и исключениях:

```
// В логах вместо реального ключа будет "***"
[2026-03-11 10:00:00] info: POST https://suggestions.dadata.ru/...?key=***
```

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance58

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/f01600d020e8476851965036a64a38bfb941a85de2ac1f633e5e9d913733995e?d=identicon)[Ex3mm](/maintainers/Ex3mm)

---

Top Contributors

[![ex3mm](https://avatars.githubusercontent.com/u/23587681?v=4)](https://github.com/ex3mm "ex3mm (1 commits)")

### Embed Badge

![Health badge](/badges/ex3mm-dadata/health.svg)

```
[![Health](https://phpackages.com/badges/ex3mm-dadata/health.svg)](https://phpackages.com/packages/ex3mm-dadata)
```

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[knplabs/github-api

GitHub API v3 client

2.2k15.8M187](/packages/knplabs-github-api)[facebook/php-business-sdk

PHP SDK for Facebook Business

90121.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

73813.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

263103.1M454](/packages/google-gax)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)