# Gratka Listing Details API Documentation

Scrappa's `GET /api/gratka/listing` returns the full record of one Gratka listing as structured JSON.

## Input

Send the `url` that the search endpoint returns, or the listing `slug` and numeric `id` taken from it. Gratka needs the right slug: a wrong slug returns `404`.

## What you get

`price`, `price_per_m2`, `additional_costs`, `area_m2`, `rooms`, `bedrooms`, `bathrooms`, `floor`, `floors_total`, `year_built`, `market_type`, `transaction`, `property_type`, a structured `address` with `latitude` and `longitude`, the full description, `details` as labelled rows exactly as the seller entered them, `highlights`, `equipment`, `facilities`, `utilities`, `environment` with noise level and public transport, all `photos`, `plans`, `videos`, the reference number, the last change, the `agent` company and person, `similar_listings` and `advertiser_listings`.

## Missing values

A value the seller did not enter is `null`, never `0`. Bedrooms, bathrooms and additional costs are optional on Gratka and are present on only some listings. Plots and garages have no rooms.

## Privacy

Phone numbers and fax numbers are not returned.

- **Documentation:** [https://scrappa.co/docs/gratka-api/gratka_listing](https://scrappa.co/docs/gratka-api/gratka_listing)
- **API group:** Gratka API
- **Endpoint:** `GET https://scrappa.co/api/gratka/listing`

## 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 |
| --- | --- | --- | --- |
| `url` | string | No | Listing url returned by search. Send this or slug with id. |
| `slug` | string | No | Listing slug from a search url, for example mieszkanie-krakow-bronowice-ojcowska. Use with id. |
| `id` | string | No | Numeric listing id, for example 49402269. Use with slug. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/gratka/listing?url=https%3A%2F%2Fgratka.pl%2Fnieruchomosci%2Fmieszkanie-krakow-bronowice-ojcowska%2Fob%2F49402269"
```

## Example response

```json
{
    "success": true,
    "listing": {
        "id": "49402269",
        "url": "https://gratka.pl/nieruchomosci/mieszkanie-krakow-bronowice-ojcowska/ob/49402269",
        "title": "Mieszkanie na wynajem",
        "transaction": "RENT",
        "property_type": "FLAT",
        "market_type": "Rynek wt\u00f3rny",
        "price": {
            "amount": 4900,
            "currency": "PLN"
        },
        "price_formatted": "4 900 z\u0142",
        "additional_costs": null,
        "area_m2": 153,
        "rooms": 5,
        "bedrooms": 4,
        "bathrooms": 2,
        "floor": 1,
        "floors_total": null,
        "year_built": 2025,
        "address": {
            "voivodeship": "ma\u0142opolskie",
            "city": "Krak\u00f3w",
            "district": "Bronowice",
            "street": "Ojcowska",
            "latitude": 50.0847,
            "longitude": 19.8962
        },
        "details": [
            {
                "label": "Pow. ca\u0142kowita",
                "value": "153 m\u00b2"
            },
            {
                "label": "Liczba sypialni",
                "value": "4"
            }
        ],
        "equipment": [
            "Meble"
        ],
        "facilities": [],
        "utilities": [],
        "environment": {
            "noise_level": "Umiarkowanie niski",
            "public_transport": [
                {
                    "type": "Autobus",
                    "name": "Ojcowska Dworek",
                    "distance_m": 78
                }
            ]
        },
        "description": "Przestronne mieszkanie w nowym budynku...",
        "reference": "SPD-MW-17935",
        "photos": [
            {
                "url": "https://d-gr.cdngr.pl/kadry/k/r/gr-ogl/aa/bb/49402269_1.jpg",
                "alt": null
            }
        ],
        "plans": [],
        "videos": [],
        "has_3d_view": 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"
            }
        },
        "similar_listings": [],
        "advertiser_listings": []
    },
    "meta": {
        "endpoint_family": "listing",
        "billable": true,
        "attempts": 1
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 404 | Not Found | No listing exists at that address on Gratka, or the slug does not match the id (`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)