# Gratka Property Search API Documentation Scrappa's `GET /api/gratka/search` returns Gratka property listings in Poland, for sale (`transaction=sale`, the default) or for rent (`rent`), as structured JSON. ## What you get One request returns one page of up to 35 listings and Gratka's own match count in `total`. Each listing has `id`, `url`, `title`, `price` with `price_formatted`, `price_per_m2`, `area_m2`, `rooms`, `floor_label`, a structured `address`, all `photos` as image links, plan, video and 3D flags, the start of the description, dates, a promoted flag and the `agent` company and person. Call the listing endpoint for the full record with coordinates, features and fees. ## Types `type` is one of `mieszkania` (flats, the default), `domy` (houses), `pokoje` (rooms), `lokale-uzytkowe` (commercial), `garaze` (garages) or `dzialki-grunty` (plots). Plots, garages and commercial units have no room count, so `rooms` is `null` there. Rooms (`pokoje`) are sale only on Gratka. Combined with `rent` they return `404`. ## Filters are honoured Gratka applies price, area, rooms, location and sort itself. Unknown parameters are rejected with `422` instead of being ignored, because Gratka would ignore them and return every listing. Bedrooms and bathrooms are not filterable on Gratka. They are returned per listing in the listing endpoint. `applied_filters` echoes what was sent. Rows that break a price, area or rooms filter are removed, and their number is reported in `meta.filtered_out`. A row without a price is kept, because a missing value is not a violation. If every row on a page breaks the filter, the request fails without charge. ## Location `location` takes a city, for example `warszawa` or `Kraków`, and `district` takes a district of that city, for example `mokotow`. Use the `search_params` of the location-autocomplete endpoint. A place Gratka does not know returns `404`. ## Pagination `page` is 1-based, 35 listings per page, up to page 200. `total_pages` and `has_more` describe the real result set. A page that does not exist returns `404` (`page_out_of_range`) without charge. Page 2 never contains page 1 data. ## Data quality Values pass through as sellers entered them. A few sale listings show a rent-sized price, and some listings ask for the price, so `price` is `null` there. - **Documentation:** [https://scrappa.co/docs/gratka-api/gratka_search](https://scrappa.co/docs/gratka-api/gratka_search) - **API group:** Gratka API - **Endpoint:** `GET https://scrappa.co/api/gratka/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 | | --- | --- | --- | --- | | `type` | string | No | mieszkania (default), domy, pokoje, lokale-uzytkowe, garaze or dzialki-grunty. | | `transaction` | string | No | sale (default) or rent. | | `location` | string | No | City name or slug from location-autocomplete, for example warszawa. | | `district` | string | No | District name or slug inside the city, for example mokotow. Needs location. | | `price_min` | integer | No | Minimum total price in PLN (monthly rent for rent listings). | | `price_max` | integer | No | Maximum total price in PLN (monthly rent for rent listings). | | `area_min` | integer | No | Minimum area in square metres. | | `area_max` | integer | No | Maximum area in square metres. | | `rooms` | integer | No | Exact room count: 2, 3 or 4. Flats only. | | `sort` | string | No | newest, oldest, cheap, expensive, cheap-m2, expensive-m2, rooms-few, rooms-many, small or large. Default order is most recently refreshed. | | `page` | integer | No | Result page, 1-200. 35 listings per page. | ## Example request ```bash #!/bin/bash curl -X GET \ -H "x-api-key: YOUR_API_KEY_HERE" \ "https://scrappa.co/api/gratka/search?type=mieszkania&transaction=rent&location=krakow&price_max=3000&sort=cheap" ``` ## Example response ```json { "success": true, "transaction": "rent", "type": "mieszkania", "applied_filters": { "location": "krakow", "district": null, "rooms": null, "price_min": null, "price_max": 3000, "area_min": null, "area_max": null, "sort": "cheap" }, "total": 1503, "page": 1, "per_page": 35, "total_pages": 43, "has_more": true, "listings": [ { "id": "49402269", "url": "https://gratka.pl/nieruchomosci/mieszkanie-krakow-bronowice-ojcowska/ob/49402269", "title": "mieszkanie do wynaj\u0119cia", "headline": "Mieszkanie do wynaj\u0119cia, 153 m\u00b2, 5 pokoi Krak\u00f3w Bronowice", "price": { "amount": 4900, "currency": "PLN" }, "price_formatted": "4 900 z\u0142", "price_per_m2": { "amount": 32.03, "currency": "PLN" }, "price_per_m2_formatted": "32 z\u0142/m\u00b2", "area_m2": 153, "rooms": 5, "rooms_label": "5 pokoi", "floor_label": "pi\u0119tro 1", "address": { "voivodeship": "ma\u0142opolskie", "city": "Krak\u00f3w", "district": "Bronowice", "neighbourhood": null, "street": "Ojcowska", "street_number": null, "county": null, "commune": null, "latitude": null, "longitude": null }, "photos": [ { "url": "https://d-gr.cdngr.pl/kadry/k/r/gr-ogl/aa/bb/49402269_1.jpg", "alt": "Mieszkanie do wynaj\u0119cia 153m2 Krak\u00f3w Bronowice - zdj\u0119cie 1" } ], "photo_count": 12, "plans_count": 0, "has_3d_view": false, "has_video": false, "description": "Przestronne mieszkanie w nowym budynku...", "added_at": "2026-10-26", "refreshed_at": null, "is_promoted": false, "is_development": false, "agent": { "company": { "id": 222179, "name": "Nieruchomo\u015bci Splendor", "type": "AGENCY", "address": [ "Tadeusza Ko\u015bciuszki 75/40", "30-114 Krak\u00f3w" ], "logo": "https://d-gr.cdngr.pl/kadry/k/r/gr-plogo/a4/bb/222179_1629328035.jpg" }, "person": { "name": "Iwona Franusiak", "type": "AGENT", "photo": "https://img2.staticmorizon.com.pl/thumbnail/example/200/200/2/thumbnail.jpg" } } } ], "meta": { "endpoint_family": "search", "billable": true, "attempts": 1, "filtered_out": 0 } } ``` ## Errors | Status | Error | Description | | --- | --- | --- | | 404 | Not Found | Gratka has no listing page for that type, location and transaction, or no results on that page (`not_found`). Non-billable. | | 422 | Validation Error | A query parameter is missing, unknown or unusable. Unknown parameters are rejected, never ignored. Non-billable. | | 503 | Upstream Unavailable | Gratka could not be reached after retries, answered with an error, or returned a page without the expected data (`upstream_unavailable`, `upstream_blocked`, `upstream_rejected`, `parser_drift`). Retryable and never billed. Clients are never rate limited. | ## 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)