### Development Setup and Linters

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

This section provides commands for setting up the project for development, including cloning the repository, installing dependencies with development extras, and installing pre-commit hooks. It also shows commands for running tests and code quality checks using tools like black, pylint, and mypy.

```bash
git clone https://github.com/Eapwrk/xmlriver-pro.git
cd xmlriver-pro
pip install -e ".[dev]"
pre-commit install

pytest
black xmlriver_pro tests
pylint xmlriver_pro
mypy xmlriver_pro
```

--------------------------------

### Install XMLRiver Pro Python Client

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/llms.txt

Instructions for installing the XMLRiver Pro Python client using pip. It covers installation from GitHub, including a specific version, and how to check the installed version.

```bash
# From GitHub (recommended)
pip install git+https://github.com/Eapwrk/xmlriver-pro.git

# Specific version
pip install git+https://github.com/Eapwrk/xmlriver-pro.git@v1.0.2

# Check version
python -c "import xmlriver_pro; print(xmlriver_pro.__version__)"
```

--------------------------------

### Install XMLRiver Pro using pip

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/README.md

Installs the XMLRiver Pro library from GitHub. Supports installation of the latest version or a specific tagged version using pip.

```bash
# Latest version
pip install git+https://github.com/Eapwrk/xmlriver-pro.git

# Specific version
pip install git+https://github.com/Eapwrk/xmlriver-pro.git@v1.0.2
```

--------------------------------

### Install XMLRiver Pro from GitHub

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

Install the XMLRiver Pro library directly from its GitHub repository using pip. This command allows for installing the latest version, a specific version using a tag, or upgrading an existing installation.

```bash
pip install git+https://github.com/Eapwrk/xmlriver-pro.git

pip install git+https://github.com/Eapwrk/xmlriver-pro.git@v1.0.1

pip install --upgrade git+https://github.com/Eapwrk/xmlriver-pro.git
```

--------------------------------

### Install XMLRiver Pro from PyPI

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

Install the XMLRiver Pro library from the Python Package Index (PyPI). This method is suitable if the package is published on PyPI, allowing installation of the latest version, a specific version, or upgrading an existing installation.

```bash
pip install xmlriver-pro

pip install xmlriver-pro==1.0.1

pip install --upgrade xmlriver-pro
```

--------------------------------

### Install XMLRiver Pro for Development

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

Set up the XMLRiver Pro library for development by cloning the repository and installing it in editable mode. This allows for direct code modifications and testing.

```bash
git clone https://github.com/Eapwrk/xmlriver-pro.git
cd xmlriver-pro
pip install -e .
```

--------------------------------

### Install XMLRiver Pro from GitHub using Pip

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/versioning.md

Installs the XMLRiver Pro package directly from its GitHub repository using pip. Supports installing the latest version, a specific version using a tag, or upgrading to the latest version.

```bash
# Latest version
pip install git+https://github.com/Eapwrk/xmlriver-pro.git

# Specific version
pip install git+https://github.com/Eapwrk/xmlriver-pro.git@v1.0.2

# Update to latest
pip install --upgrade git+https://github.com/Eapwrk/xmlriver-pro.git
```

--------------------------------

### Asynchronous Google Client with xmlriver-pro for Parallel Searches

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Demonstrates the usage of the `AsyncGoogleClient` for performing asynchronous and parallel Google searches using Python's `asyncio`. It covers single searches, parallel execution of multiple search queries using `asyncio.gather`, and specific asynchronous search methods for news, images, maps, and ads. The example utilizes a context manager for session management and includes proper import statements for necessary modules and types.

```python
import asyncio
from xmlriver_pro import AsyncGoogleClient
from xmlriver_pro.core.types import SearchType, TimeFilter, DeviceType

async def async_search_example():
    # Use context manager for automatic session cleanup
    async with AsyncGoogleClient(
        user_id=123,
        api_key="your_api_key_here",
        timeout=60
    ) as google:

        # Single async search
        results = await google.search(
            query="python asyncio tutorial",
            search_type=SearchType.ORGANIC,
            num_results=10,
            device=DeviceType.DESKTOP
        )

        print(f"Found {results.total_results} results")
        for result in results.results:
            print(f"{result.rank}. {result.title}")

        # Parallel searches with asyncio.gather
        queries = [
            "machine learning",
            "data science",
            "artificial intelligence",
            "deep learning"
        ]

        tasks = [google.search(q) for q in queries]
        all_results = await asyncio.gather(*tasks)

        for query, result in zip(queries, all_results):
            print(f"{query}: {result.total_results} results")

        # Async news search
        news = await google.search_news(
            query="tech news",
            num_results=10,
            time_filter=TimeFilter.LAST_DAY
        )

        # Async image search
        images = await google.search_images(
            query="python logo",
            num_results=20,
            size="large",
            color="blue"
        )

        # Async maps search
        maps = await google.search_maps(
            query="restaurants",
            coords=(40.7128, -74.0060),  # New York
            zoom=13,
            num_results=15
        )

        # Async ads retrieval
        ads = await google.get_ads(query="web hosting")

        return all_results

# Run async function
results = asyncio.run(async_search_example())
```

