// docs
Extracts listings from OLX with optional ready-made URL or national filters/by UF, keyword, category, region/city, sorting and price range.
olx.com.br:plp · 1 credit per request
Standard credit cost. Your account pricing is shown in the sandbox.
Try this operation in the sandbox
curl -X POST https://api.geckoapi.com.br/v1/extract \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target": "olx.com.br",
"type": "plp",
"url": "https://www.olx.com.br/celulares?q=iphone&sf=1&opst=2&o=2"
}'Keep your API key on your server. See the quickstart for authentication and response handling.
The hosted MCP tool fixes target and type for this operation. Its remaining arguments use the same input rules as Extract.
POST /v1/mcp · Bearer or X-API-Key authentication
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "olx_com_br_plp",
"arguments": {
"url": "https://www.olx.com.br/celulares?q=iphone&sf=1&opst=2&o=2",
"executionId": "exec_example_123"
}
}
}Conditional fields depend on the alternatives and constraints in the rule column. Fields marked unsupported are omitted.
| Field | Type | Requirement | Rule | Default | Example |
|---|---|---|---|---|---|
| url URL extraction target. For some PLPs it can be omitted when API assembles URL from other fields. | string (URL) | Optional | Optional. When submitted, it must point to a state or national listing of OLX; URL and its query string see the source of truth and overwrite the other payload filters. | - | https://www.olx.com.br/celulares?q=iphone&sf=1&opst=2&o=2 |
| keyword Keyword for PLP searches. In Google Search it represents the query sent to Google; in Booking PLP is mandatory; in other PLPs it can replace URL. | string | Conditional | Used when url is not sent. In this mode, it is optional if categoryPath, city or region are sent. | - | iphone |
| region Query region. The format depends on API; Temu PDP accepts br (Brazil), us (United States), uk (United Kingdom) and co (Colombia); PLP accepts br, us and uk. The default of Temu without country in URL is br and OLX accepts a textual region. | string | Optional | Textual region (e.g.: Bauru and Marilia Region). The backend normalizes to OLX slug when url is not sent. | - | Regiao de Bauru e Marilia |
| categoryPath OLX PLP category segments separated by a slash (e.g.: IT/notebooks). | string (path) | Optional | Category path (e.g.: IT/notebooks). Segments are normalized to slug when url is not sent. | - | celulares |
| city City used in structured searches for properties and vehicles and optionally in Catho PLP. In VivaReal, it requires state. | string | Optional | City to detail the search selection (e.g.: Bauru) when url is not sent. | - | Bauru |
| state UF used in structured searches for properties and vehicles and optionally in Catho PLP. | string (UF 2 letters) | Conditional | Optional for national searches for keyword/categoryPath. Mandatory when city or region is shipped. Use UF with 2 letters in the format XX (ex: PR, SP, RJ). | - | PR |
| priceMin Minimum price for PLP searches for properties and vehicles. | integer | Optional | Minimum price for OLX filter (query ps) when url is not sent. | - | 1000 |
| priceMax Maximum price for PLP searches for properties and vehicles. | integer | Optional | Maximum price for OLX filter (query pe) when url is not sent. Must be >= priceMin. | - | 3000 |
| sort Ordering for VivaReal, Chaves na Mão, OLX and Webmotors PLP, Booking Review and Hotels Review. VivaReal: relevance/date/price/biggest_price/biggest_area. Webmotors: relevance/price/biggest_price/year_desc/mileage_asc. OLX: relevance/date/price/biggest_price/price_relevance. Booking/Hotels Review: most_relevant/newest_first/oldest_first/score_desc/score_asc. | "relevance" | "date" | "price" | "biggest_price" | "biggest_area" | "price_relevance" | "most_relevant" | "newest_first" | "oldest_first" | "score_desc" | "score_asc" | "year_desc" | "mileage_asc" | Optional | Ordering: relevance, date, price, biggest_price or price_relevance when url is not sent. | relevance | date |
| target Target source for extraction. | enum | Required | Always mandatory and must be olx.com.br. | - | olx.com.br |
| type Extraction type: pdp, idp, plp, ilp, quote, review or places. | enum | Required | Always mandatory and must be plp. | - | plp |
| page Pagination. In PLP, including Trivago, and in Reclame AQUI ILP starts in 1; in review (MercadoLivre, Booking and Hotels) starts in 0. The Reclame AQUI ILP even accepts the page 100. | integer | Optional | 1-based pagination when url is not sent. With url, proceed through the query string from OLX (e.g. o=2). | 1 | 2 |
Uses a ready-made national URL from OLX and preserves filters from the string query, such as delivery, ordering and page.
{
"target": "olx.com.br",
"type": "plp",
"url": "https://www.olx.com.br/celulares?q=iphone&sf=1&opst=2&o=2"
}Omits state to search throughout Brazil for keyword and/or categoryPath.
{
"target": "olx.com.br",
"type": "plp",
"keyword": "iphone",
"categoryPath": "celulares",
"sort": "date",
"page": 2
}Base search for keyword and UF, maintaining ordering by relevance.
{
"target": "olx.com.br",
"type": "plp",
"keyword": "iphone",
"state": "PR",
"page": 1
}Uses categoryPath + region + city and sort=date to reproduce more specific URLs such as /informatica/notebooks/estado-sp/...&sf=1.
{
"target": "olx.com.br",
"type": "plp",
"keyword": "notebook",
"categoryPath": "informatica/notebooks",
"state": "SP",
"region": "Regiao de Bauru e Marilia",
"city": "Bauru",
"sort": "date",
"priceMin": 1000,
"priceMax": 3000,
"page": 1
}Same filter set, moving forward to page=2.
{
"target": "olx.com.br",
"type": "plp",
"keyword": "notebook",
"categoryPath": "informatica/notebooks",
"state": "SP",
"region": "Regiao de Bauru e Marilia",
"city": "Bauru",
"sort": "date",
"page": 2
}Leaf paths and expected types. Field names and enum values are part of the API contract.
{
"requestId": "string (uuid)",
"executionId": "string (uuid)",
"notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
"data.source": "string",
"data.type": "string",
"data.parser": "\"1.0.0\"",
"data.url": "string",
"data.requestUrl": "string",
"data.extractedAt": "string (iso datetime)",
"data.query": "string",
"data.state": "string | null",
"data.totalResults": "number",
"data.primaryResults": "number",
"data.page": "number",
"data.resultsPerPage": "number",
"data.offset": "number",
"data.nextPage": "number",
"data.nextPageUrl": "string",
"data.items[].position": "number",
"data.items[].id": "string",
"data.items[].url": "string",
"data.items[].title": "string",
"data.items[].category": "string",
"data.items[].categoryId": "number",
"data.items[].condition": "string",
"data.items[].price": "number",
"data.items[].priceDisplay": "string",
"data.items[].oldPrice": "number (optional)",
"data.items[].oldPriceDisplay": "string (optional)",
"data.items[].featured": "boolean",
"data.items[].professionalAd": "boolean",
"data.items[].chatEnabled": "boolean",
"data.items[].listedAt": "string (iso datetime)",
"data.items[].listedAtEpoch": "number",
"data.items[].imageCount": "number",
"data.items[].images[].url": "string",
"data.items[].images[].webpUrl": "string",
"data.items[].location.city": "string",
"data.items[].location.state": "string",
"data.items[].location.neighborhood": "string",
"data.items[].location.ddd": "string",
"data.items[].location.display": "string",
"data.items[].properties[].name": "string",
"data.items[].properties[].label": "string",
"data.items[].properties[].value": "string",
"data.items[].olxPayEnabled": "boolean",
"data.items[].olxDeliveryEnabled": "boolean",
"data.sort": "string"
}Illustrative response. Product names, reviews and other source content retain their original language. Missing and null values do not imply zero stock, free shipping or zero reviews.
{
"requestId": "4a69e15e-9a74-4eb4-9387-62de9424df11",
"executionId": "4a69e15e-9a74-4eb4-9387-62de9424df12",
"data": {
"source": "olx.com.br",
"type": "plp",
"parser": "1.0.0",
"url": "https://www.olx.com.br/informatica/notebooks/estado-sp/regiao-de-bauru-e-marilia/bauru?q=notebook&sf=1&ps=1000&pe=3000",
"requestUrl": "https://www.olx.com.br/informatica/notebooks/estado-sp/regiao-de-bauru-e-marilia/bauru?q=notebook&sf=1&ps=1000&pe=3000",
"extractedAt": "2026-02-21T15:04:00.000Z",
"query": "notebook",
"state": "SP",
"totalResults": 30,
"primaryResults": 1,
"page": 1,
"resultsPerPage": 50,
"offset": 0,
"nextPage": 2,
"nextPageUrl": "https://www.olx.com.br/informatica/notebooks/estado-sp/regiao-de-bauru-e-marilia/bauru?q=notebook&sf=1&ps=1000&pe=3000&o=2",
"items": [
{
"position": 1,
"id": "1506913293",
"url": "https://pr.olx.com.br/regiao-de-maringa/celulares/iphone-14-128gb-branco-1506913293",
"title": "iPhone 14 128GB Branco",
"category": "Celulares e Smartphones",
"categoryId": 3060,
"condition": "Usado - Excelente",
"price": 2200,
"priceDisplay": "R$ 2.200",
"featured": false,
"professionalAd": false,
"chatEnabled": true,
"listedAt": "2026-06-01T02:37:38.000Z",
"listedAtEpoch": 1780281458,
"imageCount": 5,
"images": [
{
"url": "https://img.olx.com.br/images/38/388649764309681.jpg",
"webpUrl": "https://img.olx.com.br/images/38/388649764309681.webp"
}
],
"location": {
"city": "Maringá",
"state": "PR",
"neighborhood": "Parque da Gávea",
"ddd": "44",
"display": "Maringá, Parque da Gávea"
},
"properties": [
{
"name": "electronics_condition",
"label": "Condição",
"value": "Usado - Excelente"
}
],
"olxPayEnabled": true,
"olxDeliveryEnabled": true
}
],
"sort": "date"
}
}| Path | Type | Description | Example |
|---|---|---|---|
| data.extractedAt | string (iso datetime) | Extraction Timestamp UTC. | 2026-02-21T15:04:00.000Z |
| data.items[].category | string | Ad category. | Celulares e Smartphones |
| data.items[].categoryId | number | ID category numeric. | 3060 |
| data.items[].chatEnabled | boolean | Indicates whether chat is enabled. | true |
| data.items[].condition | string | Item condition when available. | Usado - Excelente |
| data.items[].featured | boolean | Highlighted ad flag. | false |
| data.items[].id | string | ID OLX listing. | 1506913293 |
| data.items[].imageCount | number | Number of images in the ad. | 5 |
| data.items[].images[].url | string | URL JPG of the image. | https://img.olx.com.br/images/38/388649764309681.jpg |
| data.items[].images[].webpUrl | string | URL WEBP of the image. | https://img.olx.com.br/images/38/388649764309681.webp |
| data.items[].listedAt | string (iso datetime) | Date/time ISO published. | 2026-06-01T02:37:38.000Z |
| data.items[].listedAtEpoch | number | Unix timestamp (seconds) of publication. | 1780281458 |
| data.items[].location.city | string | City of advertisement. | Maringá |
| data.items[].location.ddd | string | DDD of the location. | 44 |
| data.items[].location.display | string | Location text displayed on the card. | Maringá, Parque da Gávea |
| data.items[].location.neighborhood | string | Ad neighborhood. | Parque da Gávea |
| data.items[].location.state | string | UF. | PR |
| data.items[].oldPrice | number (optional) | Old price normalized when displayed. | N/A |
| data.items[].oldPriceDisplay | string (optional) | Old price in textual format. | N/A |
| data.items[].olxDeliveryEnabled | boolean | Indicates whether OLX Delivery is enabled on the card. | true |
| data.items[].olxPayEnabled | boolean | Indicates whether OLX Pay is enabled on the card. | true |
| data.items[].position | number | Absolute position of the item in the search. | 1 |
| data.items[].price | number | Standard numeric price. | 2200 |
| data.items[].priceDisplay | string | Price formatted as displayed on the card. | R$ 2.200 |
| data.items[].professionalAd | boolean | Indicates whether the ad is professional. | false |
| data.items[].properties[].label | string | Readable property label. | Condição |
| data.items[].properties[].name | string | Technical property identifier. | electronics_condition |
| data.items[].properties[].value | string | Property value. | Usado - Excelente |
| data.items[].title | string | Ad title. | iPhone 14 128GB Branco |
| data.items[].url | string | URL ad public. | https://pr.olx.com.br/regiao-de-maringa/celulares/iphone-14-128gb-branco-1506913293 |
| data.nextPage | number | Next page available. | 2 |
| data.nextPageUrl | string | URL complete on the next page preserving the current filters. | https://www.olx.com.br/informatica/notebooks/estado-sp/regiao-de-bauru-e-marilia/bauru?q=notebook&sf=1&ps=1000&pe=3000&o=2 |
| data.offset | number | Offset calculated by paging. | 0 |
| data.page | number | Page returned. | 1 |
| data.parser | "1.0.0" | Stable version of the API response format. | 1.0.0 |
| data.primaryResults | number | Number of valid ads returned on the current page. | 1 |
| data.query | string | Keyword applied in the search (can be null when not sent). | notebook |
| data.requestUrl | string | Same value as `data.url`; never exposes the queried internal endpoint. | https://www.olx.com.br/informatica/notebooks/estado-sp/regiao-de-bauru-e-marilia/bauru?q=notebook&sf=1&ps=1000&pe=3000 |
| data.resultsPerPage | number | Number of results per page. | 50 |
| data.sort | string | Effective ordering applied by OLX (relevance, date, price, biggest_price or price_relevance). | date |
| data.source | string | Extraction source. | olx.com.br |
| data.state | string | null | UF used to set up the state-xx path, or null in national searches. | SP |
| data.totalResults | number | Total number of ads for the search. | 30 |
| data.type | string | Extraction type. | plp |
| data.url | string | URL canonical search. | https://www.olx.com.br/informatica/notebooks/estado-sp/regiao-de-bauru-e-marilia/bauru?q=notebook&sf=1&ps=1000&pe=3000 |
| executionId | string (uuid) | Field executionId returned in the response payload. | 4a69e15e-9a74-4eb4-9387-62de9424df12 |
| notFound | boolean (optional; true when the upstream entity was not found and data is null) | Present and true when the upstream entity was not found. In this case data is null and the request still completes successfully. | N/A |
| requestId | string (uuid) | Field requestId returned in the response payload. | 4a69e15e-9a74-4eb4-9387-62de9424df11 |
When supported by this operation, an entity not found upstream can return HTTP 200 with data: null and notFound: true. Check the documented response fields before interpreting an empty result. Source-specific behavior and exceptions are described above.
| HTTP status | Error code | Meaning |
|---|---|---|
| 400 | INVALID_PAYLOAD | Invalid JSON or a request that violates the documented validation rules. |
| 401 | UNAUTHORIZED | Missing authorization or an invalid API key or token. |
| 402 | INSUFFICIENT_CREDITS | The account has insufficient credits for this operation. |
| 403 | FORBIDDEN | The account does not have access, or the API is temporarily disabled. |
| 409 | EXECUTION_CONFLICT | The execution identifier conflicts with an incompatible execution state. |
| 429 | RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS | A rate limit or simultaneous request limit was exceeded. |
| 5xx | UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_FUNCTION_ERROR | An upstream, worker or gateway failure. Failed requests follow the platform refund policy. |