An asynchronous Python client for the Yandex Geocoder API.
- Async API based on
httpx2 - Forward and reverse geocoding
- Pydantic-based request and response validation
- Typed request parameters
- Custom
AsyncClientsupport - Structured exceptions for API and network errors
- Domain models independent from the raw API response
pip install yandex-geocoderfrom yandex_geocoder import AsyncYandexGeocoderClient
async with AsyncYandexGeocoderClient(token="YOUR_API_KEY") as client:
result = await client.geocode("Moscow, Red Square")
print(result.first)Reverse geocoding:
async with AsyncYandexGeocoderClient(token="YOUR_API_KEY") as client:
result = await client.reverse_geocode("37.6173,55.7558")
print(result.first)The client can also accept a custom httpx2.AsyncClient, which allows connection settings and other HTTP client options to be managed externally.
The SDK provides dedicated exceptions for common errors, including invalid parameters, authentication errors, rate limits, timeouts, network errors, and unexpected API responses.
API responses are validated with Pydantic DTOs and converted into immutable domain models, so application code does not need to work directly with the nested Yandex API response structure.
The main result model contains the number of found locations and a list of geocoded objects, with a convenient .first property for accessing the first result.
MIT