// docs

Zapimoveis PLP

Extrai imóveis do ZAP por cidade/UF, bairro e tipo de imóvel, com keyword opcional, faixa de área/preço e coordenadas. Os filtros seguem a busca nativa do ZAP; confira o tipo e o endereço retornados ao selecionar comparáveis.

Nota importante: alguns campos podem retornar null em produção, dependendo da página de origem. Consulte o schema e a descrição de cada campo para tratar valores ausentes; os exemplos mostram uma resposta possível.

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

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

zapimoveis_com_br_plp

Auth

Bearer ou X-API-Key

zapimoveis_com_br_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "zapimoveis_com_br_plp",
    "arguments": {
      "city": "Curitiba",
      "state": "PR",
      "businessType": "rent",
      "page": 1,
      "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
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	Opcional	Busca textual opcional com o mesmo comportamento do site. Pode encontrar palavras na descrição; use propertyTypes para filtrar a categoria do imóvel.	-	vista livre
latitude Latitude da area de busca. Deve ser enviada junto com longitude. Suportada em Airbnb PLP, Zap Imóveis PLP, VivaReal PLP, Chaves na Mão PLP e Webmotors PLP.	number	Opcional	Opcional junto com longitude. Aplica filtro de raio 2km ao redor do ponto dentro da city/state informada.	-	-23.561399
longitude Longitude da area de busca. Deve ser enviada junto com latitude. Suportada em Airbnb PLP, Zap Imóveis PLP, VivaReal PLP, Chaves na Mão PLP e Webmotors PLP.	number	Opcional	Opcional junto com latitude. Aplica filtro de raio 2km ao redor do ponto dentro da city/state informada.	-	-46.65599
city Cidade usada em buscas estruturadas de imóveis e veículos e opcionalmente em Catho PLP. Em VivaReal, requer state.	string	Obrigatório	Cidade da busca, usada para montar o path da URL.	-	Curitiba
neighborhood Bairro usado em ZAP Imóveis PLP, Chaves na Mão PLP e VivaReal PLP. Requer city + state quando enviado.	string	Opcional	Nome de um bairro dentro da city/state informada (ex.: Mirim ou Pinheiros). Até 120 caracteres, sem vírgulas ou \|. Usa a localização nativa do ZAP. O endereço exibido e resultados ampliados seguem a fonte; confira o endereço e as coordenadas de cada anúncio.	-	Mirim
state UF usada em buscas estruturadas de imóveis e veículos e opcionalmente em Catho PLP.	string (UF 2 letras)	Obrigatório	UF com 2 letras (ex: PR).	-	PR
businessType Tipo de negócio usado no Zapimoveis, VivaReal e Chaves na Mão 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).	-	rent
bedrooms Filtro de quartos em buscas imobiliárias 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 em buscas imobiliárias 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 em buscas imobiliárias 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]
propertyTypes Tipos de imóvel para ZAP Imóveis, Chaves na Mão e VivaReal PLP. Os valores aceitos dependem da API; veja as regras específicas abaixo.	array<string \| integer>	Opcional	Tipos de imóvel: apartment, house, two_story_house, condominium, penthouse, kitnet, flat, land, farm, warehouse, commercial_point e commercial_room. Aceita array de strings ou CSV (máx. 20 itens), inclusive aliases como terreno, casa, apartamento e galpão. Vários tipos são combinados com OU. Valores desconhecidos são rejeitados. Usa a categoria nativa do ZAP, independentemente de keyword.	-	["land"]
priceMin Preço mínimo para buscas PLP de imóveis e veículos.	integer	Opcional	Preco minimo. Deve ser inteiro >= 0.	-	1000
priceMax Preço máximo para buscas PLP de imóveis e veículos.	integer	Opcional	Preco maximo. Deve ser inteiro >= 0 e >= priceMin quando ambos forem enviados.	-	2000
areaMin Área mínima (m²) para buscas imobiliárias PLP.	integer	Opcional	Área mínima em m² no filtro nativo de área útil do ZAP. Inteiro >= 0. Não é um filtro separado de área total ou de terreno.	-	750
areaMax Área máxima (m²) para buscas imobiliárias PLP.	integer	Opcional	Área máxima em m² no filtro nativo de área útil do ZAP. Inteiro >= 0 e >= areaMin quando ambos forem enviados. Confira attributes.usableAreas e attributes.totalAreas separadamente na resposta.	-	2250
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio e deve ser zapimoveis.com.br.	-	zapimoveis.com.br
type Tipo da extração: pdp, idp, plp, ilp, quote, review ou places.	enum	Obrigatório	Sempre obrigatorio e deve ser plp.	-	plp
page Paginacao. Em PLP, inclusive Trivago, e no Reclame AQUI ILP inicia em 1; em review (MercadoLivre, Booking e Hoteis) inicia em 0. O Reclame AQUI ILP aceita ate a pagina 100.	integer	Opcional	Paginação 1-based (1 a 500). Envie os mesmos filtros ao aumentar page. nextPageUrl preserva os filtros, mas a API pública continua recebendo parâmetros estruturados, não url.	1	1

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
}

