// docs

Zapimoveis PLP

Extrai listagem de imoveis do Zapimoveis por cidade/UF e tipo de negocio, com keyword opcional e filtros de busca.

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.

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": "zapimoveis.com.br",
  "type": "plp",
  "city": "Curitiba",
  "state": "PR",
  "businessType": "rent",
  "page": 1
}'

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
keyword Palavra-chave para buscas PLP. Em Booking PLP é obrigatória; em outros PLPs pode substituir a URL.	string	Opcional	Opcional para refinar o termo de busca.	-	iphone 15 pro max
city Cidade usada em Webmotors PLP e opcionalmente em Catho PLP (deve vir em par com state).	string	Obrigatório	Cidade da busca, usada para montar o path da URL.	-	Sao Paulo
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 (ex: PR).	-	SP
businessType Tipo de negócio usado no Zapimoveis PLP para escolher entre venda (sale) e aluguel (rent).	"sale" \| "rent"	Obrigatório	Tipo de negocio. Valores suportados: sale ou rent (sinonimos venda/aluguel tambem sao aceitos na API).	-	sale
bedrooms Filtro de quartos no Zapimoveis PLP. Aceita lista de inteiros (ex: [2,3,4]).	integer[]	Opcional	Filtro de quartos. Aceita lista de inteiros (ex: [2,3,4]).	-	[2,3,4]
bathrooms Filtro de banheiros no Zapimoveis PLP. Aceita lista de inteiros (ex: [2,3,4]).	integer[]	Opcional	Filtro de banheiros. Aceita lista de inteiros (ex: [2,3,4]).	-	[2,3,4]
parkingSpots Filtro de vagas no Zapimoveis PLP. Aceita lista de inteiros (ex: [2,3,4]).	integer[]	Opcional	Filtro de vagas. Aceita lista de inteiros (ex: [2,3,4]).	-	[2,3,4]
priceMin Preço mínimo para busca no Zapimoveis PLP.	integer	Opcional	Preco minimo. Deve ser inteiro >= 0.	-	1000
priceMax Preço máximo para busca no Zapimoveis PLP.	integer	Opcional	Preco maximo. Deve ser inteiro >= 0 e >= priceMin quando ambos forem enviados.	-	2000
areaMin Área mínima (m²) para busca no Zapimoveis PLP.	integer	Opcional	Area minima em m². Deve ser inteiro >= 0.	-	80
areaMax Área máxima (m²) para busca no Zapimoveis PLP.	integer	Opcional	Area maxima em m². Deve ser inteiro >= 0 e >= areaMin quando ambos forem enviados.	-	220
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio e deve ser zapimoveis.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

Exemplos de request

PLP sem keyword

Fluxo recomendado: envie city, state, businessType e page. keyword e opcional.

PLP sem keyword

{
  "target": "zapimoveis.com.br",
  "type": "plp",
  "city": "Curitiba",
  "state": "PR",
  "businessType": "rent",
  "page": 1
}

PLP com filtros de imóvel

Exemplo com filtros de quartos, banheiros, vagas, faixa de preco e area.

PLP com filtros de imóvel

{
  "target": "zapimoveis.com.br",
  "type": "plp",
  "city": "Curitiba",
  "state": "PR",
  "businessType": "rent",
  "bedrooms": [
    2,
    3,
    4
  ],
  "bathrooms": [
    2,
    3,
    4
  ],
  "parkingSpots": [
    2,
    3,
    4
  ],
  "priceMin": 1000,
  "priceMax": 2000,
  "areaMin": 80,
  "areaMax": 220,
  "page": 1
}

Schema de response (leaf paths)

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

responseSchema

{
  "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.keyword": "string",
  "data.query": "string",
  "data.city": "string",
  "data.citySlug": "string",
  "data.state": "string",
  "data.businessType": "string",
  "data.searchId": "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[].business": "string",
  "data.items[].listingType": "string",
  "data.items[].description": "string",
  "data.items[].address.city": "string",
  "data.items[].address.state": "string",
  "data.items[].address.neighborhood": "string",
  "data.items[].prices.mainValue": "number",
  "data.items[].prices.period": "string",
  "data.items[].stamps[]": "string",
  "data.items[].amenities[]": "string",
  "data.items[].advertiser.id": "string",
  "data.items[].advertiser.name": "string",
  "data.items[].images[].url": "string",
  "data.items[].childrenCount": "number"
}

Exemplo de response

responseExample

