# Otomoto Listing API Documentation

Scrappa's `GET /api/otomoto/listing` endpoint returns the full detail of a single Otomoto vehicle listing as JSON.

## What the response contains

The listing carries `id`, `url`, `title`, `status`, `description`, `price` (numeric value + currency), `price_evaluation`, `make`, `model`, `year`, `mileage`, `engine_power`, `engine_capacity`, `fuel`, `transmission`, `body_type`, `vin`, `first_registration`, `location` (address, city, region, country, postal code, coordinates), `images`, `equipment` (grouped items), `parameters` (every parameter with value and unit) and the public `seller` block. Seller phone numbers are never returned.

## Correctness notes

Otomoto answers an unknown listing slug with a well-formed 404. This endpoint maps that to a `NOT_FOUND` error and never bills it. A numeric listing id resolves through the Otomoto ad hash, so one upstream lookup serves either form.

## Related Otomoto endpoints

- `GET /api/otomoto/search` — find the listing id first
- `GET /api/otomoto/dealer` — the dealer profile behind a listing's `seller.url`

- **Documentation:** [https://scrappa.co/docs/otomoto-api/otomoto_listing](https://scrappa.co/docs/otomoto-api/otomoto_listing)
- **API group:** Otomoto API
- **Endpoint:** `GET https://scrappa.co/api/otomoto/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 |
| --- | --- | --- | --- |
| `listing_id` | string | Yes | Numeric Otomoto listing id, as returned in the search response. |
| `url` | string | No | Full detail URL from a search card. Alternative to listing_id. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/otomoto/listing?listing_id=6151011578"
```

## Example response

```json
{
    "success": true,
    "data": {
        "listing": {
            "id": "6151011578",
            "url": "https://www.otomoto.pl/osobowe/oferta/volvo-xc-60-ID6Ih16a.html",
            "title": "Volvo XC 60",
            "status": "ACTIVE",
            "price": {
                "value": 66000,
                "currency": "PLN",
                "is_under_budget": false
            },
            "make": "volvo",
            "model": "xc-60",
            "year": 2019,
            "mileage": 49153,
            "engine_power": 320,
            "engine_capacity": 1969,
            "fuel": "petrol",
            "transmission": "automatic",
            "body_type": "suv",
            "vin": "dMAhVCJtxzxRDF2YyKNy8xVCWe9bMRwb7H9ryV6i8GtQ",
            "first_registration": "2019",
            "location": {
                "city": "Warszawa",
                "city_id": 17871,
                "country": "Polska",
                "postal_code": "00-877"
            },
            "images": [
                "https://ireland.apollo.olxcdn.com/v1/files/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmbiI6IjByeGx5MHlxNXZwaDEtT1RPTU9UT1BMIiwidyI6W3siZm4iOiJ3ZzRnbnFwNnkxZi1PVE9NT1RPUEwiLCJzIjoiMTYiLCJhIjoiMCIsInAiOiIxMCwtMTAifV19.ti36sSsq7Hk0ajbhkZ3_mMhtDICZc85cq_87b6eArAk/image"
            ],
            "equipment": [
                {
                    "group": "Audio i multimedia",
                    "items": [
                        "Apple CarPlay",
                        "Android Auto"
                    ]
                }
            ],
            "parameters": [
                {
                    "key": "mileage",
                    "value": 49153,
                    "unit": "km"
                }
            ],
            "seller": {
                "type": "PROFESSIONAL",
                "name": "WINCARS",
                "url": "https://wincars.otomoto.pl/inventory",
                "number_of_active_ads": 267
            }
        }
    },
    "meta": {
        "endpoint_family": "listing"
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
|  | Error | No listing carries that id. Not billed. |
|  | Error | Otomoto could not be reached. Not billed. |
|  | Error | The upstream service is temporarily unavailable. Please retry shortly. |

## Frequently asked questions

### Where do I get a listing id?

From the `id` field of any item returned by the Otomoto search endpoint.

### What happens for an id that does not exist?

You get a NOT_FOUND error rather than a broken page, and the request is not billed.

### Do I get the seller phone number?

No. Seller phone numbers are removed before the response leaves the service.

## 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)