--------------------------------

### Check XMLRiver Pro Version

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

Verify the installed version of the XMLRiver Pro library by running a Python command. This helps in confirming the correct installation and the version being used.

```python
python -c "import xmlriver_pro; print(xmlriver_pro.__version__)"
```

--------------------------------

### Get Google API Limits and Recommendations using Python

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Fetches and displays API limits (concurrent streams, timeout, daily limits) and recommendations from the Google API. Requires an initialized GoogleClient object.

```python
limits = google.get_api_limits()
print(f"Max concurrent streams: {limits['max_concurrent_streams']}")
print(f"Recommended timeout: {limits['default_timeout']} seconds")
print(f"Typical response time: {limits['typical_response_time']}")
print("Daily limits:")
for system, limit in limits['daily_limits'].items():
    print(f"  {system}: {limit:,} requests/day")
print("\nRecommendations:")
for key, value in limits['recommendations'].items():
    print(f"  {key}: {value}")
```

--------------------------------

### Check XMLRiver Pro Version

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/llms.txt

Python command to check the currently installed version of the XMLRiver Pro library. This is useful for verifying installation and compatibility.

```python
import xmlriver_pro
print(xmlriver_pro.__version__)
```

--------------------------------

### Configure Client with Timeout

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

This example illustrates how to instantiate a Google client with a custom timeout value. Setting a higher timeout, such as 60 seconds, is recommended for reliability to prevent losing responses due to premature request termination.

```python
# Используйте таймаут 60 секунд для надежности
google = GoogleClient(user_id=123, api_key="key", timeout=60)

# При низком таймауте есть риск потерять ответы
# Деньги за запрос снимаются, но результат может не прийти
```

--------------------------------

### Check XMLRiver Pro Installed Version

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/versioning.md

A Python one-liner command to quickly check the currently installed version of the XMLRiver Pro package. It imports the package and prints the `__version__` attribute.

```python
import xmlriver_pro; print(xmlriver_pro.__version__)
```

--------------------------------

### Basic Google Search with XMLRiver Pro

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/README.md

Demonstrates basic usage of the GoogleClient from the xmlriver_pro library to perform a search query and access total results. Requires API key and user ID.

```python
from xmlriver_pro import GoogleClient, YandexClient

google = GoogleClient(user_id=123, api_key="your_key")
results = google.search("python programming")
print(f"Found: {results.total_results} results")
```

--------------------------------

### Run Pytest Tests

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

This bash script outlines various ways to execute tests using the pytest framework. It includes commands for running all tests, running tests with code coverage, running specific test files, and running tests with verbose output.

```bash
# Запуск всех тестов
pytest

# Запуск с покрытием
pytest --cov=xmlriver_pro

# Запуск конкретных тестов
pytest tests/test_google.py
pytest tests/test_yandex.py

# Запуск с детальным выводом
pytest -v
```

--------------------------------

### Google Organic Search with XMLRiver Pro

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Demonstrates how to perform organic Google searches using the GoogleClient. Supports features like pagination, device selection, time filters, and handling search results. Requires user_id and api_key for initialization.

```python
from xmlriver_pro import GoogleClient
from xmlriver_pro.core.types import DeviceType, TimeFilter

# Initialize client
google = GoogleClient(user_id=123, api_key="your_api_key_here")

# Basic search
try:
    results = google.search(
        query="python programming tutorial",
        groupby=10,  # Results per page (max 10)
        page=1,      # Page number
        device=DeviceType.DESKTOP
    )

    print(f"Total results: {results.total_results}")
    print(f"Query: {results.query}")

    for result in results.results:
        print(f"Rank {result.rank}: {result.title}")
        print(f"URL: {result.url}")
        print(f"Snippet: {result.snippet}")
        if result.stars:
            print(f"Rating: {result.stars} stars")
        if result.sitelinks:
            print(f"Sitelinks: {len(result.sitelinks)}")
        print()

except Exception as e:
    print(f"Search failed: {e}")

# Search with time filter
recent_results = google.search_with_time_filter(
    query="AI news",
    time_filter=TimeFilter.LAST_WEEK
)

# Search without autocorrection
exact_results = google.search_without_correction(query="programing")

# Search with keyword highlighting
highlighted = google.search_with_highlights(query="machine learning")
```

--------------------------------

### Create Release using Python Script

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/versioning.md

This script automates the creation of a new release by performing necessary checks and updating version information. The target release version is provided as a command-line argument.

```bash
python create_release.py 1.1.0
```

--------------------------------

### Synchronous Search with XMLRiver Pro

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

Demonstrates how to perform synchronous organic searches on Google and Yandex using the XMLRiver Pro library. It shows the initialization of client objects with user ID and API key, and retrieving search results.

```python
from xmlriver_pro import GoogleClient, YandexClient

# Инициализация клиентов
google = GoogleClient(user_id=123, api_key="your_google_key")
yandex = YandexClient(user_id=123, api_key="your_yandex_key")

# Органический поиск
google_results = google.search("python programming")
yandex_results = yandex.search("программирование на python")

# Результаты поиска
google_count = google_results.total_results
yandex_count = yandex_results.total_results
```

