olx-search-cli

Extraia dados estruturados de anúncios dos resultados de busca da OLX Brasil — sem chave de API, sem navegador, sem scraping.

Como funciona

Em vez de usar a API autenticada da OLX ou um navegador headless, esta ferramenta busca o HTML público da página de busca e extrai o JSON __NEXT_DATA__ embutido que o próprio frontend Next.js da OLX usa para hidratar a UI.

Isso te entrega a resposta inicial da busca — anúncios, preços, localização, imagens e paginação — com uma única requisição HTTP.

A ferramenta então enriquece automaticamente cada resultado, buscando a página de cada anúncio em paralelo para extrair:

• Descrição completa do anúncio
• Todas as fotos do anúncio (via dados estruturados LD+JSON e RSC)
• Características (propriedades/atributos do anúncio)
• Nome do vendedor

Sem chave de API. Sem fluxo OAuth. Sem Playwright/Puppeteer. Sem API REST com limite de taxa. Sem seletores CSS frágeis. Só um fetch() e parse de JSON.

Instalação

Uso da CLI

Opções

Flag	Curto	Descrição	Padrão
--limit <n>	-l	Máximo de resultados	20
--sort <order>		price_asc, price_desc, date, relevance	—
--state <uf>		Filtrar por estado(s) (UF). Único ou separado por vírgula: sp, rj,mg,sp	—
--category <slug>		Filtrar por categoria, ex.: celulares, carros-vans-e-utilitarios	—
--list-categories		Listar todas as categorias válidas e sair	false
--strict		Filtragem inteligente: garante que todos os termos da busca aparecem no anúncio	false
--format <type>	-f	json, table, jsonl, csv	json
--pretty		JSON formatado	false
--raw		Saída com pageProps bruto completo	false
--fields <list>		Lista de campos separados por vírgula	todos
--timeout <ms>		Timeout da requisição HTTP	15000
--concurrency <n>		Máx. de requisições de detalhe em paralelo	5
--web	-w	Abrir resultados como página web interativa no browser	false

Categorias aceitas

Use o valor da coluna Slug na flag --category.