{
  "requestId": "a1f9c6b6-56da-4be1-b2f2-4ed0f3b2f001",
  "executionId": "a1f9c6b6-56da-4be1-b2f2-4ed0f3b2f002",
  "data": {
    "source": "zapimoveis.com.br",
    "type": "plp",
    "parser": "next_flight",
    "url": "https://www.zapimoveis.com.br/venda/imoveis/pr+curitiba/?q=apartamento%202%20quartos&transacao=venda&pagina=1",
    "requestUrl": "https://www.zapimoveis.com.br/venda/imoveis/pr+curitiba/?q=apartamento%202%20quartos&transacao=venda&pagina=1",
    "extractedAt": "2026-02-19T13:00:00.000Z",
    "keyword": "apartamento 2 quartos",
    "query": "apartamento 2 quartos",
    "city": "Curitiba",
    "citySlug": "curitiba",
    "state": "PR",
    "businessType": "sale",
    "searchId": "search-9fd22f2f",
    "totalResults": 824,
    "primaryResults": 24,
    "page": 1,
    "resultsPerPage": 24,
    "offset": 0,
    "nextPage": 2,
    "nextPageUrl": "https://www.zapimoveis.com.br/venda/imoveis/pr+curitiba/?q=apartamento%202%20quartos&transacao=venda&pagina=2",
    "items": [
      {
        "position": 1,
        "id": "2670123456",
        "url": "https://www.zapimoveis.com.br/imovel/venda-apartamento-2-quartos-centro-curitiba-pr-70m2-id-2670123456/",
        "business": "SALE",
        "listingType": "USED",
        "description": "Apartamento com 2 quartos, 1 suite e vaga coberta no Centro de Curitiba.",
        "address": {
          "city": "Curitiba",
          "state": "PR",
          "neighborhood": "Centro"
        },
        "prices": {
          "mainValue": 549000,
          "period": "MONTHLY"
        },
        "stamps": [
          "Super Destaque"
        ],
        "amenities": [
          "Elevador"
        ],
        "advertiser": {
          "id": "55123",
          "name": "Imobiliaria Exemplo"
        },
        "images": [
          {
            "url": "https://resizedimgs.vivareal.com/{action}/{width}x{height}/vr.images.sp/e7d3cb8f500f42f4b95f316643e2b235.webp"
          }
        ],
        "childrenCount": 0
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.businessType	string	Tipo de negócio normalizado (sale ou rent).	sale
data.city	string	Cidade normalizada da busca.	Curitiba
data.citySlug	string	Slug da cidade usado na URL.	curitiba
data.extractedAt	string (iso datetime)	Timestamp UTC da extração.	2026-02-19T13:00:00.000Z
data.items[].address.city	string	Cidade do anúncio.	Curitiba
data.items[].address.neighborhood	string	Bairro do anúncio.	Centro
data.items[].address.state	string	UF do anúncio.	PR
data.items[].advertiser.id	string	Identificador do anunciante.	55123
data.items[].advertiser.name	string	Nome do anunciante.	Imobiliaria Exemplo
data.items[].amenities[]	string	Amenidades resumidas no card.	Elevador
data.items[].business	string	Tipo de negócio no anúncio (SALE/RENTAL).	SALE
data.items[].childrenCount	number	Quantidade de anúncios filhos/agregados no card.	0
data.items[].description	string	Descrição curta do imóvel.	Apartamento com 2 quartos, 1 suite e vaga coberta no Centro de Curitiba.
data.items[].id	string	Identificador interno do anúncio.	2670123456
data.items[].images[].url	string	URL da imagem do card.	https://resizedimgs.vivareal.com/{action}/{width}x{height}/vr.images.sp/e7d3cb8f500f42f4b95f316643e2b235.webp
data.items[].listingType	string	Tipo do anúncio conforme origem.	USED
data.items[].position	number	Posição absoluta do item no resultado.	1
data.items[].prices.mainValue	number	Preço principal do anúncio.	549000
data.items[].prices.period	string	Período de cobrança do preço.	MONTHLY
data.items[].stamps[]	string	Selos/promos exibidos no card.	Super Destaque
data.items[].url	string	URL pública do anúncio.	https://www.zapimoveis.com.br/imovel/venda-apartamento-2-quartos-centro-curitiba-pr-70m2-id-2670123456/
data.keyword	string	Keyword enviada no payload.	apartamento 2 quartos
data.nextPage	number	Próxima página disponível.	2
data.nextPageUrl	string	URL da próxima página, quando disponível.	https://www.zapimoveis.com.br/venda/imoveis/pr+curitiba/?q=apartamento%202%20quartos&transacao=venda&pagina=2
data.offset	number	Offset calculado da paginação.	0
data.page	number	Página retornada.	1
data.parser	string	Parser utilizado para extrair os dados (next_flight ou jsonld).	next_flight
data.primaryResults	number	Quantidade de itens retornados na página atual.	24
data.query	string	Termo de busca aplicado na consulta.	apartamento 2 quartos
data.requestUrl	string	URL efetivamente consultada no upstream.	https://www.zapimoveis.com.br/venda/imoveis/pr+curitiba/?q=apartamento%202%20quartos&transacao=venda&pagina=1
data.resultsPerPage	number	Quantidade de resultados por página.	24
data.searchId	string	Identificador de busca retornado pela página.	search-9fd22f2f
data.source	string	Fonte da extração.	zapimoveis.com.br
data.state	string	UF usada na busca.	PR
data.totalResults	number	Total de resultados disponíveis para a consulta.	824
data.type	string	Tipo de extração.	plp
data.url	string	URL canônica montada para a consulta.	https://www.zapimoveis.com.br/venda/imoveis/pr+curitiba/?q=apartamento%202%20quartos&transacao=venda&pagina=1
executionId	string (uuid)	Campo executionId retornado no payload de resposta.	a1f9c6b6-56da-4be1-b2f2-4ed0f3b2f002
requestId	string (uuid)	Campo requestId retornado no payload de resposta.	a1f9c6b6-56da-4be1-b2f2-4ed0f3b2f001

Erros comuns

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.