--------------------------------

### Asynchronous Search with XMLRiver Pro

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

Illustrates how to perform asynchronous searches on Google and Yandex using the AsyncGoogleClient and AsyncYandexClient from XMLRiver Pro. It utilizes `async with` for client management and `asyncio.run` to execute the asynchronous main function.

```python
import asyncio
from xmlriver_pro import AsyncGoogleClient, AsyncYandexClient

async def main():
    # Google поиск
    async with AsyncGoogleClient(user_id=123, api_key="your_google_key") as google:
        results = await google.search("python programming")
        print(f"Google: {results.total_results} результатов")
    
    # Yandex поиск
    async with AsyncYandexClient(user_id=123, api_key="your_yandex_key") as yandex:
        results = await yandex.search("программирование на python")
        print(f"Yandex: {results.total_results} результатов")

# Запуск
asyncio.run(main())
```

--------------------------------

### Parallel Asynchronous Searches with XMLRiver Pro

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

Demonstrates how to execute multiple Google searches concurrently using `asyncio.gather` and the `AsyncGoogleClient`. This approach improves efficiency by performing searches in parallel rather than sequentially.

```python
import asyncio
from xmlriver_pro import AsyncGoogleClient

async def parallel_search():
    async with AsyncGoogleClient(user_id=123, api_key="your_key") as google:
        # Создаем задачи для параллельного выполнения
        tasks = [
            google.search("python programming"),
            google.search("machine learning"),
            google.search("data science")
        ]
        
        # Выполняем все задачи параллельно
        results = await asyncio.gather(*tasks)
        
        for i, result in enumerate(results):
            print(f"Запрос {i+1}: {result.total_results} результатов")

asyncio.run(parallel_search())
```

--------------------------------

### Account Management: Balance and Cost (Python)

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Shows how to retrieve account balance and cost per 1000 requests using GoogleClient and YandexClient. The balance retrieval is consistent across clients, while cost information is system-specific. Requires 'xmlriver_pro'.

```python
from xmlriver_pro import GoogleClient, YandexClient

google = GoogleClient(user_id=123, api_key="your_api_key_here")
yandex = YandexClient(user_id=123, api_key="your_api_key_here")

# Get account balance (same for both)
try:
    balance = google.get_balance()
    print(f"Account balance: {balance} RUB")
except Exception as e:
    print(f"Failed to get balance: {e}")

# Get cost per 1000 requests (different for each system)
google_cost = google.get_cost(system="google")
yandex_cost = yandex.get_cost(system="yandex")
print(f"Google: {google_cost} RUB per 1000 requests")
print(f"Yandex: {yandex_cost} RUB per 1000 requests")
```

--------------------------------

### Google Special Blocks Initialization (Python)

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Initializes the client for accessing Google's special search blocks, which include features like the Knowledge Graph, calculators, and OneBox results. This snippet demonstrates the basic instantiation of the client.

```Python
from xmlriver_pro import GoogleSpecialBlocks

# Initialize special blocks client
special = GoogleSpecialBlocks(user_id=123, api_key="your_api_key_here")
```

--------------------------------

### Asynchronous Yandex Search with Parallel Queries (Python)

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Demonstrates how to use the AsyncYandexClient for performing single and parallel searches. It utilizes asyncio for concurrent query execution and handles potential exceptions during the process. Requires the 'xmlriver_pro' library.

```python
import asyncio
from xmlriver_pro import AsyncYandexClient
from xmlriver_pro.core.types import DeviceType

async def yandex_async_example():
    async with AsyncYandexClient(
        user_id=123,
        api_key="your_api_key_here"
    ) as yandex:

        # Single search
        results = await yandex.search(
            query="программирование на python",
            num_results=10,
            device=DeviceType.MOBILE
        )

        # Parallel multi-query search
        queries = [
            "машинное обучение",
            "искусственный интеллект",
            "анализ данных"
        ]

        tasks = [yandex.search(q) for q in queries]
        all_results = await asyncio.gather(*tasks, return_exceptions=True)

        for query, result in zip(queries, all_results):
            if isinstance(result, Exception):
                print(f"{query}: Error - {result}")
            else:
                print(f"{query}: {result.total_results} results")

        return all_results

asyncio.run(yandex_async_example())
```

--------------------------------

### Update Project Version using Python Script

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/versioning.md

This script updates the version number across multiple project files, including `pyproject.toml`, `setup.py`, and `__init__.py`. It ensures version consistency throughout the project. The new version number is passed as a command-line argument.

```bash
python update_version.py 1.1.0
```

--------------------------------

### Format Google API Responses using Xmlriver-Pro in Python

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Shows how to format various Google API responses (search, news, images, maps, ads) using utility functions from `xmlriver_pro.utils`. This allows for consistent and clean data presentation. Requires initialized client objects for each Google service.