Slug	Nome
imoveis	Imóveis
imoveis/venda	Venda - casas e apartamentos
imoveis/aluguel	Aluguel - casas e apartamentos
imoveis/temporada	Temporada
imoveis/terrenos	Terrenos, sítios e fazendas
imoveis/comercio-e-industria	Comércio e indústria
imoveis/lancamentos	Imóvel Novo
autos-e-pecas	Autos
autos-e-pecas/carros-vans-e-utilitarios	Carros, vans e utilitários
autos-e-pecas/motos	Motos
autos-e-pecas/onibus	Ônibus
autos-e-pecas/caminhoes	Caminhões
autos-e-pecas/barcos-e-aeronaves	Barcos e aeronaves
autos-e-pecas/pecas-e-acessorios	Autopeças
autos-e-pecas/pecas-e-acessorios/carros-vans-e-utilitarios	Peças para carros, vans e utilitários
autos-e-pecas/pecas-e-acessorios/motos	Peças para motos
autos-e-pecas/pecas-e-acessorios/onibus	Peças para ônibus
autos-e-pecas/pecas-e-acessorios/caminhoes	Peças para caminhões
autos-e-pecas/pecas-e-acessorios/barcos-e-aeronaves	Peças para barcos e aeronaves
para-a-sua-casa	Casa, Decoração e Utensílios
para-a-sua-casa/cama-mesa-e-banho	Tecidos de Cama, Mesa e Banho
para-a-sua-casa/decoracoes-para-casa	Decorações Para Casa
para-a-sua-casa/casa-inteligente	Casa Inteligente
para-a-sua-casa/utensilios-para-cozinha	Utensílios Para Cozinha
para-a-sua-casa/utensilios-para-banheiro-e-limpeza	Utensílios Para Banheiro e Limpeza
para-a-sua-casa/iluminacao	Iluminação
para-a-sua-casa/seguranca-residencial	Segurança Residencial
para-a-sua-casa/jardinagem-e-plantas	Jardinagem e Plantas
para-a-sua-casa/area-externa	Área Externa
moveis	Móveis
moveis/camas-e-colchoes	Camas e Colchões
moveis/sofas-e-poltronas	Sofás e Poltronas
moveis/cadeiras-de-escritorio-e-gamer	Cadeiras de Escritório e Gamer
moveis/bancos-e-cadeiras	Bancos e Cadeiras
moveis/mesas	Mesas
moveis/escrivaninhas-e-penteadeiras	Escrivaninhas e Penteadeiras
moveis/racks-e-paineis	Racks e Painéis
moveis/armarios-e-guarda-roupas	Armários e Guarda-Roupas
moveis/moveis-para-organizacao	Móveis Para Organização
eletro	Eletro
eletro/ar-condicionados	Ar-condicionados
eletro/ventiladores-e-climatizadores	Ventiladores e Climatizadores
eletro/geladeiras-e-freezers	Geladeiras e Freezers
eletro/fogoes-e-fornos	Fogões e Fornos
eletro/maquinas-de-lavar-e-secadoras	Máquinas de Lavar e Secadoras
eletro/eletroportateis-para-cozinha-e-limpeza	Eletroportáteis Para Cozinha e Limpeza
eletro/eletroportateis-para-cuidados-pessoais	Eletroportáteis Para Cuidados Pessoais
materiais-de-construcao	Materiais de Construção
materiais-de-construcao/fundacao-e-estrutura	Fundação e Estrutura
materiais-de-construcao/alvenaria	Alvenaria
materiais-de-construcao/pisos-e-revestimentos	Pisos e Revestimentos
materiais-de-construcao/portas-e-janelas	Portas e Janelas
materiais-de-construcao/cubas-e-pias	Cubas e Pias
materiais-de-construcao/torneiras-duchas-e-vasos	Torneiras, Duchas e Vasos
materiais-de-construcao/instalacoes-eletricas-e-hidraulicas	Instalações Elétricas e Hidráulicas
materiais-de-construcao/ferramentas-de-construcao	Ferramentas de Construção
materiais-de-construcao/ferramentas-de-pintura	Ferramentas de Pintura
eletronicos-e-celulares	Celulares e Telefonia
celulares	Celulares e Smartphones
eletronicos-e-celulares/acessorios-de-celular	Acessórios de Celular
eletronicos-e-celulares/pecas-de-celular	Peças de Celular
eletronicos-e-celulares/smartwatches	Smartwatches
eletronicos-e-celulares/acessorios-para-smartwatch	Acessórios Para Smartwatch
eletronicos-e-celulares/telefonia-fixa-e-sem-fio	Telefonia Fixa e Sem Fio
informatica	Informática
informatica/computadores-e-desktops	Computadores e Desktops
informatica/notebooks	Notebooks
informatica/monitores	Monitores
informatica/perifericos-e-acessorios-de-computador	Periféricos e Acessórios de Computador
informatica/pecas-de-hardware	Peças de Hardware
informatica/armazenamento	Armazenamento
informatica/memoria-ram	Memória RAM
informatica/processadores	Processadores
informatica/placas-de-video	Placas de Vídeo
informatica/conectividade-e-dispositivos-de-rede	Conectividade e Dispositivos de Rede
informatica/tablets-e-readers	Tablets e E-Readers
games	Games
games/consoles-de-video-game	Consoles de Vídeo Game
games/jogos-de-video-game	Jogos de Vídeo Game
games/acessorios-de-video-game	Peças e Acessórios de Vídeo Game
tvs-e-video	TVs e video
tvs-e-video/tvs	TVs
tvs-e-video/acessorios-para-tv	Peças e Acessórios para TV
tvs-e-video/projetores-e-telas-de-projecao	Projetores e Telas de Projeção
tvs-e-video/dvd-blu-ray-video-cassete	DVD, Blu-Ray e Vídeo Cassete
tvs-e-video/dispositivos-de-streaming	Dispositivos de Streaming
audio	Áudio
audio/fones-de-ouvido	Fones de Ouvido
audio/aparelhos-de-som	Aparelhos de Som
audio/microfones-e-gravadores	Microfones e Gravadores
audio/equipamentos-e-acessorios-de-som	Equipamentos e Acessórios de Som
cameras-e-drones	Câmeras e Drones
cameras-e-filmadoras	Câmeras e Filmadoras
acessorios-para-cameras-e-filmadoras	Acessórios para Câmeras e Filmadoras
drones	Drones
moda-e-beleza	Moda e beleza
beleza-e-saude	Beleza e Cuidados Pessoais
roupas	Roupas
bolsas-malas-e-mochilas	Bolsas, malas e mochilas
bijouteria-relogios-e-acessorios	Acessórios
calcados	Calçados
comercio-e-escritorio	Comércio
comercio-e-escritorio/equipamentos	Equipamentos Para Comércio
comercio-e-escritorio/gastronomia	Gastronomia e Hotelaria
comercio-e-escritorio/equipamento-medico	Equipamentos Médicos e Hospitalares
comercio-e-escritorio/uniformes-epis	Uniformes de Trabalho e EPIs
comercio-e-escritorio/trailers-e-carrinhos-comerciais	Trailers e carrinhos comerciais
escritorio	Escritório e Home Office
escritorio/itens-para-escritorio	Itens Para Escritório
escritorio/cadeiras-de-escritorio	Cadeiras de Escritório e Gamer
escritorio/moveis-de-escritorio	Móveis de Escritório
escritorio/papelaria	Papelaria
musica-e-hobbies	Música e hobbies
instrumentos-musicais	Instrumentos musicais
cds-dvds	CDs, DVDs etc
livros-e-revistas	Livros e revistas
antiguidades	Antiguidades
hobbies-e-colecoes	Hobbies e coleções
esportes-e-lazer	Esportes e Fitness
ciclismo	Ciclismo
esportes-e-lazer/academia-e-exercicios	Academia e Exercícios
esportes-e-lazer/acampamento	Acampamento
esportes-e-lazer/esportes-sobre-rodas	Esportes Sobre Rodas
esportes-e-lazer/quadra-e-ao-ar-livre	Esportes de Quadra e Ao Ar Livre
esportes-e-lazer/esportes-aquaticos	Esportes Aquáticos
esportes-e-lazer/roupas-esportivas	Roupas Esportivas
esportes-e-lazer/calcados-esportivos	Calçados Esportivos
esportes-e-lazer/acessorios-de-ciclismo	Acessórios de Ciclismo
artigos-infantis	Artigos infantis
artigos-infantis/roupas-infantis	Roupas Infantis
artigos-infantis/calcados-infantis	Calçados Infantis
artigos-infantis/roupas-para-bebes	Roupas para Bebês
artigos-infantis/calcados-para-bebes	Calçados Para Bebês
artigos-infantis/brinquedos	Brinquedos e Jogos
artigos-infantis/maternidade-e-bebes	Maternidade e Cuidados com o Bebê
artigos-infantis/moveis-infantis	Móveis Infantis
animais-de-estimacao	Animais de estimação
animais-de-estimacao/cachorros	Cachorros
animais-de-estimacao/gatos	Gatos
animais-de-estimacao/acessorios	Acessórios para pets
animais-de-estimacao/roedores	Roedores
animais-de-estimacao/outros-animais	Outros animais
agro-e-industria	Agro e indústria
agro-e-industria/tratores-e-maquinas-agricolas	Tratores e máquinas agrícolas
agro-e-industria/maquinas-pesadas-para-construcao	Máquinas pesadas para construção
agro-e-industria/maquinas-para-producao-industrial	Máquinas para produção industrial
agro-e-industria/pecas-para-tratores-e-maquinas	Peças para tratores e máquinas
agro-e-industria/animais-para-agropecuaria	Animais para agropecuária
agro-e-industria/producao-rural	Produção Rural
agro-e-industria/outros-itens-para-agro-e-industria	Outros itens para agro e indústria
servicos	Serviços
vagas-de-emprego	Vagas de emprego

