Otomoto APIotomoto.pl ↗
Search and retrieve vehicle listings from otomoto.pl. Get prices, specs, photos, seller info, and equipment data across Poland's largest car marketplace.
What is the Otomoto API?
The otomoto.pl API gives developers structured access to Poland's largest automotive marketplace across 5 endpoints. Use search_listings to query listings by make, model, and category with up to 32 results per page, or call get_listing_detail to retrieve a complete advert including price, seller information, vehicle parameters, equipment categories, and full image sets. Each listing summary includes fields like year, mileage, fuel type, transmission, and location.
curl -X GET 'https://api.parse.bot/scraper/db745f1d-4beb-4bb3-85b5-5eb6fbca2fe7/search_listings?make=volkswagen&page=1&model=golf&category=osobowe' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace otomoto-pl-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Otomoto SDK — search Polish vehicle listings, drill into details."""
from parse_apis.Otomoto_API import Otomoto, VehicleCategory, ListingNotFound
otomoto = Otomoto()
# List available vehicle categories
for cat in otomoto.categories.list(limit=8):
print(cat.id, cat.name)
# Search for Volkswagen listings in passenger cars category
for listing in otomoto.listing_summaries.search(
make="volkswagen",
category=VehicleCategory.OSOBOWE,
limit=5,
):
print(listing.title, listing.price.amount, listing.price.currency)
# Drill into the first result's full details
summary = otomoto.listing_summaries.search(make="toyota", limit=1).first()
if summary:
detail = summary.details()
print(detail.title, detail.price.value, detail.price.currency)
print(detail.seller.name, detail.seller.type)
# Get full-resolution photos for the listing
for photo_url in detail.photos(limit=3):
print(photo_url)
# Typed error handling: catch a removed listing
try:
removed = otomoto.listing_summaries.search(make="bmw", limit=1).first()
if removed:
removed.details()
except ListingNotFound as exc:
print(f"Listing gone: {exc.url}")
print("exercised: categories.list / search / details / photos / error handling")
Search vehicle listings on otomoto.pl with optional make, model, and category filters. Returns a paginated page of listing summaries including price, location, and vehicle parameters. Each page contains up to 32 results. Use the page parameter to advance through results.
| Param | Type | Description |
|---|---|---|
| make | string | Vehicle make slug (e.g., volkswagen, toyota, bmw, aston-martin). |
| page | integer | Page number for pagination (1-based). |
| model | string | Vehicle model slug (e.g., golf, corolla, 3-series). Requires make to be set. |
| category | string | Vehicle category slug. |
{
"type": "object",
"fields": {
"listings": "array of listing summary objects with id, title, url, price, location, thumbnail, make, model, year, mileage, fuel_type, transmission, engine_capacity, engine_power, seller_type, created_at",
"page_size": "integer number of listings per page",
"total_count": "integer total number of listings",
"total_pages": "integer total number of pages",
"current_page": "integer current page number"
},
"sample": {
"data": {
"listings": [
{
"id": "6148468711",
"url": "https://www.otomoto.pl/osobowe/oferta/volkswagen-golf-ID6I6lAb.html",
"make": "volkswagen",
"year": "2014",
"model": "golf",
"price": {
"type": null,
"amount": 83500,
"currency": "PLN"
},
"title": "Volkswagen Golf 2.0 TSI BMT 4Mot R",
"mileage": "90698",
"location": {
"city": "Korytnica",
"region": "Mazowieckie"
},
"fuel_type": "petrol",
"thumbnail": "https://ireland.apollo.olxcdn.com/v1/files/ff0cowl8vcow1-OTOMOTOPL/image;s=640x480",
"created_at": "2026-06-06T14:45:51Z",
"seller_type": null,
"engine_power": "300",
"transmission": "manual",
"engine_capacity": "1984"
}
],
"page_size": 32,
"total_count": 3511,
"total_pages": 110,
"current_page": 1
},
"status": "success"
}
}About the Otomoto API
Searching and Browsing Listings
The search_listings endpoint accepts optional make, model, and category slugs and returns paginated results of up to 32 listings per page. The response includes total_count and total_pages so you can plan how many requests you need. Each listing summary in the listings array carries the listing id, url, title, price, location, thumbnail, make, model, year, mileage, fuel_type, and transmission. The model parameter requires make to be set. To get the valid category slugs and their Polish display names, call get_categories first — the list is stable and changes infrequently.
Full Listing Detail and Photos
get_listing_detail accepts a full listing URL or path and returns the complete advert object. Beyond the summary fields, this includes a description field containing the HTML seller description, an equipment array organized into category objects, an images object with both photos and thumbnails arrays, a structured price object with value, currency, and labels, and a seller object covering seller type, name, and location. The details array provides all key-value vehicle parameters (engine size, color, doors, etc.) as listed on the original advert. If you only need image URLs, get_listing_photos calls the same listing URL but returns just the photos array of full-resolution strings.
Bulk Collection
get_all_listings_paginated iterates through multiple pages in a single API call and returns a flat listings array alongside total_count and pages_scraped. The max_pages parameter caps collection between 1 and 50 pages. Because this endpoint performs multiple fetches internally, it is slower than calling search_listings page by page — use it when you need a bulk snapshot and latency is not a concern.
The Otomoto API is a managed, monitored endpoint for otomoto.pl — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when otomoto.pl changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official otomoto.pl API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track asking price trends for a specific make and model over time using
search_listingsprice fields - Build a cross-border vehicle import tool comparing Polish market prices by fuel type and mileage
- Aggregate dealer inventory by parsing seller type and location fields from
get_listing_detail - Populate a listing alert system by diffing total_count across repeated searches for a given make/model
- Extract full equipment lists from
equipmentarrays to train a used-car valuation model - Download all listing photos via
get_listing_photosfor computer vision or image quality analysis - Build a category browser app using slug and Polish display name pairs from
get_categories
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does otomoto.pl have an official developer API?+
What vehicle parameters does get_listing_detail return beyond the search summary?+
get_listing_detail returns a details array of all key-value parameters on the advert page — things like engine displacement, color, number of doors, and drive type — plus an equipment array grouped into categories, an HTML description, structured price labels, and a seller object with seller type and name.How does pagination work across these endpoints?+
search_listings returns up to 32 listings per page. Use the page parameter (1-based) to step through results; the response includes total_pages and total_count to plan iteration. get_all_listings_paginated handles the iteration for you and returns a flat combined listings array, but it is slower because it performs multiple sequential fetches. The max_pages cap is 50.Does the API support filtering by price range, mileage, or year?+
search_listings and get_all_listings_paginated filter only by make, model, and category. Price, mileage, year, and fuel-type filters are not exposed as parameters. You can fork this API on Parse and revise it to add those filter parameters to the search endpoint.Is seller contact information like phone numbers available?+
seller object in get_listing_detail returns seller type, name, and location. Phone numbers and direct contact details are not included in the current response. You can fork this API on Parse and revise it to add a contact-detail endpoint if that data is accessible on the listing page.