```python
from xmlriver_pro import GoogleClient
from xmlriver_pro.utils import (
    format_search_result,
    format_ads_result,
    format_news_result,
    format_image_result,
    format_map_result
)

google = GoogleClient(user_id=123, api_key="your_api_key_here")

# Get and format search results
results = google.search("python programming")

for result in results.results:
    formatted = format_search_result(result)
    print(formatted)
    # Output: Formatted dictionary with clean structure

# Format individual result types
from xmlriver_pro import GoogleNews, GoogleImages, GoogleMaps, GoogleAds

# Format news
news_client = GoogleNews(user_id=123, api_key="key")
news_results = news_client.search_news("tech news")
for news in news_results.results:
    formatted_news = format_news_result(news)
    print(formatted_news)

# Format images
images_client = GoogleImages(user_id=123, api_key="key")
image_results = images_client.search_images("python logo")
for img in image_results.results:
    formatted_img = format_image_result(img)
    print(formatted_img)

# Format maps
maps_client = GoogleMaps(user_id=123, api_key="key")
map_results = maps_client.search_maps("cafe", zoom=14, coords=(55.7558, 37.6176))
for place in map_results.results:
    formatted_place = format_map_result(place)
    print(formatted_place)

# Format ads
ads_client = GoogleAds(user_id=123, api_key="key")
ads_response = ads_client.get_ads("hosting")
for ad in ads_response.top_ads:
    formatted_ad = format_ads_result(ad)
    print(formatted_ad)
```

--------------------------------

### Synchronous Google Searches and Data Retrieval with xmlriver-pro

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Demonstrates how to use the `special` object from xmlriver-pro to perform various synchronous Google searches and data retrievals. This includes fetching OneBox documents, Knowledge Graph information, related searches, calculator results, translations, weather, currency conversions, and time in a specific location. Error handling is included for the OneBox document fetch.

```python
try:
    onebox_docs = special.get_onebox_documents(
        query="python programming",
        types=["organic", "video", "images", "news"]
    )

    for doc in onebox_docs:
        print(f"Type: {doc.content_type}")
        print(f"Title: {doc.title}")
        print(f"URL: {doc.url}")
        print(f"Snippet: {doc.snippet}")
        print(f"Extra: {doc.additional_data}\n")

except Exception as e:
    print(f"OneBox fetch failed: {e}")

# Get Knowledge Graph
kg = special.get_knowledge_graph(query="Python programming language")
if kg:
    print(f"Entity: {kg.entity_name}")
    print(f"Description: {kg.description}")
    print(f"Image: {kg.image_url}")
    print(f"Info: {kg.additional_info}")

# Get related searches
related = special.get_related_searches(query="machine learning")
for search in related:
    print(f"Related: {search.query} -> {search.url}")

# Calculator
calc_result = special.get_calculator(query="2 + 2 * 5")
if calc_result:
    print(f"Expression: {calc_result['expression']}")
    print(f"Result: {calc_result['result']}")

# Translator
translation = special.get_translator(query="hello world")
if translation:
    print(f"Original: {translation['original_text']}")
    print(f"Translation: {translation['translation']}")

# Weather
weather = special.get_weather(query="weather London")
if weather:
    print(f"Location: {weather['location']}")
    print(f"Info: {weather['weather_info']}")

# Currency converter
conversion = special.get_currency_converter(query="100 USD to EUR")
if conversion:
    print(f"Query: {conversion['conversion_query']}")
    print(f"Result: {conversion['result']}")

# Time in location
time_info = special.get_time(query="time in Tokyo")
if time_info:
    print(f"Location: {time_info['location_query']}")
    print(f"Time: {time_info['time_info']}")
```

--------------------------------

### Google Maps Search with Coordinates and Place Details (Python)

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Searches for locations on Google Maps using coordinates, zoom levels, and place details. It initializes a maps client and demonstrates searching with specific coordinates, nearby searches, and convenience methods for common place types like restaurants and hotels.

```Python
from xmlriver_pro import GoogleMaps
from xmlriver_pro.core.types import Coords

# Initialize maps client
maps = GoogleMaps(user_id=123, api_key="your_api_key_here")

# Search with coordinates (latitude, longitude)
moscow_coords: Coords = (55.7558, 37.6176)

try:
    results = maps.search_maps(
        query="кафе",
        zoom=14,  # 1-15
        coords=moscow_coords,
        count=20,  # 5-50
        lr="ru"
    )

    for place in results.results:
        print(f"Name: {place.title}")
        print(f"Type: {place.type}")
        print(f"Address: {place.address}")
        print(f"Rating: {place.stars} ({place.count_reviews} reviews)")
        print(f"Phone: {place.phone}")
        print(f"Location: {place.latitude}, {place.longitude}")
        print(f"Place ID: {place.place_id}")
        print(f"Price: {place.price}")
        if place.accessibility:
            print("Accessible: Yes")
        print()

except Exception as e:
    print(f"Maps search failed: {e}")

# Search nearby with automatic zoom
nearby = maps.search_nearby(
    query="restaurant",
    coords=moscow_coords,
    radius=1000  # meters
)

# Convenience methods for common searches
restaurants = maps.search_restaurants(coords=moscow_coords)
hotels = maps.search_hotels(coords=moscow_coords, query="отель")
gas_stations = maps.search_gas_stations(coords=moscow_coords)
pharmacies = maps.search_pharmacies(coords=moscow_coords)
```

