// docs

VivaReal: Get listing details

Search VivaReal autocomplete suggestions by keyword (KLP — Keyword List Page), returning the original JSON in data. Costs 1 credit per successful request.

vivareal.com.br:klp · 1 credit per request

Standard credit cost. Your account pricing is shown in the sandbox.

Try this operation in the sandbox

When to use this operation

Send keyword with 1 to 200 characters. The query uses the same autocomplete parameters: up to 10 suggestions, portal VIVAREAL, listingType USED and businessType SALE. Results may include neighborhoods, cities, advertisers, condominiums, zones and streets. Ordering, duplicates, relative URLs, empty fields and additional fields are preserved. With no matches, data.result is an empty array. Pagination and additional filters are not supported.

HTTP request

cURL

curl -X POST https://api.geckoapi.com.br/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "vivareal.com.br",
  "type": "klp",
  "keyword": "Terrara"
}'

Keep your API key on your server. See the quickstart for authentication and response handling.

MCP request

The hosted MCP tool fixes target and type for this operation. Its remaining arguments use the same input rules as Extract.

POST /v1/mcp · Bearer or X-API-Key authentication

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

Supported inputs

Conditional fields depend on the alternatives and constraints in the rule column. Fields marked unsupported are omitted.

Field	Type	Requirement	Rule	Default	Example
keyword Keyword for PLP searches. In Google Search it represents the query sent to Google; in Booking PLP is mandatory; in other PLPs it can replace URL.	string	Required	Keyword with 1 to 200 characters after trimming surrounding whitespace.	-	Terrara
target Target source for extraction.	enum	Required	Always required and must be vivareal.com.br.	-	vivareal.com.br
type Extraction type: pdp, idp, plp, ilp, quote, review or places.	enum	Required	Always required and must be klp (Keyword List Page).	-	klp

Request examples

Condominium autocomplete

Real query for Terrara. The response example was captured from VivaReal; suggestions may vary.

Condominium autocomplete

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

City autocomplete

Terms containing spaces and accents are accepted.

City autocomplete

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

Response schema

Leaf paths and expected types. Field names and enum values are part of the API contract.

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

Example response

Illustrative response. Product names, reviews and other source content retain their original language. Missing and null values do not imply zero stock, free shipping or zero reviews.

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/"
      }
    ]
  }
}

Complete field reference

Path	Type	Description	Example
data	object	Original VivaReal autocomplete JSON response, without normalization or removed fields.	{"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>	Suggestions in their original order. An empty array represents a valid search with no suggestions.	[{"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)	Original address; may include neighborhood, city, state, zone, street, locationId and point.	{"city":"São Paulo","zone":"","street":"Avenida Interlagos","locationId":"","state":"São Paulo","neighborhood":"Jardim Umuarama"}
data.result[].advertiser	object (optional)	Advertiser data, including name when supplied.	N/A
data.result[].category	string (optional)	Suggestion category, such as neighborhood, city, account, condominium, zone or street.	condominium
data.result[].condominium	object (optional)	Condominium data, including name when supplied.	{"name":"Terrara"}
data.result[].uriCategory	object (optional)	Original navigation category, when supplied.	{"page":"CONDOMINIUM"}
data.result[].url	string (optional)	Original suggestion URL, which may be relative to the VivaReal website.	/condominio/terrara-jardim-umuarama-id-e48adcc4-29cd/
executionId	string (uuid)	Execution identifier.	fc1ea885-9751-4652-a29d-03bc1d57fdb8
requestId	string (uuid)	Request identifier.	58b53d62-131a-4842-938b-9153d7928113

Errors and missing data

When supported by this operation, an entity not found upstream can return HTTP 200 with data: null and notFound: true. Check the documented response fields before interpreting an empty result. Source-specific behavior and exceptions are described above.

HTTP status	Error code	Meaning
400	`INVALID_PAYLOAD`	Invalid JSON or a request that violates the documented validation rules.
401	`UNAUTHORIZED`	Missing authorization or an invalid API key or token.
402	`INSUFFICIENT_CREDITS`	The account has insufficient credits for this operation.
403	`FORBIDDEN`	The account does not have access, or the API is temporarily disabled.
409	`EXECUTION_CONFLICT`	The execution identifier conflicts with an incompatible execution state.
429	`RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS`	A rate limit or simultaneous request limit was exceeded.
5xx	`UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_FUNCTION_ERROR`	An upstream, worker or gateway failure. Failed requests follow the platform refund policy.

VivaReal: Get listing details

When to use this operation

HTTP request

MCP request

Supported inputs

Request examples

Condominium autocomplete

City autocomplete

Response schema

Example response

Complete field reference

Errors and missing data

Other VivaReal operations