# Otomoto API scraper — otomoto.pl, Poland's largest car marketplace (OLX Group): search cars, vans and motorcycles by make, model, voivodeship or city with otomoto's own filters and sorts, and read the full offer record. Every ad returns the price in PLN checked against otomoto's own price string, the published year, mileage, fuel, gearbox, engine power and capacity, whether the seller is a private person or a dealer, and whether the ad is a paid promoted placement. No account, no browser.

> Search otomoto.pl the way its own visitors do: pick a section (cars, vans, motorcycles), narrow by make and model, by voivodeship or by city with a radius, and apply otomoto's own price, year, mileage, engine power, engine capacity, fuel, gearbox, body, condition, damage and seller-type filters. Every ad comes back with the price in PLN cross-checked against otomoto's own price string, the published model year, the odometer reading with the site's own formatted string beside it, fuel and gearbox in both otomoto's code and its Polish label, engine power and capacity, the city and voivodeship, whether a private person or a dealer is selling (otomoto's own flag, never inferred), otomoto's below/at/above-market price indicator, the CEPiK history-check flag, and whether the ad is a paid promoted placement. Promoted ads are returned in the position otomoto gives them and flagged, never dropped. Sort by price, mileage, engine power or posting date, and page through the whole result set. The answer repeats every filter otomoto actually applied, with the canonical slug it resolved to, and lists every model otomoto publishes for the chosen make with its live ad count — so the next call can drill down without guessing a slug.
> ReefAPI engine `otomoto` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/otomoto/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/otomoto/v1/search — 1 credit
Search otomoto.pl the way its own visitors do: pick a section (cars, vans, motorcycles), narrow by make and model, by voivodeship or by city with a radius, and apply otomoto's own price, year, mileage, engine power, engine capacity, fuel, gearbox, body, condition, damage and seller-type filters. Every ad comes back with the price in PLN cross-checked against otomoto's own price string, the published model year, the odometer reading with the site's own formatted string beside it, fuel and gearbox in both otomoto's code and its Polish label, engine power and capacity, the city and voivodeship, whether a private person or a dealer is selling (otomoto's own flag, never inferred), otomoto's below/at/above-market price indicator, the CEPiK history-check flag, and whether the ad is a paid promoted placement. Promoted ads are returned in the position otomoto gives them and flagged, never dropped. Sort by price, mileage, engine power or posting date, and page through the whole result set. The answer repeats every filter otomoto actually applied, with the canonical slug it resolved to, and lists every model otomoto publishes for the chosen make with its live ad count — so the next call can drill down without guessing a slug.

**Parameters:**
- `category` (enum, optional, default "osobowe") — Which otomoto section to search. These are otomoto's own URL sections; the category id each one resolves to is returned in filters_applied. [one of: osobowe, dostawcze, motocykle-i-quady]
- `make` (string, optional) — A make exactly as otomoto spells it in its own URLs: bmw, audi, volkswagen, mercedes-benz, skoda. Case and spaces are normalised. If otomoto does not recognise the make the call is refused — it is NOT quietly widened to every car, which is what the site itself does.
- `model` (string, optional) — A model slug as otomoto spells it (x3, seria-3, golf, a4). Requires make. Every model otomoto publishes for a make, with its live ad count, comes back in related_links.models of any search for that make.
- `location` (string, optional) — A Polish voivodeship or city slug as otomoto spells it (mazowieckie, warszawa, krakow, slaskie, wroclaw). otomoto resolves it itself to a region or a city and echoes which; the answer is in filters_applied. A city search also carries a radius (see distance_km). An unrecognised location is refused.
- `distance_km` (integer, optional) — Search radius in kilometres around a city given in location. otomoto's own default for a city is 50 km. Ignored for a voivodeship, which has no radius.
- `page` (integer, optional, default 1) — Result page, from 1. otomoto serves 32 ads per page and the page size is fixed by the site, not by this API.
- `sort` (enum, optional, default "relevance") — Result order, using otomoto's own published sort ids. [one of: relevance, featured, newest, price_asc, price_desc, mileage_asc, mileage_desc, power_asc, power_desc]
- `seller_type` (enum, optional) — Whether the ad is posted by a private seller or a business. This is otomoto's own filter, and every row also carries the seller type the site publishes for it, so the two can be checked against each other (measured: 32/32 rows agreed on each side). [one of: private, business]
- `condition` (enum, optional) — New or used, as otomoto's own new/used filter defines it. [one of: new, used]
- `fuel_type` (string, optional) — otomoto's fuel value: petrol, diesel, petrol-lpg, petrol-cng, hybrid, plugin-hybrid, electric, hydrogen, ethanol. Every row returns the value and otomoto's own Polish label, so the vocabulary can be read back from any result.
- `gearbox` (string, optional) — otomoto's gearbox value: manual or automatic. Rows return the value and otomoto's Polish label.
- `body_type` (string, optional) — otomoto's body value: suv, sedan, kombi, compact, city-cars, minivan, coupe, cabrio, small-cars.
- `damaged` (boolean, optional) — true returns only damaged vehicles, false only undamaged ones. Omit to include both, which is otomoto's default.
- `price_from` (integer, optional) — Lowest price in PLN, inclusive, as otomoto's own price filter applies it.
- `price_to` (integer, optional) — Highest price in PLN, inclusive.
- `year_from` (integer, optional) — Earliest model year, inclusive.
- `year_to` (integer, optional) — Latest model year, inclusive.
- `mileage_from` (integer, optional) — Lowest odometer reading in kilometres, inclusive.
- `mileage_to` (integer, optional) — Highest odometer reading in kilometres, inclusive.
- `engine_power_from` (integer, optional) — Lowest engine power in metric horsepower (KM), inclusive.
- `engine_power_to` (integer, optional) — Highest engine power in metric horsepower (KM), inclusive.
- `engine_capacity_from` (integer, optional) — Smallest engine capacity in cm3, inclusive.
- `engine_capacity_to` (integer, optional) — Largest engine capacity in cm3, inclusive.

**Returns:** results[]{ad_id (otomoto's numeric ad id), listing_id (the offer token in the URL, e.g. ID6IgtYL or OLX_ID6IguOF — this is what listing/detail takes), title, subtitle, url, created_at, price (PLN, cross-checked against the source's own price string), price_raw, currency, price_is_gross, price_evaluation (otomoto's own below/in/above market indicator), price_drop, price_mismatch (present only when the source contradicted itself and the price was withheld), make, make_slug, model, model_slug, version, year, mileage_km, mileage_display (otomoto's own formatted string, for cross-checking), fuel_type{value,label}, gearbox{value,label}, engine_power_hp, engine_capacity_ccm, field_mismatch (the numeric fields the source contradicted, when any), location{city, region, country}, seller{kind — private, dealer, or crosslisted for an ad cross-posted from OLX, which is all otomoto publishes on the row for those (the offer page resolves the real type); uuid, dealer_id, dealer_name, dealer_url, is_credit_intermediary}, is_promoted, promotions[], badges[], cepik_verified, image, category_id}, count, total_results, total_pages, page, page_size, has_more, sort, filters_applied (every filter otomoto echoed back, with the canonical slug and label it resolved to), breadcrumb[]{label, url}, related_links{models|makes|…}[]{title, slug, url, count}, search_url (the otomoto page this answer came from), currency

**Example request body:**
```json
{
  "make": "bmw"
}
```

### POST https://api.reefapi.com/otomoto/v1/listing/detail — 1 credit
The full otomoto offer record from an offer URL or its ID token: title, the price in PLN with otomoto's own VAT and invoice labels, the seller's type (private person or dealer), the dealer's trading name, page and how many ads it currently has, the city, voivodeship and country, the whole published specification grouped exactly as otomoto groups it (basic information, technical specification, condition and history, financing), every equipment item by category, every photo at full size, the seller's own description with its HTML stripped, the CEPiK history-check flag, the posting and last-update timestamps, the ad status, and whether the ad carries a paid promotion. Numbers otomoto publishes twice — mileage, year, engine power, engine capacity — are returned only when the site's own formatted string agrees with its raw value. The seller's street address, postcode, map point and website are returned as the page carries them; the phone number sits behind otomoto's reveal call and is not requested. A withdrawn or unknown offer answers NOT_FOUND.

**Parameters:**
- `listing` (string, required) — An otomoto offer URL, or the listing_id at the end of it (…-ID6IgtYL.html → ID6IgtYL; an ad cross-posted from OLX ends …-OLX_ID6IguOF.html → OLX_ID6IguOF, and the OLX_ part is required). Search rows carry both `url` and `listing_id`. The numeric `ad_id` is otomoto's internal id and does NOT address an offer page; passing it is refused rather than reported as missing.

**Returns:** listing{ad_id, listing_id, title, url, status, created_at, updated_at, price, price_raw, currency, price_labels[], price_drop, is_promoted, promotions[], make, make_slug, model, model_slug, version, generation, year, mileage_km, mileage_display, fuel_type{value,label}, gearbox{value,label}, engine_power_hp, engine_capacity_ccm, body_type{value,label}, colour{value,label}, doors, seats, drive{value,label}, condition{value,label}, vin_published, field_mismatch, location{city, region, country}, seller{kind, name, dealer_url, active_ads, badges[], address, postal_code, short_address, latitude, longitude, website}, specs[]{key, label, value, group}, spec_groups[]{key, label}, equipment[]{key, label, items[]{key, label}}, images[], image_count, description, cepik_verified, category{id, code, name}, breadcrumb[]{label, url}, seo{title, description}}

**Example request body:**
```json
{
  "listing": "https://www.otomoto.pl/osobowe/oferta/bmw-x3-ID6IgtYL.html"
}
```

### POST https://api.reefapi.com/otomoto/v1/makes — 1 credit
The makes otomoto itself lists on a section's landing page, ranked by how many live ads each one carries, with the exact slug a search needs. This is otomoto's own published shortlist, not its full make register — it is as long as otomoto makes it (20 entries on the cars section, measured), and `count` says how many came back. Use it to get a slug right before searching, because otomoto silently ignores a make it does not recognise and answers with the whole section instead. Passing a make returns that make's model shortlist instead, each model with its slug and live ad count.

**Parameters:**
- `category` (enum, optional, default "osobowe") — Which otomoto section to search. These are otomoto's own URL sections; the category id each one resolves to is returned in filters_applied. [one of: osobowe, dostawcze, motocykle-i-quady]
- `make` (string, optional) — A make exactly as otomoto spells it in its own URLs: bmw, audi, volkswagen, mercedes-benz, skoda. Case and spaces are normalised. If otomoto does not recognise the make the call is refused — it is NOT quietly widened to every car, which is what the site itself does.

**Returns:** results[]{title, slug, url, count (live ads for that make or model)}, kind (makes|models), count (how many entries otomoto published, not how many exist), category, make (when a make was given), total_results (live ads in the section), other_lists{fuel-types|body-types|regions|model-generations} — the other shortlists otomoto published on the same page, each with slug and count, source_url

**Example request body:**
```json
{
  "category": "osobowe"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=otomoto
- Human docs page: https://reefapi.com/docs/otomoto
- Overview page: https://reefapi.com/otomoto-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
