// docs

OLX PLP

Extrai listagem de anuncios da OLX com URL pronta opcional ou filtros por keyword, categoria, regiao/cidade, ordenacao e faixa de preco.

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.

Quando a entidade consultada não existe na origem, o extract e a tool MCP retornam 200 com data: null e notFound: true. Esse caso é tratado como resposta concluída, não como erro de servidor.

Chamada HTTP

cURL

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",
  "url": "https://www.olx.com.br/imoveis/terrenos/estado-sc/oeste-de-santa-catarina/urubici?q=terreno&o=2"
}'

Chamada MCP

A mesma seam também aparece no MCP hospedado como uma tool dedicada. Os argumentos reaproveitam os campos do extract, mas target e type já ficam fixos pela tool.

Ver guia completo do MCP

Endpoint

POST /v1/mcp

Tool name

olx_com_br_plp

Auth

Bearer ou X-API-Key

olx_com_br_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "olx_com_br_plp",
    "arguments": {
      "url": "https://www.olx.com.br/imoveis/terrenos/estado-sc/oeste-de-santa-catarina/urubici?q=terreno&o=2",
      "executionId": "exec_example_123"
    }
  }
}

Possibilidades de input

Campos suportados nesta API do POST /v1/extract, com regras específicas de obrigatoriedade e condicionais.

Campo	Tipo	Status	Regra	Default	Exemplo
url URL alvo da extração. Para alguns PLPs pode ser omitida quando a API monta a URL a partir de outros campos.	string (URL)	Opcional	Opcional. Quando enviada, deve apontar para uma listagem da OLX e sobrescreve keyword/state/city/region/categoryPath/sort/price/page do payload.	-	https://www.mercadolivre.com.br/p/MLB123456
keyword Palavra-chave para buscas PLP. Em Google Search ela representa a query enviada ao Google; em Booking PLP é obrigatória; em outros PLPs pode substituir a URL.	string	Condicional	Usado quando url nao e enviada. Nesse modo, e opcional se categoryPath, city ou region forem enviados.	-	iphone 15 pro max
region Regiao textual para buscas OLX PLP (ex.: Regiao de Bauru e Marilia).	string	Opcional	Regiao textual (ex.: Regiao de Bauru e Marilia). O backend normaliza para slug da OLX quando url nao e enviada.	-	Regiao de Bauru e Marilia
categoryPath Segmentos de categoria da OLX PLP separados por barra (ex.: informatica/notebooks).	string (path)	Opcional	Path da categoria (ex.: informatica/notebooks). Segmentos sao normalizados para slug quando url nao e enviada.	-	informatica/notebooks
city Cidade usada em Webmotors PLP e opcionalmente em Catho PLP (deve vir em par com state).	string	Opcional	Cidade para detalhar o recorte da busca (ex.: Bauru) quando url nao e enviada.	-	Sao Paulo
state UF usada em Webmotors PLP e opcionalmente em Catho PLP (deve vir em par com city).	string (UF 2 letras)	Condicional	Obrigatoria quando url nao e enviada. Use UF com 2 letras no formato XX (ex: PR, SP, RJ).	-	SP
priceMin Preço mínimo para busca no Zapimoveis PLP.	integer	Opcional	Preco minimo para filtro da OLX (query ps) quando url nao e enviada.	-	1000
priceMax Preço máximo para busca no Zapimoveis PLP.	integer	Opcional	Preco maximo para filtro da OLX (query pe) quando url nao e enviada. Deve ser >= priceMin.	-	2000
sort Ordenacao para OLX PLP, Booking Review e Hoteis Review. OLX: relevance/date/price/biggest_price/price_relevance. Booking/Hoteis Review: most_relevant/newest_first/oldest_first/score_desc/score_asc.	"relevance" \| "date" \| "price" \| "biggest_price" \| "price_relevance" \| "most_relevant" \| "newest_first" \| "oldest_first" \| "score_desc" \| "score_asc"	Opcional	Ordenacao: relevance, date, price, biggest_price ou price_relevance quando url nao e enviada.	relevance	date
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, idp, plp, quote, review ou places.	enum	Obrigatório	Sempre obrigatorio e deve ser plp.	-	pdp
page Paginacao. Em PLP inicia em 1; em review (MercadoLivre, Booking e Hoteis) inicia em 0.	integer	Opcional	Paginacao 1-based quando url nao e enviada. Com url, avance pela propria query string da OLX (ex.: o=2).	1	2

Exemplos de request

Busca OLX - URL especifica de listagem

Usa uma URL pronta da OLX e sobrescreve os filtros montados pelo payload.

Busca OLX - URL especifica de listagem

{
  "target": "olx.com.br",
  "type": "plp",
  "url": "https://www.olx.com.br/imoveis/terrenos/estado-sc/oeste-de-santa-catarina/urubici?q=terreno&o=2"
}

Busca OLX - relevantes por estado

Busca base por keyword e UF, mantendo ordenacao por relevancia.

Busca OLX - relevantes por estado

{
  "target": "olx.com.br",
  "type": "plp",
  "keyword": "iphone",
  "state": "PR",
  "page": 1
}

Busca OLX - recentes com categoria/regiao/cidade

Usa categoryPath + region + city e sort=date para reproduzir URLs mais especificas como /informatica/notebooks/estado-sp/...&sf=1.

Busca OLX - recentes com categoria/regiao/cidade

{
  "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
}

Busca OLX - pagina 2 mantendo filtros

Mesmo conjunto de filtros, avancando para page=2.

Busca OLX - pagina 2 mantendo filtros

{
  "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
}

Schema de response (leaf paths)

Mapa de paths de saída com tipo esperado para esta API.

responseSchema

{
  "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": "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",
  "data.sort": "string"
}

Exemplo de response

responseExample

{
  "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/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": "1486619109",
        "url": "https://pr.olx.com.br/regiao-de-maringa/celulares/iphone-14-pro-max-128gb-roxo-profundo-100-bateria-impecavel-1486619109",
        "title": "Notebook Acer",
        "category": "Notebooks",
        "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
      }
    ],
    "sort": "date"
  }
}

Referência completa de campos

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.	Notebooks
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.	1486619109
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.	Notebook Acer
data.items[].url	string	URL pública do anúncio.	https://pr.olx.com.br/regiao-de-maringa/celulares/iphone-14-pro-max-128gb-roxo-profundo-100-bateria-impecavel-1486619109
data.nextPage	number	Próxima página disponível.	2
data.nextPageUrl	string	URL completa da proxima pagina preservando os filtros atuais.	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 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.	1
data.query	string	Keyword aplicada na busca (pode ser null quando nao enviada).	notebook
data.requestUrl	string	URL efetivamente consultada no upstream.	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	Quantidade de resultados por página.	50
data.sort	string	Ordenacao efetiva aplicada pela OLX (relevance, date, price, biggest_price ou price_relevance).	date
data.source	string	Fonte da extração.	olx.com.br
data.state	string	UF usada para montar o path estado-xx.	SP
data.totalResults	number	Quantidade total de anúncios para a busca.	30
data.type	string	Tipo da extração.	plp
data.url	string	URL canônica da busca.	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)	Campo executionId retornado no payload de resposta.	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)	Campo requestId retornado no payload de resposta.	4a69e15e-9a74-4eb4-9387-62de9424df11

Erros comuns

Respostas com notFound: true não entram nesta tabela, porque retornam sucesso HTTP 200.

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.