// docs

VivaReal KLP — Autocomplete

Consulta sugestões do autocomplete do VivaReal por palavra-chave (KLP — Keyword List Page), retornando o JSON original em data. Custa 1 crédito por consulta bem-sucedida.

Quando usar este endpoint

Envie keyword com 1 a 200 caracteres. A consulta usa os mesmos parâmetros do autocomplete: até 10 sugestões, portal VIVAREAL, listingType USED e businessType SALE. Pode retornar bairros, cidades, anunciantes, condomínios, zonas e ruas. A ordem, duplicidades, URLs relativas, campos vazios e campos adicionais são preservados. Sem resultados, data.result é uma lista vazia. Não há paginação nem filtros adicionais.

Testar este endpoint no sandbox

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": "vivareal.com.br",
  "type": "klp",
  "keyword": "Terrara"
}'

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

vivareal_com_br_klp

Auth

Bearer ou X-API-Key

vivareal_com_br_klp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "vivareal_com_br_klp",
    "arguments": {
      "keyword": "Terrara",
      "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	Obrigatório	Palavra-chave com 1 a 200 caracteres após remover espaços nas extremidades.	-	Terrara
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatório e deve ser vivareal.com.br.	-	vivareal.com.br
type Tipo da extração: pdp, idp, plp, ilp, quote, review ou places.	enum	Obrigatório	Sempre obrigatório e deve ser klp (Keyword List Page).	-	klp

Exemplos de request

Autocomplete de condomínio

Consulta real para Terrara. O exemplo de resposta foi coletado no VivaReal; sugestões podem variar.

Autocomplete de condomínio

{
  "target": "vivareal.com.br",
  "type": "klp",
  "keyword": "Terrara"
}

Autocomplete de cidade

Termos com espaços e acentos são aceitos.

Autocomplete de cidade

{
  "target": "vivareal.com.br",
  "type": "klp",
  "keyword": "São Paulo"
}

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": "object",
  "data.result": "array<object>",
  "data.result[].category": "string (optional)",
  "data.result[].uriCategory": "object (optional)",
  "data.result[].address": "object (optional)",
  "data.result[].condominium": "object (optional)",
  "data.result[].advertiser": "object (optional)",
  "data.result[].url": "string (optional)"
}

Exemplo de response

responseExample

