# OLX Marketplace Listings Scraper (`trovevault/olx-marketplace-listings-scraper`) Actor
Search public OLX listings by keyword across 11 country marketplaces. Extract titles, prices, locations, sellers, clean descriptions, attributes, images, and listing URLs.
- **URL**: https://apify.com/trovevault/olx-marketplace-listings-scraper.md
- **Developed by:** [Trove Vault](https://apify.com/trovevault) (community)
- **Categories:** E-commerce, News, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet
## Pricing
from $1.70 / 1,000 listings
This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event
## What's an Apify Actor?
Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).
If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
## OLX Marketplace Listings Scraper
Search public OLX classifieds with one keyword across 11 country marketplaces and export normalized data. The Actor collects titles, numeric prices, currencies, locations, categories, conditions, sellers, clean text descriptions, attributes, images, publication timestamps, and direct URLs when publicly available.
Use the same input for one or several countries instead of maintaining separate search URLs, category trees, and parsers. The Actor does not calculate deal scores, freshness ranks, market positions, price-drop predictions, or historical comparisons.
### What can this Actor do?
- Search the same keyword in multiple OLX countries in one run.
- Map a normalized category to each marketplace's local category tree.
- Apply optional location and local-currency price filters.
- Normalize country-specific pages and APIs into one dataset schema.
- Deduplicate promoted and organic copies of the same listing.
- Continue with the remaining countries when one marketplace fails.
- Append results to an existing dataset and tag rows with a workflow ID.
- Store a per-country diagnostic report in `RUN_SUMMARY`.
Typical uses include product sourcing, local supply research, price comparisons, scheduled monitoring, and data pipelines.
### Which countries are supported?
Select one or more marketplaces in the `countries` input:
| Country | Code | Currency | Access method |
| --- | --- | --- | --- |
| Bosnia and Herzegovina | `ba` | BAM | Public OLX API |
| Brazil | `br` | BRL | Residential proxy and browser fallback |
| Bulgaria | `bg` | BGN | Direct extraction |
| India | `in` | INR | Residential proxy and browser fallback |
| Kazakhstan | `kz` | KZT | Direct extraction |
| Pakistan | `pk` | PKR | Residential proxy and browser fallback |
| Poland | `pl` | PLN | Direct extraction |
| Portugal | `pt` | EUR | Direct extraction |
| Romania | `ro` | RON | Direct extraction |
| Ukraine | `ua` | UAH | Direct extraction |
| Uzbekistan | `uz` | UZS or USD | Direct extraction |
Brazil, India, and Pakistan can require a residential proxy and Chromium when HTTP extraction is blocked. The default is configured accordingly, making these runs slower and more expensive. Other marketplaces ignore the proxy setting.
OLX country sites are independent products and may change their page structure or access controls without notice.
### How do I run it?
For a small single-country search:
```json
{
"query": "iPhone 15",
"countries": ["pt"],
"maxResults": 10
}
````
Use the same keyword across several marketplaces:
```json
{
"query": "mountain bike",
"countries": ["pl", "pt", "ro"],
"category": "sports-hobbies",
"minPrice": 500,
"maxPrice": 5000,
"sort": "price-asc",
"maxResults": 100
}
```
For Brazil, keep the residential proxy enabled:
```json
{
"query": "iPhone 15",
"countries": ["br"],
"category": "electronics",
"maxResults": 25,
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": ["RESIDENTIAL"]
}
}
```
`query` and `countries` are required. `category`, `location`, `minPrice`, `maxPrice`, and `sort` narrow each search. `maxResults` is a per-country limit from 1 to 1,000, so three countries at 100 can produce 300 rows. Prices use local currency and are not converted.
`datasetId` optionally appends every row to an existing Apify dataset. `runId` is copied into each row and summary for pipeline tracing. Legacy API calls using a single `country` string remain supported.
If a mapped category returns no listings, the Actor retries the keyword across all categories.
### What data does it return?
Each dataset row can contain:
| Field | Description |
| --- | --- |
| `listingId` | Marketplace listing identifier |
| `title` | Public listing title |
| `price`, `currency`, `priceText` | Parsed price, ISO currency, and original label |
| `country`, `countryCode` | Marketplace name and two-letter input code |
| `category`, `location`, `condition` | Normalized listing context |
| `sellerName`, `sellerType` | Public seller information when exposed |
| `postedAt` | Publication timestamp when available |
| `description` | Plain text with HTML tags such as `
` removed |
| `attributes` | Category-specific key-value details |
| `imageUrl`, `images` | Primary image and available gallery URLs |
| `url` | Canonical public listing URL |
| `scrapedAt`, `runId` | Observation time and optional workflow ID |
Example normalized output:
```json
{
"listingId": "672276142",
"title": "Caixas iPhone 15 Pro Max",
"price": 15,
"currency": "EUR",
"priceText": "15 €",
"country": "Portugal",
"countryCode": "pt",
"category": "electronics",
"location": "Lisboa, Benfica",
"condition": "used",
"sellerType": "private",
"postedAt": "2026-07-13T17:24:05+01:00",
"description": "Capas para iPhone 15 em excelente estado.",
"attributes": {
"Estado": "Usado",
"Tipo": "Outros"
},
"imageUrl": "https://ireland.apollo.olxcdn.com/v1/files/example/image;s=750x1000",
"images": [
"https://ireland.apollo.olxcdn.com/v1/files/example/image;s=750x1000"
],
"url": "https://www.olx.pt/d/anuncio/example-IDExample.html",
"scrapedAt": "2026-07-21T09:09:01.158Z"
}
```
Unavailable fields are omitted or `null`. Exchange, free, or unpriced listings can have `price: null` while retaining `priceText`. Missing seller details, dates, or attributes are never invented.
### How can I integrate it?
Start a run with the Apify API:
```bash
curl -X POST "https://api.apify.com/v2/acts/trovevault~olx-marketplace-listings-scraper/runs" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"query": "iPhone 15",
"countries": ["pt", "pl", "ro"],
"category": "electronics",
"maxResults": 25
}'
```
It also works with Apify clients, Schedules, webhooks, dataset exports, and MCP. It writes only to Apify storage unless you provide `datasetId`.
At the end of a run, the default key-value store contains:
- `OUTPUT`: dataset URL plus aggregate counters.
- `RUN_SUMMARY`: saved rows, discovered listings, requests, failures, filters, and timing for each country.
### How much does a run cost?
Cost depends on saved rows, pagination, memory, and proxy traffic. Most listings require one detail request. Multi-country totals scale with `maxResults` times the selected countries.
Protected markets use a 2 GB browser runtime and residential traffic, so they cost more. Start with 5 to 25 results per country, inspect them, then increase the limit. Proxy traffic follows your Apify plan.
### What are the limitations?
- Search ranking, promoted results, and deep pagination are controlled by OLX.
- A normalized category may not have an exact equivalent in every country.
- Location filtering works only when OLX exposes a matching public location.
- Detail pages can be unavailable even when the search card remains public; card data is retained and unavailable fields become `null`.
- Seller names, descriptions, exact publication times, and attributes are not present on every listing.
- Contact details behind login, chat, phone reveal, or private account flows are not accessed.
- Source text can contain inaccurate seller claims; the Actor reports it without verifying the item or seller.
### How do I troubleshoot it?
| Problem | What to check |
| --- | --- |
| Empty dataset | Use a broader keyword, choose `category: "all"`, and remove location or price filters. |
| Fewer rows than requested | The market may have fewer public matches, limited pagination, duplicates, or rows removed by filters. |
| Protected-market access error | For Brazil, India, or Pakistan, keep Apify Proxy enabled with the `RESIDENTIAL` group. |
| Some fields are `null` | The country site did not expose those fields publicly; use `url` to audit the source listing. |
| One country failed | Read `RUN_SUMMARY`; the Actor records that error and continues with all remaining countries. |
For issues, include the country, query, run time, run ID, and proxy status. Never post tokens, passwords, or private data.
### Is responsible use required?
Yes. This Actor reads public listing pages. You are responsible for complying with applicable laws, marketplace terms, robots directives, data-protection requirements, and acceptable-use rules. Avoid collecting or using personal data without a lawful purpose. Do not use it to bypass login, private messaging, contact-reveal controls, or other access restrictions.
# Actor input Schema
## `query` (type: `string`):
Keyword or phrase to search for in listing titles and descriptions, for example iPhone 15, mountain bike, or apartment Lisbon.
## `countries` (type: `array`):
OLX country marketplaces to search with the same keyword. Results from every selected country are normalized into one dataset.
## `category` (type: `string`):
Optional normalized category filter. The Actor maps this selection to the closest category available in every chosen OLX marketplace.
## `location` (type: `string`):
Optional city, region, state, or district name. Listings are filtered when the marketplace exposes a matching public location.
## `minPrice` (type: `number`):
Optional minimum listing price, applied independently in each marketplace's local currency.
## `maxPrice` (type: `number`):
Optional maximum listing price, applied independently in each marketplace's local currency.
## `sort` (type: `string`):
Choose the preferred result order. Availability depends on the selected marketplace; the Actor preserves marketplace order when a native sort is unavailable.
## `maxResults` (type: `integer`):
Maximum number of listings to save from each selected country. The total can reach this value multiplied by the number of countries, so higher values take longer and cost more.
## `proxyConfiguration` (type: `object`):
Proxy settings used for Brazil, India, and Pakistan. The default residential proxy improves access but adds proxy usage charges; it is ignored for other marketplaces.
## `datasetId` (type: `string`):
Optional existing Apify dataset ID. Each result is appended to that dataset as well as this run's default dataset.
## `runId` (type: `string`):
Optional parent workflow identifier copied into every output row and the run summary.
## Actor input object example
```json
{
"query": "iPhone 15",
"countries": [
"pt"
],
"category": "all",
"sort": "relevance",
"maxResults": 10,
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}
```
# Actor output Schema
## `dataset` (type: `string`):
No description
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"query": "iPhone 15"
};
// Run the Actor and wait for it to finish
const run = await client.actor("trovevault/olx-marketplace-listings-scraper").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = { "query": "iPhone 15" }
# Run the Actor and wait for it to finish
run = client.actor("trovevault/olx-marketplace-listings-scraper").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{
"query": "iPhone 15"
}' |
apify call trovevault/olx-marketplace-listings-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=trovevault/olx-marketplace-listings-scraper",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "OLX Marketplace Listings Scraper",
"description": "Search public OLX listings by keyword across 11 country marketplaces. Extract titles, prices, locations, sellers, clean descriptions, attributes, images, and listing URLs.",
"version": "0.1",
"x-build-id": "LpgIG4t9tqcTjJ9Sx"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/trovevault~olx-marketplace-listings-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-trovevault-olx-marketplace-listings-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/trovevault~olx-marketplace-listings-scraper/runs": {
"post": {
"operationId": "runs-sync-trovevault-olx-marketplace-listings-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/trovevault~olx-marketplace-listings-scraper/run-sync": {
"post": {
"operationId": "run-sync-trovevault-olx-marketplace-listings-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",
"required": [
"query",
"countries"
],
"properties": {
"query": {
"title": "Search Query",
"minLength": 1,
"type": "string",
"description": "Keyword or phrase to search for in listing titles and descriptions, for example iPhone 15, mountain bike, or apartment Lisbon.",
"default": "iPhone 15"
},
"countries": {
"title": "Countries",
"minItems": 1,
"uniqueItems": true,
"type": "array",
"description": "OLX country marketplaces to search with the same keyword. Results from every selected country are normalized into one dataset.",
"items": {
"type": "string",
"enum": [
"ba",
"br",
"bg",
"in",
"kz",
"pk",
"pl",
"pt",
"ro",
"ua",
"uz"
],
"enumTitles": [
"Bosnia and Herzegovina",
"Brazil",
"Bulgaria",
"India",
"Kazakhstan",
"Pakistan",
"Poland",
"Portugal",
"Romania",
"Ukraine",
"Uzbekistan"
]
},
"default": [
"pt"
]
},
"category": {
"title": "Category",
"enum": [
"all",
"vehicles",
"property",
"electronics",
"home-garden",
"fashion",
"jobs",
"services",
"animals",
"sports-hobbies",
"kids",
"business-industrial"
],
"type": "string",
"description": "Optional normalized category filter. The Actor maps this selection to the closest category available in every chosen OLX marketplace.",
"default": "all"
},
"location": {
"title": "Location",
"type": "string",
"description": "Optional city, region, state, or district name. Listings are filtered when the marketplace exposes a matching public location."
},
"minPrice": {
"title": "Minimum Price",
"minimum": 0,
"type": "number",
"description": "Optional minimum listing price, applied independently in each marketplace's local currency."
},
"maxPrice": {
"title": "Maximum Price",
"minimum": 0,
"type": "number",
"description": "Optional maximum listing price, applied independently in each marketplace's local currency."
},
"sort": {
"title": "Sort Results",
"enum": [
"relevance",
"newest",
"price-asc",
"price-desc"
],
"type": "string",
"description": "Choose the preferred result order. Availability depends on the selected marketplace; the Actor preserves marketplace order when a native sort is unavailable.",
"default": "relevance"
},
"maxResults": {
"title": "Maximum Results per Country",
"minimum": 1,
"maximum": 1000,
"type": "integer",
"description": "Maximum number of listings to save from each selected country. The total can reach this value multiplied by the number of countries, so higher values take longer and cost more.",
"default": 10
},
"proxyConfiguration": {
"title": "Proxy Configuration",
"type": "object",
"description": "Proxy settings used for Brazil, India, and Pakistan. The default residential proxy improves access but adds proxy usage charges; it is ignored for other marketplaces.",
"default": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
},
"datasetId": {
"title": "Dataset ID",
"type": "string",
"description": "Optional existing Apify dataset ID. Each result is appended to that dataset as well as this run's default dataset."
},
"runId": {
"title": "Run ID",
"type": "string",
"description": "Optional parent workflow identifier copied into every output row and the run summary."
}
}
},
"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
}
}
}
}
}
}
}
}
}
}
```