API Reference¶

This page provides detailed documentation for all public APIs in Yarasp.

Clients¶

YaraspClient¶

Synchronous client for accessing Yandex Schedule API.

from yarasp import YaraspClient

client = YaraspClient(**kwargs)

Parameters:

base_url (str, default: "https://api.rasp.yandex.net/v3.0") - Base URL for API requests
verbose (bool, default: False) - Enable verbose logging
safe_mode (bool, default: True) - Enable safe mode (raises error when daily limit exceeded)
daily_limit (int, default: 500) - Daily API request limit
counter_backend (str, default: "json") - Usage counter backend ("json" or "redis")
counter_storage_path (str, default: "yarasp_counter.json") - Path to JSON counter file
cache_enabled (bool, default: True) - Enable HTTP caching
cache_storage (optional) - Custom cache storage backend (hishel storage instance)
user_agent (str, default: "httpx") - User-Agent header for requests

Methods:

search(params=None, auto_paginate=True)¶

Search for routes between stations.

Parameters: - params (dict, optional) - Request parameters (from, to, date, etc.) - auto_paginate (bool, default: True) - Automatically fetch all pages - result_key (str, optional, default: "segments") - Key to extract from paginated results

Returns: List of route segments

Example:

results = client.search(params={
    "from": "c213",
    "to": "c2",
    "date": "2024-01-15"
})

schedule(params=None, auto_paginate=True)¶

Get station schedule.

Parameters: - params (dict, optional) - Request parameters (station, date, etc.) - auto_paginate (bool, default: True) - Automatically fetch all pages - result_key (str, optional, default: "schedule") - Key to extract from paginated results

Returns: List of schedule entries

Example:

schedule = client.schedule(params={
    "station": "s9600213",
    "date": "2024-01-15"
})

thread(params=None)¶

Get route thread information.

Parameters: - params (dict, optional) - Request parameters (uid, etc.)

Returns: Thread information dictionary

Example:

thread_info = client.thread(params={"uid": "12345"})

nearest_stations(params=None, auto_paginate=True)¶

Find nearest stations by coordinates.

Parameters: - params (dict, optional) - Request parameters (lat, lng, distance, etc.) - auto_paginate (bool, default: True) - Automatically fetch all pages - result_key (str, optional, default: "stations") - Key to extract from paginated results

Returns: List of station information

Example:

stations = client.nearest_stations(params={
    "lat": 55.7558,
    "lng": 37.6173,
    "distance": 50
})

nearest_settlement(params=None)¶

Find nearest settlement by coordinates.

Parameters: - params (dict, optional) - Request parameters (lat, lng, etc.)

Returns: Settlement information dictionary

Example:

settlement = client.nearest_settlement(params={
    "lat": 55.7558,
    "lng": 37.6173
})

carrier(params=None)¶

Get carrier information.

Parameters: - params (dict, optional) - Request parameters (code, etc.)

Returns: Carrier information dictionary

Example:

carrier_info = client.carrier(params={"code": "SU"})

stations_list(params=None)¶

Get list of stations.

Parameters: - params (dict, optional) - Request parameters

Returns: List of stations

Example:

stations = client.stations_list()

copyright(params=None)¶

Get copyright information.

Parameters: - params (dict, optional) - Request parameters

Returns: Copyright information dictionary

Example:

copyright_info = client.copyright()

get(endpoint, params=None, auto_paginate=False, result_key=None)¶

Generic method to call any API endpoint.

Parameters: - endpoint (str) - API endpoint path - params (dict, optional) - Request parameters - auto_paginate (bool, default: False) - Automatically fetch all pages - result_key (str, optional) - Key to extract from paginated results

Returns: API response (list if paginated, dict otherwise)

Example:

result = client.get("custom/endpoint", params={"param": "value"})

is_from_cache()¶

Check if the last response was retrieved from cache.

Returns: bool - True if last response was from cache, False otherwise

Example:

client.search(params={"from": "c213", "to": "c2"})
if client.is_from_cache():
    print("Served from cache!")

AsyncYaraspClient¶

Asynchronous client for accessing Yandex Schedule API.

from yarasp import AsyncYaraspClient

client = AsyncYaraspClient(**kwargs)

Parameters: Same as YaraspClient

Methods: All methods from YaraspClient, but they are async and must be awaited.

Example:

import asyncio
from yarasp import AsyncYaraspClient

async def main():
    client = AsyncYaraspClient()
    results = await client.search(params={
        "from": "c213",
        "to": "c2",
        "date": "2024-01-15"
    })
    print(f"Found {len(results)} routes")

asyncio.run(main())

Utilities¶

JSONUsageCounter¶

Counter for tracking API key usage stored in a JSON file.

from yarasp import JSONUsageCounter

counter = JSONUsageCounter(file_path="yarasp_counter.json")

Methods:

get_count()¶

Get the current usage count for today.

Returns: int - Number of API requests made today

Example:

count = counter.get_count()
print(f"Made {count} API requests today")

increment()¶

Increment the usage counter for today.

Returns: int - Updated count after incrementing

Example:

count = counter.increment()
print(f"Usage count: {count}")

Constants¶

Environment Variables¶

YARASP_API_KEY (required) - API key for Yandex Schedule API
YARASP_API_DAILY_LIMIT (optional, default: 500) - Daily request limit
YARASP_SAFE_MODE (optional, default: 1) - Enable safe mode (1 or 0)

Exceptions¶

RuntimeError¶

Raised when: - API key is not set in environment variables - Daily API limit is exceeded (when safe mode is enabled)

NotImplementedError¶

Raised when trying to use Redis counter backend (not yet implemented).

ValueError¶

Raised when unsupported counter backend is specified.

Type Hints¶

Yarasp includes type hints for better IDE support and static type checking.

from yarasp import YaraspClient
from typing import List, Dict, Any

client: YaraspClient = YaraspClient()
results: List[Dict[str, Any]] = client.search(params={"from": "c213", "to": "c2"})