--------------------------------

### Google Images Search with Filters (Python)

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Searches for images on Google with options to filter by size, color, type, and usage rights. It initializes an images client, performs a basic search, and then demonstrates filtered searches. Handles potential exceptions during the search process.

```Python
from xmlriver_pro import GoogleImages

# Initialize images client
images = GoogleImages(user_id=123, api_key="your_api_key_here")

# Basic image search
try:
    results = images.search_images(
        query="python logo",
        count=50,  # Max 50 images
        page=1
    )

    for img in results.results:
        print(f"Rank: {img.rank}")
        print(f"Title: {img.title}")
        print(f"Image URL: {img.img_url}")
        print(f"Source: {img.url}")
        print(f"Display: {img.display_link}")
        print(f"Size: {img.original_width}x{img.original_height}\n")

except Exception as e:
    print(f"Image search failed: {e}")

# Search by size
large_images = images.search_images_by_size(
    query="nature landscape",
    size="large"  # small, medium, large, xlarge
)

# Search by color
blue_images = images.search_images_by_color(
    query="ocean",
    color="blue"  # any, color, grayscale, transparent, red, orange, etc.
)

# Search by type
photos = images.search_images_by_type(
    query="animals",
    image_type="photo"  # any, face, photo, clipart, lineart, animated
)

# Search by usage rights
free_images = images.search_images_by_usage_rights(
    query="technology icons",
    usage_rights="cc_publicdomain"  # Creative Commons filters
)

# Get suggested searches
suggestions = images.get_suggested_searches(query="python")
print(f"Suggested: {suggestions}")
```

--------------------------------

### Update XMLRiver Pro to Latest Version

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

Update the XMLRiver Pro library to the most recent version available on PyPI using pip. This ensures you have the latest features and bug fixes.

```bash
pip install --upgrade xmlriver-pro
```

--------------------------------

### Yandex Search: Basic and Filtered Searches in Python

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/examples.md

Demonstrates basic search queries with parameters like grouping, pagination, region, language, and device. It also shows how to filter search results by time, search for exact phrases, exclude words, and search within specific fields like titles or URLs.

```python
from xmlriver_pro import DeviceType

results = search.search(
    query="программирование на python",
    groupby=10,
    page=0,  # Yandex использует 0-based пагинацию
    lr=213,  # Москва
    lang="ru",
    domain="ru",
    device=DeviceType.DESKTOP
)

results = search.search_with_time_filter(
    query="python новости",
    within=77  # За сутки
)

results = search.search_with_highlights("python programming")

results = search.search_with_filter("python programming")

results = search.search_site("python.org", "tutorial")

results = search.search_exact_phrase("программирование на python")

results = search.search_exclude_words(
    "python programming",
    ["java", "c++", "javascript"]
)

results = search.search_in_title("python")

results = search.search_in_url("python.org")

results = search.search_by_region("python", 213)  # Москва

results = search.search_by_language("python", "ru")

results = search.search_by_domain("python", "ru")

results = search.search_file_type("python tutorial", "pdf")

results = search.search_define("python programming")

results = search.search_related("https://python.org")
```

--------------------------------

### Check Indexing and Domain Trust

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

This code shows how to verify if a given URL is indexed by Google and if a domain is considered trusted. It utilizes methods like `check_indexing()` and `is_trust_domain()` from a Google client object.

```python
is_indexed = google.check_indexing("https://python.org")
is_trusted = google.is_trust_domain("python.org")
```

--------------------------------

### Retrieve API Costs and Limits

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/README.md

This snippet demonstrates how to fetch cost information for Google and Yandex searches and retrieve API limits for concurrent streams and daily requests. It assumes the existence of a client object with methods like `get_cost()` and `get_api_limits()`.

```python
google_cost = google.get_cost()  # Стоимость Google запросов
yandex_cost = yandex.get_cost()  # Стоимость Yandex запросов

limits = google.get_api_limits()
print(f"Максимум потоков: {limits['max_concurrent_streams']}")
print(f"Дневной лимит Google: {limits['daily_limits']['google']:,} запросов")
print(f"Дневной лимит Yandex: {limits['daily_limits']['yandex']:,} запросов")
```

--------------------------------

### Yandex Organic Search with XMLRiver Pro

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Shows how to perform organic Yandex searches using the YandexClient. Supports regional settings, language options, advanced operators like site search, exact phrase matching, word exclusion, and searching within titles or URLs. Requires user_id and api_key.

```python
from xmlriver_pro import YandexClient
from xmlriver_pro.core.types import DeviceType, OSType

# Initialize Yandex client
yandex = YandexClient(user_id=123, api_key="your_api_key_here")

# Basic Yandex search
try:
    results = yandex.search(
        query="программирование на python",
        groupby=10,
        page=0,  # Yandex pages start from 0
        lr=213,  # Region: Moscow
        lang="ru",
        domain="ru"
    )

    for result in results.results:
        print(f"{result.rank}. {result.title}")
        print(f"   {result.url}")

except Exception as e:
    print(f"Error: {e}")

# Search within specific site
site_results = yandex.search_site(
    site="python.org",
    query="tutorials"
)

# Exact phrase search
exact_results = yandex.search_exact_phrase("машинное обучение")

# Search with word exclusion
filtered = yandex.search_exclude_words(
    query="python",
    exclude_words=["snake", "animal"]
)

# Search in titles only
title_results = yandex.search_in_title(query="python guide")

# Search in URLs
url_results = yandex.search_in_url(query="docs")
```

