// docs
Extrai listagem de anúncios da OLX por keyword e UF (formato XX), com paginação por página.
Nota importante: alguns campos podem retornar null em produção,
dependendo da página de origem. Nesta documentação, os exemplos de output são
preenchidos intencionalmente com valores não nulos para facilitar integração.
curl -X POST https://api.geckoapi.com.br/v1/extract \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"target": "olx.com.br",
"type": "plp",
"keyword": "iphone",
"state": "PR",
"page": 1
}'
Campos suportados nesta API do POST /v1/extract,
com regras específicas de obrigatoriedade e condicionais.
| Campo | Tipo | Status | Regra | Default | Exemplo |
|---|---|---|---|---|---|
| keyword Palavra-chave para buscas PLP. Em Booking PLP é obrigatória; em outros PLPs pode substituir a URL. | string | Obrigatório | Termo de busca da OLX. | - | iphone 15 pro max |
| state UF usada em Webmotors PLP e opcionalmente em Catho PLP (deve vir em par com city). | string (UF 2 letras) | Obrigatório | UF com 2 letras no formato XX (ex: PR, SP, RJ). | - | SP |
| target Fonte alvo da extração. | enum | Obrigatório | Sempre obrigatorio e deve ser olx.com.br. | - | mercadolivre.com.br |
| type Tipo da extração: pdp, plp, review ou places. | enum | Obrigatório | Sempre obrigatorio e deve ser plp. | - | pdp |
| page Paginação. Em PLP inicia em 1; em MercadoLivre review inicia em 0. | integer | Opcional | Paginação 1-based. | 1 | 2 |
Informe keyword e state (UF com 2 letras). A página 1 não exige parâmetro o na URL upstream.
{
"target": "olx.com.br",
"type": "plp",
"keyword": "iphone",
"state": "PR",
"page": 1
}Mesmo filtro, avançando para a segunda página da listagem.
{
"target": "olx.com.br",
"type": "plp",
"keyword": "iphone",
"state": "PR",
"page": 2
}Mapa de paths de saída com tipo esperado para esta API.
{
"requestId": "string (uuid)",
"executionId": "string (uuid)",
"data.source": "string",
"data.type": "string",
"data.parser": "string",
"data.url": "string",
"data.requestUrl": "string",
"data.extractedAt": "string (iso datetime)",
"data.query": "string",
"data.state": "string",
"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",
"data.items[].oldPriceDisplay": "string",
"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"
}{
"requestId": "4a69e15e-9a74-4eb4-9387-62de9424df11",
"executionId": "4a69e15e-9a74-4eb4-9387-62de9424df12",
"data": {
"source": "olx.com.br",
"type": "plp",
"parser": "next_data",
"url": "https://www.olx.com.br/estado-pr?q=iphone",
"requestUrl": "https://www.olx.com.br/estado-pr?q=iphone",
"extractedAt": "2026-02-21T15:04:00.000Z",
"query": "iphone",
"state": "PR",
"totalResults": 4663,
"primaryResults": 50,
"page": 1,
"resultsPerPage": 50,
"offset": 0,
"nextPage": 2,
"nextPageUrl": "https://www.olx.com.br/estado-pr?q=iphone&o=2",
"items": [
{
"position": 1,
"id": "1470653416",
"url": "https://pr.olx.com.br/regiao-de-curitiba-e-paranagua/celulares/iphone-17-pro-256gb-e-sim-laranja-loja-fisica-com-garantia-nota-foscam-br-cor-laranja-1470653416",
"title": "iPhone 17 Pro 256GB | E-Sim - Laranja",
"category": "Celulares e Smartphones",
"categoryId": 3060,
"condition": "Novo",
"price": 7749,
"priceDisplay": "R$ 7.749",
"oldPrice": 8199,
"oldPriceDisplay": "R$ 8.199",
"featured": false,
"professionalAd": true,
"chatEnabled": true,
"listedAt": "2026-02-21T03:16:20.000Z",
"listedAtEpoch": 1771598180,
"imageCount": 2,
"images": [
{
"url": "https://img.olx.com.br/images/20/201655000258589.jpg",
"webpUrl": "https://img.olx.com.br/images/20/201655000258589.webp"
}
],
"location": {
"city": "Curitiba",
"state": "PR",
"neighborhood": "Agua Verde",
"ddd": "41",
"display": "Curitiba, Agua Verde - DDD 41"
},
"properties": [
{
"name": "electronics_condition",
"label": "Condição",
"value": "Novo"
}
],
"olxPayEnabled": false,
"olxDeliveryEnabled": false
}
]
}
}| Path | Tipo | Descrição | Exemplo |
|---|---|---|---|
| data.extractedAt | string (iso datetime) | Timestamp UTC da extração. | 2026-02-21T15:04:00.000Z |
| data.items[].category | string | Categoria do anúncio. | Celulares e Smartphones |
| data.items[].categoryId | number | ID numérico da categoria. | 3060 |
| data.items[].chatEnabled | boolean | Indica se chat está habilitado. | true |
| data.items[].condition | string | Condição do item quando disponível. | Novo |
| data.items[].featured | boolean | Flag de anúncio destacado. | false |
| data.items[].id | string | ID de listagem da OLX. | 1470653416 |
| data.items[].imageCount | number | Quantidade de imagens do anúncio. | 2 |
| data.items[].images[].url | string | URL JPG da imagem. | https://img.olx.com.br/images/20/201655000258589.jpg |
| data.items[].images[].webpUrl | string | URL WEBP da imagem. | https://img.olx.com.br/images/20/201655000258589.webp |
| data.items[].listedAt | string (iso datetime) | Data/hora ISO da publicação. | 2026-02-21T03:16:20.000Z |
| data.items[].listedAtEpoch | number | Timestamp unix (segundos) da publicação. | 1771598180 |
| data.items[].location.city | string | Cidade do anúncio. | Curitiba |
| data.items[].location.ddd | string | DDD da localidade. | 41 |
| data.items[].location.display | string | Texto de localização exibido no card. | Curitiba, Agua Verde - DDD 41 |
| data.items[].location.neighborhood | string | Bairro do anúncio. | Agua Verde |
| data.items[].location.state | string | UF do anúncio. | PR |
| data.items[].oldPrice | number | Preço antigo normalizado, quando exibido. | 8199 |
| data.items[].oldPriceDisplay | string | Preço antigo em formato textual. | R$ 8.199 |
| data.items[].olxDeliveryEnabled | boolean | Indica se OLX Delivery está habilitado no card. | false |
| data.items[].olxPayEnabled | boolean | Indica se OLX Pay está habilitado no card. | false |
| data.items[].position | number | Posição absoluta do item na busca. | 1 |
| data.items[].price | number | Preço numérico normalizado. | 7749 |
| data.items[].priceDisplay | string | Preço formatado conforme exibido no card. | R$ 7.749 |
| data.items[].professionalAd | boolean | Indica se o anúncio é profissional. | true |
| data.items[].properties[].label | string | Rótulo legível da propriedade. | Condição |
| data.items[].properties[].name | string | Identificador técnico da propriedade. | electronics_condition |
| data.items[].properties[].value | string | Valor da propriedade. | Novo |
| data.items[].title | string | Título do anúncio. | iPhone 17 Pro 256GB | E-Sim - Laranja |
| data.items[].url | string | URL pública do anúncio. | https://pr.olx.com.br/regiao-de-curitiba-e-paranagua/celulares/iphone-17-pro-256gb-e-sim-laranja-loja-fisica-com-garantia-nota-foscam-br-cor-laranja-1470653416 |
| data.nextPage | number | Próxima página disponível. | 2 |
| data.nextPageUrl | string | URL completa da próxima página. | https://www.olx.com.br/estado-pr?q=iphone&o=2 |
| data.offset | number | Offset calculado pela paginação. | 0 |
| data.page | number | Página retornada. | 1 |
| data.parser | string | Parser utilizado no backend. | next_data |
| data.primaryResults | number | Quantidade de anúncios válidos retornados na página atual. | 50 |
| data.query | string | Keyword aplicada na busca. | iphone |
| data.requestUrl | string | URL efetivamente consultada no upstream. | https://www.olx.com.br/estado-pr?q=iphone |
| data.resultsPerPage | number | Quantidade de resultados por página. | 50 |
| data.source | string | Fonte da extração. | olx.com.br |
| data.state | string | UF usada para montar o path estado-xx. | PR |
| data.totalResults | number | Quantidade total de anúncios para a busca. | 4663 |
| data.type | string | Tipo da extração. | plp |
| data.url | string | URL canônica da busca. | https://www.olx.com.br/estado-pr?q=iphone |
| executionId | string (uuid) | Campo executionId retornado no payload de resposta. | 4a69e15e-9a74-4eb4-9387-62de9424df12 |
| requestId | string (uuid) | Campo requestId retornado no payload de resposta. | 4a69e15e-9a74-4eb4-9387-62de9424df11 |
| Status | errorCode | Quando acontece |
|---|---|---|
| 400 | INVALID_PAYLOAD | JSON inválido ou violação das regras de validação do payload. |
| 401 | UNAUTHORIZED | Header Authorization ausente ou token/chave inválida. |
| 402 | INSUFFICIENT_CREDITS | Saldo de créditos insuficiente para a API solicitada. |
| 403 | FORBIDDEN | Usuário sem acesso ou API temporariamente desabilitada. |
| 409 | EXECUTION_CONFLICT | executionId conflita com uma execução em estado incompatível. |
| 429 | RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS | Limite de taxa ou limite de requisições em voo excedido. |
| 5xx | UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_INVOCATION_FAILED / WORKER_FUNCTION_ERROR / WORKER_INVALID_RESPONSE / INTERNAL_ERROR | Falha de servidor no worker, provider/proxy ou gateway. Nesses casos os créditos são estornados automaticamente. |
