| Field | Type | Required | Description |
|---|
| startUrl | string | No | Optional OLX search or category URL. Country, keyword, category, region, city and price are parsed from the URL. |
| country | enum | No | Marketplace to scrape: Poland, Ukraine, Romania, Portugal, Bulgaria, Kazakhstan or Uzbekistan. Default Poland. |
| maxItems | integer | No | Free users capped at 10 (preview). Paid users up to 1,000,000. |
| query | string | No | Free-text keyword in the country's native language. |
| category | enum | No | Category picked from the OLX tree of every market (7,700+ options). The country-code prefix selects the marketplace and overrides the Country field. Pick a parent category to include all of its subcategories. No IDs to guess. |
| region | enum | No | Region or province to limit results to, picked from a dropdown of all 170 OLX regions across the seven markets. |
| cityName | string | No | City name (e.g. Warszawa, Kyiv, Bucuresti). Resolved to the matching OLX city automatically, so you never look up an ID. |
| priceMin | integer | No | Minimum price in the local currency. |
| priceMax | integer | No | Maximum price in the local currency. |
| itemState | enum | No | Any, new, used or damaged. |
| sellerType | enum | No | Any, private or business. |
| sortBy | enum | No | Newest, lowest price, highest price or relevance. |
| proxyConfiguration | object | No | Apify Proxy. Datacenter is enough for most runs. |
Example: pull the 50 newest iPhone listings in Warszawa on OLX Poland.
```json
{
"country": "PL",
"query": "iphone",
"cityName": "Warszawa",
"maxItems": 50,
"sortBy": "created_at:desc"
}
````
Example: used cars in Romania, business sellers only, between 5,000 and 15,000 EUR.
```json
{
"category": "RO:84",
"query": "BMW",
"priceMin": 5000,
"priceMax": 15000,
"sellerType": "business",
"itemState": "used",
"maxItems": 200
}
```
> โ ๏ธ **Good to Know:** OLX caps a single filter combination at roughly 1,000 results per query. To dig deeper, narrow the search by city, category, region, price range or keyword. Because OLX runs each country as a separate platform, the Category and Region dropdowns carry a country-code prefix (for example PL or UA) that automatically selects the right marketplace.
***
### ๐ Output
Each record is a single OLX listing with full price, seller, location, parameter and photo data.
#### ๐งพ Schema
| Field | Type | Example |
|---|---|---|
| ๐ผ๏ธ `imageUrl` | string | `https://ireland.apollo.olxcdn.com/v1/files/.../image;s=1024x768` |
| ๐ `title` | string | `Iphone 17 Pro Max 512GB Deep Blue` |
| ๐ `url` | string | `https://www.olx.pl/d/oferta/iphone-17-pro-max-...html` |
| ๐ `listingId` | number | `1071097984` |
| ๐ `country` | string | `PL` |
| ๐ `domain` | string | `www.olx.pl` |
| ๐ฐ `price` | number | `5300` |
| ๐ฑ `currency` | string | `PLN` |
| ๐ท๏ธ `priceLabel` | string | `5 300 zล` |
| ๐ `priceType` | string | `price` (or `free`, `swap`, `arranged`) |
| ๐ค `priceNegotiable` | boolean | `false` |
| ๐ง `itemState` | string | `new`, `used`, `damaged` or `null` |
| ๐๏ธ `categoryId` | number | `99` |
| ๐ `categoryType` | string | `electronics` |
| ๐ค `sellerType` | string | `private` or `business` |
| ๐ `sellerId` | number | `2279110136` |
| ๐ชช `sellerUuid` | string | `77aef22a-20bb-4e42-9556-c52b98007611` |
| ๐ `sellerName` | string | `Wiktor` |
| ๐ข `sellerCompanyName` | string | optional company |
| ๐
`sellerJoined` | datetime | `2024-06-20T12:46:57+02:00` |
| ๐ข `sellerLastSeen` | datetime | `2026-05-06T23:56:29+02:00` |
| ๐ต `sellerIsOnline` | boolean | `false` |
| โ๏ธ `sellerOtherAdsEnabled` | boolean | `true` |
| ๐ `contactPhone` | boolean | phone available |
| ๐ฌ `contactChat` | boolean | chat available |
| ๐๏ธ `city` | string | `Warszawa` |
| ๐๏ธ `district` | string | `Biaลoลฤka` |
| ๐บ๏ธ `region` | string | `Mazowieckie` |
| ๐งญ `latitude` | number | `52.33008` |
| ๐งญ `longitude` | number | `20.99661` |
| ๐ `description` | string | seller-written description |
| ๐งช `parameters` | object | category-specific attributes |
| ๐ผ๏ธ `photoCount` | number | `3` |
| ๐ผ๏ธ `photoUrls` | array | full 1024x768 image URLs |
| โญ `isPromoted` | boolean | paid placement |
| ๐ `isHighlighted` | boolean | yellow background highlight |
| ๐ `isTopAd` | boolean | top of search results |
| โฑ๏ธ `isUrgent` | boolean | urgent label |
| ๐ฆ `offerType` | string | `offer` or `wanted` |
| ๐ฆ `status` | string | `active`, `paused`, etc. |
| ๐
`createdAt` | datetime | first published |
| ๐ `refreshedAt` | datetime | last refreshed |
| โ `validUntil` | datetime | expiry date |
| ๐ `scrapedAt` | datetime | when this record was captured |
| โ `error` | string | only present when a fetch failed |
#### ๐ฆ Sample records
|
#### ๐ Research and academia
- Empirical datasets for papers, thesis work, and coursework
- Longitudinal studies tracking changes across snapshots
- Reproducible research with cited, versioned data pulls
- Classroom exercises on data analysis and ethical scraping
|
#### ๐จ Personal and creative
- Side projects, portfolio demos, and indie app launches
- Data visualizations, dashboards, and infographics
- Content research for bloggers, YouTubers, and podcasters
- Hobbyist collections and personal trackers
|
|
#### ๐ค Non-profit and civic
- Transparency reporting and accountability projects
- Advocacy campaigns backed by public-interest data
- Community-run databases for local issues
- Investigative journalism on public records
|
#### ๐งช Experimentation
- Prototype AI and machine-learning pipelines with real data
- Validate product-market hypotheses before engineering spend
- Train small domain-specific models on niche corpora
- Test dashboard concepts with live input
|
***
### ๐ Automating OLX International Classifieds Scraper
Run the Actor on demand, on a schedule, or as part of a larger workflow.
- **Node.js**: call `apify.actor("parseforge/olx-scraper").start({...})` to launch runs from your backend.
- **Python**: use the [Apify Python client](https://docs.apify.com/api/client/python/) to feed listings into pandas, BigQuery or your own warehouse.
- **REST API**: trigger runs from any HTTP client following the [Apify API docs](https://docs.apify.com/api/v2).
Schedules: pair the Actor with [Apify Schedules](https://docs.apify.com/platform/schedules) to refresh inventory hourly, daily or weekly without writing any infrastructure.
***
### โ Frequently Asked Questions