--------------------------------

### Google News Search with XMLRiver Pro

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Illustrates how to search Google News using the GoogleNews client. Supports time-based filters, custom date ranges, and country selection. Provides convenience methods for common time periods. Requires user_id and api_key.

```python
from xmlriver_pro import GoogleNews
from xmlriver_pro.core.types import TimeFilter

# Initialize news client
news = GoogleNews(user_id=123, api_key="your_api_key_here")

# Search news with time filter
try:
    results = news.search_news(
        query="artificial intelligence breakthrough",
        time_filter=TimeFilter.LAST_DAY,
        groupby=10,
        country=840  # USA
    )

    for article in results.results:
        print(f"Title: {article.title}")
        print(f"URL: {article.url}")
        print(f"Published: {article.pub_date}")
        print(f"Media: {article.media}")
        print(f"Snippet: {article.snippet}\n")

except Exception as e:
    print(f"News search failed: {e}")

# Convenience methods for different time periods
last_hour = news.search_news_last_hour("breaking news")
last_day = news.search_news_last_day("tech news")
last_week = news.search_news_last_week("python release")
last_month = news.search_news_last_month("AI developments")

# Custom date range (MM/DD/YYYY format)
custom_period = news.search_news_custom_period(
    query="climate change",
    start_date="01/01/2024",
    end_date="12/31/2024"
)
```

--------------------------------

### Yandex Ads: Retrieving and Analyzing Ads in Python

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/examples.md

This snippet demonstrates how to use the YandexAds wrapper to retrieve advertising blocks. It includes functions for general ad retrieval, filtering by region, language, and domain, as well as accessing ad statistics.

```python
from xmlriver_pro import YandexAds

ads = YandexAds(user_id=123, api_key="your_key")

# Получение рекламных блоков
ads_response = ads.get_ads("программирование python")

# Поиск по региону
moscow_ads = ads.get_ads_by_region("python", 213)

# Поиск по языку
russian_ads = ads.get_ads_by_language("python", "ru")

# Поиск по домену
ru_ads = ads.get_ads_by_domain("python", "ru")

# Статистика
stats = ads.get_ads_stats("python")
print(f"Верхние: {stats['top_ads_count']}")
print(f"Нижние: {stats['bottom_ads_count']}")
print(f"Всего: {stats['total_ads_count']}")
```

--------------------------------

### Analyze Competitors Across Search Engines (Python)

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/examples.md

This Python function analyzes competitors for a given domain based on a list of keywords. It queries search engines like Google and Yandex, identifying competing URLs, their titles, and ranks. The function returns a structured analysis of competitors for each keyword and engine. It requires `GoogleClient` and `YandexClient`.

```python
def analyze_competitors(domain, keywords, search_engines=["google", "yandex"]):
    """Анализ конкурентов по ключевым словам"""
    analysis = {}
    
    if "google" in search_engines:
        google = GoogleClient(user_id=123, api_key="your_google_key")
        analysis["google"] = {}
        
        for keyword in keywords:
            try:
                results = google.search(keyword)
                competitors = []
                for result in results.results:
                    if domain not in result.url:
                        competitors.append({
                            "url": result.url,
                            "title": result.title,
                            "rank": result.rank
                        })
                analysis["google"][keyword] = competitors
            except Exception as e:
                analysis["google"][keyword] = f"Ошибка: {e}"
    
    if "yandex" in search_engines:
        yandex = YandexClient(user_id=123, api_key="your_yandex_key")
        analysis["yandex"] = {}
        
        for keyword in keywords:
            try:
                results = yandex.search(keyword)
                competitors = []
                for result in results.results:
                    if domain not in result.url:
                        competitors.append({
                            "url": result.url,
                            "title": result.title,
                            "rank": result.rank
                        })
                analysis["yandex"][keyword] = competitors
            except Exception as e:
                analysis["yandex"][keyword] = f"Ошибка: {e}"
    
    return analysis

# Использование
domain = "python.org"
keywords = ["python programming", "python tutorial", "python documentation"]
competitors = analyze_competitors(domain, keywords)

for engine, engine_competitors in competitors.items():
    print(f"\n{engine.upper()}:")
    for keyword, keyword_competitors in engine_competitors.items():
        if isinstance(keyword_competitors, list):
            print(f"  {keyword}:")
            for competitor in keyword_competitors[:5]:  # Топ-5
                print(f"    {competitor['rank']}. {competitor['title']}")
                print(f"       {competitor['url']}")
        else:
            print(f"  {keyword}: {keyword_competitors}")
```

--------------------------------

### Validate Parameters with Xmlriver-Pro Utilities in Python

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Demonstrates the use of various validation functions from `xmlriver_pro.utils` to ensure data integrity before API calls. Includes validation for coordinates, zoom levels, URLs, queries, device types, and OS types. Handles `ValidationError` exceptions.

