🏠 Клиент ФИАС Public API на Python

Python-клиент для ФИАС Public API — федеральной информационной адресной системы Российской Федерации. Поддерживает синхронные и асинхронные операции.

📦 Установка

Установка из PyPI (рекомендуется)

pip install fias-public-api

Установка из GitHub

pip install git+https://github.com/quonaro/fias-public-api

🔌 Зависимости

Пакет	Версия	Описание
requests	>=2.32.5	HTTP библиотека для API запросов
httpx	>=0.28.1	Асинхронная HTTP библиотека

🚀 Быстрый старт

Синхронный пример

fromfias_public_apiimportget_token_sync, SyncFPA, AddressType# Получаем токен автоматическиtoken=get_token_sync()
# Создаем клиент (address_type обязателен: 1 — административный, 2 — муниципальный)api=SyncFPA(token, AddressType.ADMINISTRATIVE)
# Ищем адресresults=api.search("Москва, Красная площадь")
print(f"Найдено: {len(results)} результатов")
# Получаем детали первого результатаifresults:
details=api.details_by_id(results[0]['id'])
print(f"Адрес: {details.get('address', 'N/A')}")

Асинхронный пример

importasynciofromfias_public_apiimportget_token_async, AsyncFPA, AddressTypeasyncdefmain():
token=awaitget_token_async()
asyncwithAsyncFPA(token, AddressType.ADMINISTRATIVE) asapi:
results=awaitapi.search("Москва, Красная площадь")
print(f"Найдено: {len(results)} результатов")
ifresults:
details=awaitapi.details_by_id(results[0]['id'])
print(f"Адрес: {details.get('address', 'N/A')}")
asyncio.run(main())

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

🔍 Поиск адресов

# Простой поиск (используется address_type из конструктора)results=api.search("Москва")
# Поиск с переопределением address_type для конкретного вызоваresults=api.search("Санкт-Петербург", address_type=AddressType.MUNICIPALITY)
# Обработка результатовforresultinresults:
print(f"ID: {result['id']}")
print(f"Адрес: {result['address']}")
print(f"Тип: {result['type']}")

🗺️ Получить список регионов

regions=api.get_regions()
forregioninregions:
print(region['name'])

🆔 Детали по ID

fromfias_public_apiimportAddressTypeobject_id=12345# address_type можно переопределить для конкретного вызоваdetails=api.details_by_id(object_id, address_type=AddressType.MUNICIPALITY)

🧬 Детали по GUID

object_guid="some-guid-string"details=api.details_by_guid(object_guid, address_type=AddressType.ADMINISTRATIVE)

📍 Местоположение по IP

location=api.get_location_by_ip("8.8.8.8")
print(location)

🛠️ Фильтрация адресных объектов

items=api.get_address_items(
path="7700000000000",
address_level=7,
name_part="Тверская"
)

💡 Подсказки по адресу

hints=api.get_address_hint(
search_string="Москва",
up_to_level=5
)

⚙️ Опции клиента

fromfias_public_apiimportAddressTypeapi=SyncFPA(
token,
address_type=AddressType.ADMINISTRATIVE,
enable_logging=True,
)

🔄 Retry-декоратор

fromfias_public_apiimportretry_on_errorfromrequests.exceptionsimportConnectionError, HTTPError@retry_on_error(max_retries=5,delay=1.0,backoff=2.0,exceptions=(ConnectionError, HTTPError))defsearch_with_retry(search_string):
returnapi.search_address_items(search_string)

🔄 Обработка ошибок

fromrequests.exceptionsimportHTTPError, RequestExceptiontry:
results=api.search("Несуществующий адрес")
exceptHTTPErrorase:
ife.response.status_code==404:
print("Адрес не найден")
elife.response.status_code==401:
print("Неверный токен")
else:
print(f"HTTP ошибка: {e}")
exceptRequestExceptionase:
print(f"Ошибка сети: {e}")

📚 Методы API

Синхронные методы (SyncFPA)

• search(search_string, address_type) — поиск адресов по текстовой строке
• details_by_id(object_id, address_type) — детали по ID
• details_by_guid(object_guid, address_type) — детали по GUID
• get_regions() — список регионов
• get_address_items(...) — фильтрация адресных объектов
• get_details(object_id) — дополнительные сведения
• is_descendant(ancestor, descendant, address_type) — проверка вложенности
• has_descendants(parent, up_to_level, address_type) — проверка наличия потомков
• get_address_item_by_cadastral_number(number, address_type) — по кадастровому номеру
• get_fias_object_types() — типы объектов ФИАС
• search_address_items(search_string, address_type) — поиск по строке
• get_address_hint(...) — подсказки по адресу
• search_address_item(search_string, address_type) — поиск одного объекта
• get_location_by_ip(ip, address_type) — местоположение по IP

Асинхронные методы (AsyncFPA)

Все методы из SyncFPA доступны в асинхронной версии с поддержкой async/await.

Вспомогательные функции

• get_token_sync(url) — получить токен (синхронно)
• get_token_async(url) — получить токен (асинхронно)
• STANDART_HEADERS(token) — стандартные HTTP-заголовки
• AddressType — перечисление типов адресов (ADMINISTRATIVE = 1, MUNICIPALITY = 2)
• retry_on_error(...) — декоратор для повторных попыток при ошибках

📁 Примеры из папки examples

Все примеры доступны в папке examples/:

• 01_basic_usage.py — базовое использование API
• 02_address_types.py — работа с типами адресов
• 03_async_usage.py — асинхронное использование
• 04_retry_decorator.py — использование retry декоратора
• 05_address_info_methods.py — методы AddressInfo
• 06_search_methods.py — методы поиска
• 07_location_methods.py — определение локации по IP
• 08_error_handling.py — обработка ошибок

🧪 Тестирование

# Установка зависимостей для разработки
pip install -e ".[dev]"# Запуск всех тестов
pytest
# Запуск с подробным выводом
pytest -vv
# Запуск конкретного теста
pytest tests/test_sync.py::TestSyncFPA::test_get_regions

📄 Лицензия

MIT. Подробности см. в файле LICENSE.

🔗 Полезные ссылки

• PyPI Package
• Официальный сайт ФИАС
• Swagger UI FIAS Public Service