Metadata-Version: 2.4
Name: immoscout-api-client
Version: 1.0.0
Summary: A thin Python client for the ImmoScout24 mobile API
Project-URL: Repository, https://github.com/libklein/immoscout-api-client
Author-email: Patrick Klein <patrick@libklein.com>
License-File: LICENSE
Keywords: api,client,immoscout24
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.10
Requires-Dist: furl>=2.1.4
Requires-Dist: rnet>=2.2.11
Description-Content-Type: text/markdown

# immoscout-api-client

A thin Python client for the ImmoScout24 mobile API.

## Installation

```bash
pip install immoscout-api-client
```

Or with uv:

```bash
uv add immoscout-api-client
```

## Usage

### Basic Example

```python
import asyncio
from immoscout_api_client import ImmoscoutAPIClient, convert_web_to_mobile

async def main():
    # Initialize the client
    client = ImmoscoutAPIClient()

    # Convert a web URL to mobile API format
    web_url = "https://www.immobilienscout24.de/Suche/de/berlin/berlin/wohnung-mieten"
    mobile_url = convert_web_to_mobile(web_url)

    # Fetch first page of search results
    results = await client.search_list(mobile_url, page=1)
    print(f"Found {results['totalResults']} properties")

    # Get details for a specific property
    listing_id = results['resultListItems'][0]['item']['id']
    details = await client.get_property_details(listing_id)
    print(f"Property title: {details['sections'][0]['title']}")

asyncio.run(main())
```

## API Reference

### `ImmoscoutAPIClient`

Main HTTP client for the ImmoScout24 API.

**Constructor:**

```python
ImmoscoutAPIClient(
    timeout: int = 30,
    impersonate: Impersonate = Impersonate.OkHttp5,
    user_agent: str = "ImmoScout24_1410_30_._"
)
```

**Methods:**

- `async search_list(mobile_url: str, page: int) -> dict`
  - Fetch a page of search results
  - Returns raw JSON response

- `async get_property_details(listing_id: int) -> dict`
  - Fetch detailed information for a specific property
  - Returns raw JSON response

### URL Utilities

- `convert_web_to_mobile(web_url: str) -> str`
  - Convert web URL to mobile API format
  - Raises `ValueError` for invalid URLs or unsupported parameters

- `get_page_url(mobile_url: str, page: int) -> str`
  - Add/update page number in mobile API URL

- `get_expose_details_url(listing_id: int | str) -> str`
  - Construct property details endpoint URL

### Exceptions

- `ImmoscoutAPIError`: Base exception for all API errors
- `ImmoscoutHTTPError`: Raised when HTTP requests fail

## License

MIT License - see LICENSE file for details