```python
from xmlriver_pro.utils import (
    validate_coords,
    validate_zoom,
    validate_url,
    validate_query,
    validate_device,
    validate_os
)
from xmlriver_pro.core.types import DeviceType, OSType
from xmlriver_pro.core.exceptions import ValidationError

# Validate coordinates
coords = (55.7558, 37.6176)
try:
    validate_coords(coords)
    print(f"Coordinates valid: {coords}")
except ValidationError as e:
    print(f"Invalid coordinates: {e}")

# Validate zoom level
zoom = 14
try:
    validate_zoom(zoom)
    print(f"Zoom valid: {zoom}")
except ValidationError as e:
    print(f"Invalid zoom: {e}")

# Validate URL
url = "https://python.org"
try:
    validate_url(url)
    print(f"URL valid: {url}")
except ValidationError as e:
    print(f"Invalid URL: {e}")

# Validate search query
query = "python programming"
try:
    validate_query(query)
    print(f"Query valid: {query}")
except ValidationError as e:
    print(f"Invalid query: {e}")

# Validate device type
device = DeviceType.MOBILE
try:
    validate_device(device)
    print(f"Device valid: {device.value}")
except ValidationError as e:
    print(f"Invalid device: {e}")

# Validate OS type
os = OSType.ANDROID
try:
    validate_os(os)
    print(f"OS valid: {os.value}")
except ValidationError as e:
    print(f"Invalid OS: {e}")
```

--------------------------------

### Robust API Error Handling with Retries (Python)

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Implements a robust search function using GoogleClient that includes comprehensive error handling for various API exceptions like AuthenticationError, RateLimitError, and NetworkError. It incorporates retry logic for temporary issues and provides specific feedback for different error types. Requires 'xmlriver_pro' and 'time'.

```python
from xmlriver_pro import GoogleClient
from xmlriver_pro.core import (
    XMLRiverError,
    AuthenticationError,
    RateLimitError,
    NoResultsError,
    NetworkError,
    ValidationError,
    InsufficientFundsError,
    ServiceUnavailableError
)
import time

google = GoogleClient(user_id=123, api_key="your_api_key_here")

def robust_search(query, max_retries=3):
    """Search with comprehensive error handling and retry logic"""

    for attempt in range(max_retries):
        try:
            results = google.search(query)
            print(f"Success: {results.total_results} results")
            return results

        except AuthenticationError as e:
            # Fatal: Invalid credentials (codes 31, 42, 45)
            print(f"Authentication failed: {e.message}")
            print(f"Error code: {e.code}")
            print("Check your user_id and api_key")
            return None

        except RateLimitError as e:
            # Temporary: Too many concurrent requests (codes 110, 111, 115)
            print(f"Rate limit hit: {e.message}")
            wait_time = 5 * (attempt + 1)
            print(f"Waiting {wait_time} seconds before retry...")
            time.sleep(wait_time)
            continue

        except NoResultsError as e:
            # Normal: No search results found (code 15)
            print(f"No results for query: {query}")
            return None

        except InsufficientFundsError as e:
            # Fatal: Account balance depleted (code 200)
            print(f"Insufficient funds: {e.message}")
            print("Please recharge your account")
            return None

        except ServiceUnavailableError as e:
            # Temporary: Service maintenance (codes 101, 201)
            print(f"Service unavailable: {e.message}")
            print("Waiting 30 seconds...")
            time.sleep(30)
            continue

        except NetworkError as e:
            # Temporary: Network issues (codes 500, 202)
            print(f"Network error: {e.message}")
            print(f"Retry {attempt + 1}/{max_retries}")
            time.sleep(10)
            continue

        except ValidationError as e:
            # Fatal: Invalid parameters (codes 2, 102-108, 120, 121)
            print(f"Validation error: {e.message}")
            print(f"Error code: {e.code}")
            print("Fix query parameters")
            return None

        except XMLRiverError as e:
            # Generic API error
            print(f"API error [{e.code}]: {e.message}")
            return None

    print(f"Failed after {max_retries} retries")
    return None

# Usage
result = robust_search("python programming")
```

--------------------------------

### Google Ads Retrieval and Filtering (Python)

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

Retrieves advertising blocks from Google search results, including top and bottom ads. It allows for filtering ads by domain and checking for the presence of ads. The client can also return the count of ads and detailed statistics.