Terrenos por bairro e faixa de área

Use propertyTypes para filtrar a categoria do imóvel sem depender de palavras na descrição. neighborhood refina city/state. Para pesquisar toda a cidade, omita neighborhood. Repita os mesmos filtros e aumente page para paginar.

Terrenos por bairro e faixa de área

{
  "target": "zapimoveis.com.br",
  "type": "plp",
  "city": "Imbituba",
  "state": "SC",
  "businessType": "sale",
  "propertyTypes": [
    "land"
  ],
  "neighborhood": "Mirim",
  "areaMin": 750,
  "areaMax": 2250,
  "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
}

PLP com filtro por coordenadas

Refina a busca de city/state com latitude e longitude. O upstream aplica raio de 2km ao redor do ponto.

PLP com filtro por coordenadas

{
  "target": "zapimoveis.com.br",
  "type": "plp",
  "city": "Sao Paulo",
  "state": "SP",
  "businessType": "sale",
  "latitude": -23.561399,
  "longitude": -46.65599,
  "page": 1
}

Mais de um tipo de imóvel com keyword

Combina apartamentos ou casas com uma busca textual independente. A keyword mantém o comportamento do site e não classifica o imóvel.

Mais de um tipo de imóvel com keyword

{
  "target": "zapimoveis.com.br",
  "type": "plp",
  "city": "São Paulo",
  "state": "SP",
  "businessType": "sale",
  "propertyTypes": [
    "apartment",
    "house"
  ],
  "neighborhood": "Pinheiros",
  "keyword": "vista livre",
  "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)",
  "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.keyword": "string",
  "data.query": "string",
  "data.city": "string",
  "data.citySlug": "string",
  "data.state": "string",
  "data.businessType": "string",
  "data.neighborhood": "string | null",
  "data.propertyTypes[]": "string",
  "data.latitude": "number | null",
  "data.longitude": "number | null",
  "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[].unitTypes[]": "string",
  "data.items[].attributes": "object | null",
  "data.items[].attributes.usableAreas": "number[]",
  "data.items[].attributes.totalAreas": "number[]",
  "data.items[].attributes.bedrooms": "number[]",
  "data.items[].attributes.bathrooms": "number[]",
  "data.items[].attributes.suites": "number[]",
  "data.items[].attributes.parkingSpaces": "number[]",
  "data.items[].attributes.floors": "number[]",
  "data.items[].attributes.unitFloor": "number | null",
  "data.items[].description": "string",
  "data.items[].address.city": "string",
  "data.items[].address.state": "string",
  "data.items[].address.neighborhood": "string",
  "data.items[].address.latitude": "number | null",
  "data.items[].address.longitude": "number | null",
  "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": "1.0.0",
    "url": "https://www.zapimoveis.com.br/venda/imoveis/pr+curitiba/?q=apartamento+2+quartos&transacao=venda&pagina=1&addressPointLat=-25.4296&addressPointLon=-49.2719&tipos=apartamento_residencial&onde=%2CParan%C3%A1%2CCuritiba%2C%2CCentro%2C%2C%2Cneighborhood%2C%2C%2C&pointRadius=2km",
    "requestUrl": "https://www.zapimoveis.com.br/venda/imoveis/pr+curitiba/?q=apartamento+2+quartos&transacao=venda&pagina=1&addressPointLat=-25.4296&addressPointLon=-49.2719&tipos=apartamento_residencial&onde=%2CParan%C3%A1%2CCuritiba%2C%2CCentro%2C%2C%2Cneighborhood%2C%2C%2C&pointRadius=2km",
    "extractedAt": "2026-02-19T13:00:00.000Z",
    "keyword": "apartamento 2 quartos",
    "query": "apartamento 2 quartos",
    "city": "Curitiba",
    "citySlug": "curitiba",
    "state": "PR",
    "businessType": "sale",
    "latitude": -25.4296,
    "longitude": -49.2719,
    "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+2+quartos&transacao=venda&pagina=2&addressPointLat=-25.4296&addressPointLon=-49.2719&tipos=apartamento_residencial&onde=%2CParan%C3%A1%2CCuritiba%2C%2CCentro%2C%2C%2Cneighborhood%2C%2C%2C&pointRadius=2km",
    "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",
          "latitude": -25.4296,
          "longitude": -49.2719
        },
        "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,
        "unitTypes": [
          "APARTMENT"
        ],
        "attributes": {
          "usableAreas": [
            70
          ],
          "totalAreas": [],
          "bedrooms": [
            2
          ],
          "bathrooms": [],
          "suites": [],
          "parkingSpaces": [],
          "floors": [],
          "unitFloor": null
        }
      }
    ],
    "neighborhood": "Centro",
    "propertyTypes": [
      "apartment"
    ]
  }
}

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.latitude	number \| null	Latitude do anúncio quando exposta no card da PLP.	-25.4296
data.items[].address.longitude	number \| null	Longitude do anúncio quando exposta no card da PLP.	-49.2719
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[].attributes	object \| null	Características numéricas publicadas pela fonte; null quando ausentes. Campos de lista sem valor são retornados como [].	{"usableAreas":[70],"totalAreas":[],"bedrooms":[2],"bathrooms":[],"suites":[],"parkingSpaces":[],"floors":[],"unitFloor":null}
data.items[].attributes.bathrooms	number[]	Quantidade de banheiros.	[]
data.items[].attributes.bedrooms	number[]	Quantidade de quartos.	[2]
data.items[].attributes.floors	number[]	Quantidade de andares.	[]
data.items[].attributes.parkingSpaces	number[]	Quantidade de vagas.	[]
data.items[].attributes.suites	number[]	Quantidade de suítes.	[]
data.items[].attributes.totalAreas	number[]	Áreas totais em m², somente quando explicitamente publicadas pela fonte. [] quando ausentes; nunca copiadas de usableAreas ou inferidas da descrição.	[]
data.items[].attributes.unitFloor	number \| null	Andar da unidade quando informado; null quando ausente.	null
data.items[].attributes.usableAreas	number[]	Áreas úteis em m² informadas pelo ZAP. Para terrenos, a fonte pode publicar a metragem neste campo.	[70]
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	Categoria de publicação da fonte (ex.: USED); a classificação física do imóvel está em unitTypes.	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[].unitTypes[]	string	Classificação nativa do imóvel, como APARTMENT, HOME, ALLOTMENT_LAND ou RESIDENTIAL_ALLOTMENT_LAND. Preserva os valores da fonte, sem inferir a partir de keyword, título ou descrição. Lista vazia quando indisponível.	APARTMENT
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.latitude	number \| null	Latitude usada como filtro de ponto quando enviada; null para busca city/state sem coordenadas.	-25.4296
data.longitude	number \| null	Longitude usada como filtro de ponto quando enviada; null para busca city/state sem coordenadas.	-49.2719
data.neighborhood	string \| null	Bairro solicitado; null quando omitido. Não substitui o endereço de cada anúncio.	Centro
data.nextPage	number	Próxima página disponível.	2
data.nextPageUrl	string	URL nativa da próxima página com os mesmos filtros, quando disponível. Para consultar pela API, repita os parâmetros da busca e use nextPage como page.	https://www.zapimoveis.com.br/venda/imoveis/pr+curitiba/?q=apartamento+2+quartos&transacao=venda&pagina=2&addressPointLat=-25.4296&addressPointLon=-49.2719&tipos=apartamento_residencial&onde=%2CParan%C3%A1%2CCuritiba%2C%2CCentro%2C%2C%2Cneighborhood%2C%2C%2C&pointRadius=2km
data.offset	number	Offset calculado da paginação.	0
data.page	number	Página retornada.	1
data.parser	"1.0.0"	Versão estável do formato de resposta da API.	1.0.0
data.primaryResults	number	Quantidade de itens retornados na página atual.	24
data.propertyTypes[]	string	Tipos solicitados normalizados para os aliases da API (ex.: land). Lista vazia quando não há filtro de categoria.	apartment
data.query	string	Termo de busca aplicado na consulta.	apartamento 2 quartos
data.requestUrl	string	Mesmo valor de `data.url`; nunca expõe o endpoint interno consultado.	https://www.zapimoveis.com.br/venda/imoveis/pr+curitiba/?q=apartamento+2+quartos&transacao=venda&pagina=1&addressPointLat=-25.4296&addressPointLon=-49.2719&tipos=apartamento_residencial&onde=%2CParan%C3%A1%2CCuritiba%2C%2CCentro%2C%2C%2Cneighborhood%2C%2C%2C&pointRadius=2km
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+2+quartos&transacao=venda&pagina=1&addressPointLat=-25.4296&addressPointLon=-49.2719&tipos=apartamento_residencial&onde=%2CParan%C3%A1%2CCuritiba%2C%2CCentro%2C%2C%2Cneighborhood%2C%2C%2C&pointRadius=2km
executionId	string (uuid)	Campo executionId retornado no payload de resposta.	a1f9c6b6-56da-4be1-b2f2-4ed0f3b2f002
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.	a1f9c6b6-56da-4be1-b2f2-4ed0f3b2f001

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.