{
  "requestId": "58b53d62-131a-4842-938b-9153d7928113",
  "executionId": "fc1ea885-9751-4652-a29d-03bc1d57fdb8",
  "data": {
    "result": [
      {
        "category": "condominium",
        "uriCategory": {
          "page": "CONDOMINIUM"
        },
        "address": {
          "city": "São Paulo",
          "zone": "",
          "street": "Avenida Interlagos",
          "locationId": "",
          "state": "São Paulo",
          "neighborhood": "Jardim Umuarama"
        },
        "condominium": {
          "name": "Terrara"
        },
        "url": "/condominio/terrara-jardim-umuarama-id-e48adcc4-29cd/"
      },
      {
        "category": "condominium",
        "uriCategory": {
          "page": "CONDOMINIUM"
        },
        "address": {
          "city": "São Paulo",
          "zone": "",
          "street": "Avenida Interlagos",
          "locationId": "",
          "state": "São Paulo",
          "neighborhood": "Jardim Umuarama"
        },
        "condominium": {
          "name": "Terrara"
        },
        "url": "/condominio/aluguel/terrara-jardim-umuarama-id-7fe933d8-dec5/"
      },
      {
        "category": "condominium",
        "uriCategory": {
          "page": "CONDOMINIUM"
        },
        "address": {
          "city": "São Paulo",
          "zone": "",
          "street": "Avenida Interlagos",
          "locationId": "",
          "state": "São Paulo",
          "neighborhood": "Jardim Umuarama"
        },
        "condominium": {
          "name": "Terrara"
        },
        "url": "/condominio/venda/terrara-jardim-umuarama-id-7fe933d8-dec5/"
      },
      {
        "category": "condominium",
        "uriCategory": {
          "page": "CONDOMINIUM"
        },
        "address": {
          "city": "São Paulo",
          "zone": "",
          "street": "Avenida Interlagos",
          "locationId": "",
          "state": "São Paulo",
          "neighborhood": "Jardim Umuarama"
        },
        "condominium": {
          "name": "Terrara"
        },
        "url": "/condominio/terrara-jardim-umuarama-id-7fe933d8-dec5/"
      },
      {
        "category": "condominium",
        "uriCategory": {
          "page": "CONDOMINIUM"
        },
        "address": {
          "city": "São Paulo",
          "zone": "",
          "street": "Avenida Interlagos",
          "locationId": "",
          "state": "São Paulo",
          "neighborhood": "Jardim Umuarama"
        },
        "condominium": {
          "name": "Terrara"
        },
        "url": "/condominio/terrara-jardim-umuarama-id-0e9bee08-1cf2/"
      },
      {
        "category": "condominium",
        "uriCategory": {
          "page": "CONDOMINIUM"
        },
        "address": {
          "city": "São Paulo",
          "zone": "",
          "street": "Avenida Interlagos",
          "locationId": "",
          "state": "São Paulo",
          "neighborhood": "Jardim Umuarama"
        },
        "condominium": {
          "name": "Terrara"
        },
        "url": "/condominio/terrara-jardim-umuarama-id-73e5d042-b425/"
      },
      {
        "category": "condominium",
        "uriCategory": {
          "page": "CONDOMINIUM"
        },
        "address": {
          "city": "São Paulo",
          "zone": "",
          "street": "Avenida Interlagos",
          "locationId": "",
          "state": "São Paulo",
          "neighborhood": "Jardim Umuarama"
        },
        "condominium": {
          "name": "Terrara"
        },
        "url": "/condominio/terrara-jardim-umuarama-id-1a7e21e4-fada/"
      },
      {
        "category": "condominium",
        "uriCategory": {
          "page": "CONDOMINIUM"
        },
        "address": {
          "city": "São Paulo",
          "zone": "",
          "street": "Avenida Interlagos",
          "locationId": "",
          "state": "São Paulo",
          "neighborhood": "Jardim Umuarama"
        },
        "condominium": {
          "name": "Terrara Casas/Townhouses"
        },
        "url": "/condominio/aluguel/terrara-casas-townhouses-jardim-umuarama-id-0e9bee08-1cf2/"
      },
      {
        "category": "condominium",
        "uriCategory": {
          "page": "CONDOMINIUM"
        },
        "address": {
          "city": "São Paulo",
          "zone": "",
          "street": "Avenida Interlagos",
          "locationId": "",
          "state": "São Paulo",
          "neighborhood": "Jardim Umuarama"
        },
        "condominium": {
          "name": "Terrara Casas/Townhouses"
        },
        "url": "/condominio/venda/terrara-casas-townhouses-jardim-umuarama-id-0e9bee08-1cf2/"
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data	object	Resposta JSON original do autocomplete do VivaReal, sem normalização ou remoção de campos.	{"result":[{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/terrara-jardim-umuarama-id-e48adcc4-29cd/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/aluguel/terrara-jardim-umuarama-id-7fe933d8-dec5/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/venda/terrara-jardim-umuarama-id-7fe933d8-dec5/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/terrara-jardim-umuarama-id-7fe933d8-dec5/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/terrara-jardim-umuarama-id-0e9bee08-1cf2/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/terrara-jardim-umuarama-id-73e5d042-b425/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/terrara-jardim-umuarama-id-1a7e21e4-fada/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara Casas/Townhouses"},"url":"/condominio/aluguel/terrara-casas-townhouses-jardim-umuarama-id-0e9bee08-1cf2/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara Casas/Townhouses"},"url":"/condominio/venda/terrara-casas-townhouses-jardim-umuarama-id-0e9bee08-1cf2/"}]}
data.result	array<object>	Sugestões na ordem original. Uma lista vazia representa uma busca válida sem sugestões.	[{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/terrara-jardim-umuarama-id-e48adcc4-29cd/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/aluguel/terrara-jardim-umuarama-id-7fe933d8-dec5/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/venda/terrara-jardim-umuarama-id-7fe933d8-dec5/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/terrara-jardim-umuarama-id-7fe933d8-dec5/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/terrara-jardim-umuarama-id-0e9bee08-1cf2/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/terrara-jardim-umuarama-id-73e5d042-b425/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara"},"url":"/condominio/terrara-jardim-umuarama-id-1a7e21e4-fada/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara Casas/Townhouses"},"url":"/condominio/aluguel/terrara-casas-townhouses-jardim-umuarama-id-0e9bee08-1cf2/"},{"category":"condominium","uriCategory":{"page":"CONDOMINIUM"},"address":{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"},"condominium":{"name":"Terrara Casas/Townhouses"},"url":"/condominio/venda/terrara-casas-townhouses-jardim-umuarama-id-0e9bee08-1cf2/"}]
data.result[].address	object (optional)	Endereço original; pode incluir neighborhood, city, state, zone, street, locationId e point.	{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"}
data.result[].advertiser	object (optional)	Dados do anunciante, incluindo name quando fornecido.	N/A
data.result[].category	string (optional)	Categoria da sugestão, como neighborhood, city, account, condominium, zone ou street.	condominium
data.result[].condominium	object (optional)	Dados do condomínio, incluindo name quando fornecido.	{"name":"Terrara"}
data.result[].uriCategory	object (optional)	Categoria de navegação original, quando fornecida.	{"page":"CONDOMINIUM"}
data.result[].url	string (optional)	URL original da sugestão, que pode ser relativa ao site VivaReal.	/condominio/terrara-jardim-umuarama-id-e48adcc4-29cd/
executionId	string (uuid)	Identificador da execução.	fc1ea885-9751-4652-a29d-03bc1d57fdb8
requestId	string (uuid)	Identificador da requisição.	58b53d62-131a-4842-938b-9153d7928113

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.