```Python
from xmlriver_pro import GoogleAds

# Initialize ads client
ads_client = GoogleAds(user_id=123, api_key="your_api_key_here")

# Get all ads
try:
    ads_response = ads_client.get_ads(
        query="buy laptop online",
        country=840,
        device="desktop"
    )

    print(f"Top ads: {len(ads_response.top_ads)}")
    for ad in ads_response.top_ads:
        print(f"Title: {ad.title}")
        print(f"URL: {ad.url}")
        print(f"Ads URL: {ad.ads_url}")
        print(f"Description: {ad.snippet}\n")

    print(f"Bottom ads: {len(ads_response.bottom_ads)}")
    for ad in ads_response.bottom_ads:
        print(f"Title: {ad.title}")
        print(f"URL: {ad.url}\n")

except Exception as e:
    print(f"Ads retrieval failed: {e}")

# Get only top ads
top_ads = ads_client.get_top_ads(query="cloud hosting")

# Get only bottom ads
bottom_ads = ads_client.get_bottom_ads(query="web hosting")

# Get all ads combined
all_ads = ads_client.get_all_ads(query="vps server")

# Check if query has ads
has_advertising = ads_client.has_ads(query="cheap domains")
print(f"Has ads: {has_advertising}")

# Get ads count
count = ads_client.count_ads(query="ssl certificate")
print(f"Total ads: {count}")

# Filter ads by domain
domain_ads = ads_client.get_ads_by_domain(
    query="hosting",
    domain="godaddy.com"
)

# Get detailed statistics
stats = ads_client.get_ads_stats(query="web development")
print(f"Stats: {stats}")
# Output: {'top_ads_count': 4, 'bottom_ads_count': 3, 'total_ads_count': 7, 'has_ads': True}
```

--------------------------------

### Monitor URL Positions Across Search Engines (Python)

Source: https://github.com/eapwrk/xmlriver-pro/blob/main/docs/examples.md

This Python function monitors the search engine positions of a given URL for a list of keywords. It supports multiple search engines like Google and Yandex, returning a dictionary of positions for each keyword and engine. Dependencies include `GoogleClient` and `YandexClient`.

```python
def monitor_positions(url, keywords, search_engines=["google", "yandex"]):
    """Мониторинг позиций URL по ключевым словам"""
    positions = {}
    
    if "google" in search_engines:
        google = GoogleClient(user_id=123, api_key="your_google_key")
        positions["google"] = {}
        
        for keyword in keywords:
            try:
                results = google.search(keyword)
                position = None
                for i, result in enumerate(results.results, 1):
                    if url in result.url:
                        position = i
                        break
                positions["google"][keyword] = position
            except Exception as e:
                positions["google"][keyword] = f"Ошибка: {e}"
    
    if "yandex" in search_engines:
        yandex = YandexClient(user_id=123, api_key="your_yandex_key")
        positions["yandex"] = {}
        
        for keyword in keywords:
            try:
                results = yandex.search(keyword)
                position = None
                for i, result in enumerate(results.results, 1):
                    if url in result.url:
                        position = i
                        break
                positions["yandex"][keyword] = position
            except Exception as e:
                positions["yandex"][keyword] = f"Ошибка: {e}"
    
    return positions

# Использование
url = "https://python.org"
keywords = ["python programming", "python tutorial", "python documentation"]
positions = monitor_positions(url, keywords)

for engine, engine_positions in positions.items():
    print(f"\n{engine.upper()}:")
    for keyword, position in engine_positions.items():
        if isinstance(position, int):
            print(f"  {keyword}: позиция {position}")
        else:
            print(f"  {keyword}: {position}")
```

--------------------------------

### Google Organic Search API

Source: https://context7.com/eapwrk/xmlriver-pro/llms.txt

This section covers the Google Organic Search API endpoint, allowing users to perform organic searches on Google with various filtering and customization options.

```APIDOC
## Google Organic Search

### Description
Perform organic Google searches with pagination, device selection, and time filters.

### Method
POST (Implicit via client method)

### Endpoint
Not directly exposed; managed by the `GoogleClient` class.

### Parameters
#### Path Parameters
None

#### Query Parameters
- **query** (string) - Required - The search query.
- **groupby** (integer) - Optional - Number of results per page (max 10).
- **page** (integer) - Optional - Page number.
- **device** (DeviceType enum) - Optional - Device type for the search (e.g., DESKTOP, MOBILE, TABLET).
- **time_filter** (TimeFilter enum) - Optional - Filter results by time (e.g., LAST_WEEK, LAST_MONTH).

### Request Example
```python
from xmlriver_pro import GoogleClient
from xmlriver_pro.core.types import DeviceType, TimeFilter

google = GoogleClient(user_id=123, api_key="your_api_key_here")
results = google.search(
    query="python programming tutorial",
    groupby=10,
    page=1,
    device=DeviceType.DESKTOP
)
```

### Response
#### Success Response (200)
- **total_results** (integer) - The total number of search results.
- **query** (string) - The original search query.
- **results** (list of objects) - A list of search result objects, each containing:
  - **rank** (integer) - The rank of the result.
  - **title** (string) - The title of the search result.
  - **url** (string) - The URL of the search result.
  - **snippet** (string) - The snippet or description of the search result.
  - **stars** (float) - The star rating, if available.
  - **sitelinks** (list) - Sitelinks associated with the result, if any.

#### Response Example
```json
{
  "total_results": 1000000,
  "query": "python programming tutorial",
  "results": [
    {
      "rank": 1,
      "title": "Python Programming Tutorial - Official Python Website",
      "url": "https://www.python.org/about/gettingstarted/",
      "snippet": "Learn Python programming from scratch with our comprehensive tutorial...",
      "stars": null,
      "sitelinks": []
    }
    // ... more results
  ]
}
```
```