Para imprimir essa lista no terminal:

Sites suportados

ID	País	Domínio
BR	Brasil	www.olx.com.br

Uso como biblioteca

Estrutura do item

Cada item em result.items tem este formato:

Como a extração funciona

As páginas de busca da OLX são apps Next.js renderizadas no servidor. O servidor embute a resposta completa da busca dentro de uma tag <script id="__NEXT_DATA__"> como parte dos dados de hidratação da página:

Esse objeto pageProps contém os mesmos dados que a API da OLX retornaria — títulos, preços, imagens, localização, propriedades — tudo pré-serializado em JSON dentro do HTML.

Para detalhes de cada anúncio, a ferramenta extrai o application/ld+json (dados estruturados Schema.org) e os dados RSC do React embutidos na página de detalhe de forma automática.

Processo de extração:

1. Busca o HTML da página de busca com uma única requisição GET.
2. Localiza a tag <script id="__NEXT_DATA__"> e extrai o JSON.
3. Identifica os anúncios e, para cada um, busca a página de detalhe em paralelo (respeitando a concorrência).
4. Extrai fotos, descrição e atributos via LD+JSON e dados RSC embutidos na página do anúncio.
5. Combina todos os dados em um objeto de item estruturado e limpo.

Essa abordagem é:

• Rápida — uma requisição HTTP, ~1-2 segundos no total
• Completa — busca descrição, fotos, atributos e nome do vendedor
• Confiável — faz parse de JSON estruturado, não de elementos DOM
• Zero dependências de produção — usa apenas o fetch() nativo do Node.js. (O prettier é usado estritamente para desenvolvimento; ferramentas de automação internas não são incluídas no repositório).
• Sem autenticação — sem chave de API ou OAuth

Limites de taxa

Como isso busca páginas web comuns (não a API), aplica-se o throttling padrão do servidor web:

• ~30-50 requisições/minuto a partir de um único IP costuma ser seguro
• Rajadas rápidas (100+ em segundos) podem acionar CAPTCHA ou HTTP 429
• Para uso intenso, adicione intervalo entre requisições

Isenção de responsabilidade

Este projeto não é afiliado, endossado ou mantido pela OLX.

O uso desta ferramenta é de responsabilidade exclusiva de quem a utiliza. Você deve respeitar os Termos de Uso, políticas e legislação aplicável.

Não nos responsabilizamos por bloqueios, limitações, alterações de funcionamento, perdas ou quaisquer danos decorrentes do uso deste software.

Desenvolvimento

Os scripts no package.json são voltados para o desenvolvimento do projeto:

• npm run format: Formata o código usando prettier.

Note: Scripts de automação internos (como o readyup) não são incluídos no repositório.

Licença

MIT