{ "openapi": "3.0.1", "info": { "title": "Otomoto.pl Scraper — Clean History & VAT Invoice", "description": "Otomoto.pl Scraper extracts car listings, prices, mileage, fuel type, gearbox, specifications, seller details, locations, and other vehicle data from Otomoto.pl. Automate automotive market research, price tracking, competitor analysis, and lead generation.", "version": "0.1", "x-build-id": "MaXZWrQTYJVKFdRKU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapio~otomoto-pl-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapio-otomoto-pl-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/scrapio~otomoto-pl-scraper/runs": { "post": { "operationId": "runs-sync-scrapio-otomoto-pl-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/scrapio~otomoto-pl-scraper/run-sync": { "post": { "operationId": "run-sync-scrapio-otomoto-pl-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "startUrls": { "title": "🔗 Start URLs (adverts or listings to screen)", "type": "array", "description": "Full Otomoto.pl URLs. Accepts BOTH listing pages (https://www.otomoto.pl/osobowe/volvo) and individual advert pages (https://www.otomoto.pl/osobowe/oferta/volvo-xc-40-ID6IbdLC.html). When this list is non-empty it OVERRIDES every search filter below, INCLUDING the provenance screen - the provenance columns are still filled in from the advert itself, and the word screen still runs. An advert that has been sold or removed produces a free, uncharged row with the reason instead of silently disappearing.", "default": [], "items": { "type": "string" } }, "category": { "title": "🏷️ Vehicle Category", "enum": [ "cars", "vans", "trucks", "motorcycles", "trailers", "campers", "construction", "agricultural", "parts" ], "type": "string", "description": "Otomoto section to search. English aliases are translated to the current Otomoto slug. Otomoto has moved several sections: motorcycles is now /motocykle-i-quady, trailers is /przyczepy, construction is /maszyny-budowlane, agricultural is /maszyny-rolnicze, and the standalone campers section was retired so campers are searched as the camper body type inside /dostawcze. The provenance filters are car-market filters; on the parts category they will return nothing.", "default": "cars" }, "query": { "title": "🔎 Brand / Model", "type": "string", "description": "Brand, or brand plus model separated by a space. Examples: \"volvo\" → /osobowe/volvo · \"bmw seria 3\" → /osobowe/bmw/seria-3 · \"mercedes-benz c-klasa\". Use Otomoto's own Polish model name. If Otomoto does not recognise the brand or the model it silently returns the whole catalogue, so the run FAILS instead and names the word it rejected.", "default": "" }, "location": { "title": "📍 Location (town or voivodeship)", "type": "string", "description": "A Polish town (\"Warszawa\", \"Kraków\", \"Łódź\") or a voivodeship (\"Małopolskie\", \"Mazowieckie\"). Polish characters are handled. Otomoto applies its own default catchment radius around a town, so nearby localities are included; a voivodeship is an exact administrative match. If Otomoto cannot resolve the name it falls back to the whole country, so the run FAILS instead of returning national results labelled as a local search.", "default": "" }, "sort": { "title": "↕️ Sort Order", "enum": [ "relevance_web", "created_at:desc", "created_at:asc", "price:asc", "price:desc", "year:desc", "year:asc", "filter_float_price:asc", "filter_float_price:desc", "filter_float_mileage:asc", "created_at_first:desc" ], "type": "string", "description": "Otomoto silently ignores unrecognised sort keys, so several of these values are handled for you: \"Price: low → high\" and \"Price: high → low\" are remapped to Otomoto's working price keys, and the two Year orders plus \"Oldest first\" are applied CLIENT-SIDE over the rows this run collected because Otomoto publishes no server-side year sort. The run log always states which one was used.", "default": "relevance_web" }, "minPrice": { "title": "💰 Min Price (PLN)", "minimum": 0, "type": "integer", "description": "Minimum advert price in Polish złoty. Applied by Otomoto as search[filter_float_price:from]." }, "maxPrice": { "title": "💸 Max Price (PLN)", "minimum": 0, "type": "integer", "description": "Maximum advert price in Polish złoty. Applied by Otomoto as search[filter_float_price:to]." }, "minProductionYear": { "title": "📅 Min Production Year", "minimum": 1900, "maximum": 2030, "type": "integer", "description": "Earliest production year, e.g. 2019. Applied by Otomoto as search[filter_float_year:from]." }, "maxProductionYear": { "title": "📆 Max Production Year", "minimum": 1900, "maximum": 2030, "type": "integer", "description": "Latest production year, e.g. 2025. Applied by Otomoto as search[filter_float_year:to]." }, "maxItems": { "title": "🔢 Max Items", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Hard cap on how many adverts are scraped and charged. Free rows (removed adverts, and adverts dropped by the word screen) are never charged and can only reduce the charged count, never push it above this number. Default is 10.", "default": 10 }, "damageStatus": { "title": "🚧 Damaged vehicles", "enum": [ "exclude", "any", "only" ], "type": "string", "description": "Otomoto's own damage checkbox (search[filter_enum_damaged]). Measured: exclude → 15,934 adverts, only → 1,008, any → 19,594. Defaults to EXCLUDE, because a procurement or family-car shortlist should not contain salvage. Choose 'only' when you are deliberately sourcing repairables.", "default": "exclude" }, "accidentFreeOnly": { "title": "🛡️ Accident-free only (bezwypadkowy)", "type": "boolean", "description": "Keep only adverts where the seller declared the car accident-free (search[filter_enum_no_accident]=1). Measured: 10,420 of 19,594. ON by default - it is the first question a Polish buyer asks. Turn it off to include cars with a declared accident history AND cars whose seller left the question blank.", "default": true }, "serviceHistoryOnly": { "title": "🔧 Documented service history only (serwisowany)", "type": "boolean", "description": "Keep only adverts advertised with a documented service record (search[filter_enum_service_record]=1). Measured: 8,405 of 19,594. ON by default - for a fleet or company purchase the maintenance record is the paperwork that matters second only to the invoice.", "default": true }, "vatInvoiceOnly": { "title": "🧾 VAT invoice only (faktura VAT)", "type": "boolean", "description": "Keep only cars sold with a VAT invoice (search[filter_enum_vat]=1), so a business buyer can reclaim the tax. Measured: 4,451 of 19,594. OFF by default because private buyers do not need it. Read hasVatMarginInvoice before assuming a car is reclaimable - a margin-scheme invoice generally is not.", "default": false }, "vatMarginOnly": { "title": "🧮 VAT margin invoice only (faktura VAT marża)", "type": "boolean", "description": "Keep only cars sold on a margin-scheme invoice (search[filter_enum_vat_discount]=1). Measured: 1,607 of 19,594. This is the opposite need to the one above: VAT generally CANNOT be reclaimed on a margin-scheme car. Leave off unless you specifically want them.", "default": false }, "firstOwnerOnly": { "title": "👤 First owner only (pierwszy właściciel)", "type": "boolean", "description": "Keep only cars still owned by their first owner (search[filter_enum_original_owner]=1). Measured: 4,746 of 19,594. Otomoto publishes NO owner-count filter and no owner-count field, so this first-owner checkbox is the deliverable half of a 'max previous owners' filter - a numeric owner limit does not exist on the site.", "default": false }, "registeredInPolandOnly": { "title": "🇵🇱 Registered in Poland only (zarejestrowany w PL)", "type": "boolean", "description": "Keep only cars already registered in Poland (search[filter_enum_registered]=1), dropping fresh imports that still need customs paperwork, excise duty, an inspection and a re-registration. Measured: 10,251 of 19,594.", "default": false }, "hasVinOnly": { "title": "🔢 Only adverts that publish a VIN", "type": "boolean", "description": "Keep only adverts where the seller published a VIN (search[filter_enum_has_vin]=1). Measured: 17,737 of 19,594. This actor does NOT return the VIN itself - Otomoto serves it as an encrypted token behind a reCAPTCHA - only whether one exists, so you know a history check is possible elsewhere.", "default": false }, "countryOfOrigin": { "title": "🌍 Country of origin", "enum": [ "", "pl", "d", "usa", "f", "b", "ch", "nl", "i", "dk", "a", "s", "gb", "cn", "n", "cz", "gr", "e", "l", "est", "tr", "ru", "kr", "irl", "hr", "ro", "sk", "lt", "by", "lv", "bg", "ua" ], "type": "string", "description": "Keep only cars Otomoto records as originating from this country (search[filter_enum_country_origin]). The code is Otomoto's own value and is shown in each option. Measured on /osobowe/bmw: Germany (d) → 3,440 of 19,594. Every code listed here was requested live and returned a non-zero advert count. Leave empty for any country.", "default": "" }, "excludeKeywords": { "title": "🚫 Drop adverts containing these words", "type": "array", "description": "Case-insensitive, Polish-diacritic-insensitive SUBSTRING match over the advert title, description and equipment list. Typical entries: powypadkowy, sprowadzony, do poprawek, anglik. Substring matching produces false positives on purpose-written prose - \"auto bezwypadkowe, nie powypadkowe\" contains \"powypadkow\" - which is exactly why the dropped rows are kept and labelled. Leave empty to skip the word screen.", "default": [], "items": { "type": "string" } }, "concurrency": { "title": "⚡ Concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many Otomoto pages are fetched in parallel. Default is 10, maximum 20.", "default": 10 }, "requestDelay": { "title": "⏱️ Request Delay (seconds)", "minimum": 0, "maximum": 30, "type": "integer", "description": "Extra pause before each request, in seconds, plus a small random jitter. Default is 0 (no extra delay).", "default": 0 }, "proxyConfiguration": { "title": "Proxy settings", "type": "object", "description": "Leave disabled to run without a proxy. The actor still escalates to datacenter and then residential automatically if it is genuinely blocked.", "default": { "useApifyProxy": false } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }