# Otodom Search API Documentation

Scrappa's `GET /api/otodom/search` endpoint is the Otodom Search API documentation page for developers who need Polish property listings as structured JSON instead of building their own scraper.

## Endpoint reference for Otodom search

Use this endpoint to search apartments, houses, rooms, plots and commercial premises for sale or rent anywhere in Poland. The request takes a `transaction`, an `estate_slug`, a `geo_path` from the Otodom locations endpoint, and optional price, area, room-count, amenity, owner-type, sort and distance filters, plus `page` and `limit`.

## What the Otodom search response returns

Each listing returns its full field set: `id`, `slug`, `title`, `href`, `estate`, `transaction`, prices (`totalPrice`, `rentPrice`, `pricePerSquareMeter`, `priceFromPerSquareMeter`), `areaInSquareMeters`, `roomsNumber`, `floorNumber`, owner and agency flags, publication timestamps, tags, location, development grouping (`developmentId`, `developmentTitle`, `developmentUrl`) and image URLs. The response also carries pagination (`total_items`, `total_pages`, `current_page`, `items_per_page`), the resolved location chain and `result_count` for filter read-back.

## How this differs from an Otodom scraper build

Otodom publishes no public API and serves filtered search only from server-rendered page state; its GraphQL endpoint accepts no filters and answers with the entire national corpus. This endpoint performs that translation for you, so your application never has to maintain a browser, a proxy pool or a state parser.

## Otodom search API use cases

Proptech products can run repeatable supply feeds for Polish cities, counties, districts and residential quarters. Market analysts can compare asking prices and availability across the whole country by combining the search endpoint with the count endpoint. Alerting tools can poll the same filtered search on a schedule and trigger on newly published listings.

For cross-portal coverage, query Otodom beside other real estate APIs and deduplicate by address, coordinates, listing URL and price.

## When to pair this endpoint with the other Otodom endpoints

Use `GET /api/otodom/locations` first to resolve a place name into the `geo_path` this endpoint requires. Follow a result `id` into `GET /api/otodom/property` for the full description, characteristics and agency data. Use `GET /api/otodom/development` when an item carries a `developmentUrl`, and `GET /api/otodom/count` when you need a total without paging through results.

## Related Otodom endpoints

- `GET /api/otodom/locations` — resolve a place name to a `geo_path`
- `GET /api/otodom/property` — full detail for one listing id
- `GET /api/otodom/development` — investment/development detail with per-unit pricing
- `GET /api/otodom/count` — facet totals for a filter set

- **Documentation:** [https://scrappa.co/docs/otodom-api/otodom_search](https://scrappa.co/docs/otodom-api/otodom_search)
- **API group:** Otodom API
- **Endpoint:** `GET https://scrappa.co/api/otodom/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction` | string | Yes | sprzedaz (sale) or wynajem (rent). |
| `estate_slug` | string | Yes | Estate slug, e.g. mieszkanie, kawalerka, dom, pokoj, dzialka, mieszkanie,rynek-pierwotny. |
| `geo_path` | string | Yes | 2 to 6 slash-separated segments from the locations endpoint. |
| `price_min` | integer | No | Minimum price. |
| `price_max` | integer | No | Maximum price. |
| `rooms_number[]` | array | No | Room counts: ONE, TWO, THREE, FOUR, FIVE, SIX_OR_MORE. |
| `owner_type` | string | No | DEVELOPER, PRIVATE or AGENCY. |
| `limit` | integer | No | Items per page, up to 72. |
| `page` | integer | No | Page number. |
| `has_discount` | boolean | No | Only true is supported. Omit it for listings both with and without a discount. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/otodom/search?transaction=sprzedaz&estate_slug=mieszkanie%2Crynek-pierwotny&geo_path=mazowieckie%2Fwarszawa%2Fwarszawa%2Fwarszawa&limit=5"
```

## Example response

```json
{
    "success": true,
    "data": {
        "items": [
            {
                "id": "64629218",
                "slug": "mieszkanie-3-pokojowe-warszawa-ID4nb0K",
                "title": "Mieszkanie 3 pokojowe, Warszawa",
                "estate": "FLAT",
                "transaction": "SELL",
                "totalPrice": {
                    "value": 899000,
                    "currency": "PLN"
                },
                "areaInSquareMeters": 68.5,
                "roomsNumber": "THREE",
                "developmentId": null,
                "images": [
                    "https://cdn.otodom.pl/asset/example/image;s=655x491;q=80"
                ]
            }
        ],
        "pagination": {
            "total_items": 20226,
            "total_pages": 281,
            "current_page": 1,
            "items_per_page": 72
        },
        "result_count": 20226
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
|  | Error | The geo path or estate slug was rejected. |
|  | Error | Otodom could not be reached. This response is not billed. |

## Frequently asked questions

### How do I find a geo_path?

Call the Otodom locations endpoint with a place name and use the `id` of the match you want.

### Why is my result count much larger than I expected?

An unrecognized estate slug silently returns the nationwide feed. Every supported slug is listed in the endpoint reference.

### Is a request billed when it fails?

No. Failed requests return an `error` object and are never charged.

### Why can I request page 99999?

Otodom clamps a page past the end rather than erroring. The response reports `page_clamped` with the page actually served.

### Are image files downloaded?

No. Only image URLs are returned, which is cheaper and lets you choose any resolution.

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)