Skip to content
PT Start free

// docs

Chaves na Mão: Search listings

Extracts real estate listing pages from Chaves na Mão for sale and rent. Accepts public URL from PLP or friendly filters to set up the search, with optional filter by latitude/longitude.

chavesnamao.com.br:plp · 1 credit per request

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

Try this operation in the sandbox

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": "chavesnamao.com.br",
  "type": "plp",
  "businessType": "sale",
  "city": "Curitiba",
  "state": "PR",
  "neighborhood": "Centro",
  "propertyTypes": [
    "apartment"
  ],
  "amenities": [
    "pool",
    "balcony"
  ],
  "bedrooms": [
    3
  ],
  "bathrooms": [
    2
  ],
  "parkingSpots": [
    1
  ],
  "priceMin": 500000,
  "priceMax": 900000,
  "areaMin": 80,
  "areaMax": 180,
  "sort": "price",
  "directOwner": true,
  "page": 1
}'

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

chavesnamao_com_br_plp · tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "chavesnamao_com_br_plp",
    "arguments": {
      "businessType": "sale",
      "city": "Curitiba",
      "state": "PR",
      "neighborhood": "Centro",
      "propertyTypes": [
        "apartment"
      ],
      "amenities": [
        "pool",
        "balcony"
      ],
      "bedrooms": [
        3
      ],
      "bathrooms": [
        2
      ],
      "parkingSpots": [
        1
      ],
      "priceMin": 500000,
      "priceMax": 900000,
      "areaMin": 80,
      "areaMax": 180,
      "sort": "price",
      "directOwner": true,
      "page": 1,
      "executionId": "exec_example_123"
    }
  }
}

Supported inputs

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

FieldTypeRequirementRuleDefaultExample
url
URL extraction target. For some PLPs it can be omitted when API assembles URL from other fields.
 string (URL) Optional Public URL from PLP in domain chavesnamao.com.br. When omitted, API assembles the base route from businessType/location. - https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/
latitude
Latitude of the search area. It must be sent together with longitude. Supported in Airbnb PLP, Zap Imóveis PLP, VivaReal PLP, Chaves na Mão PLP and Webmotors PLP.
 number Optional Optional together with longitude. The worker applies a 2 km filter to the items returned on the current page using the geolocation exposed by the ad, neighborhood or city. - -25.4284
longitude
Longitude of the search area. It must be sent together with latitude. Supported in Airbnb PLP, Zap Imóveis PLP, VivaReal PLP, Chaves na Mão PLP and Webmotors PLP.
 number Optional Optional together with latitude. The worker applies a 2 km filter to the items returned on the current page using the geolocation exposed by the ad, neighborhood or city. - -49.2733
city
City used in structured searches for properties and vehicles and optionally in Catho PLP. In VivaReal, it requires state.
 string Optional Search city. If submitted, state is also required. - Curitiba
neighborhood
Neighborhood used in ZAP Properties PLP, Chaves na Mão PLP and VivaReal PLP. Requires city + state when shipped.
 string Optional Search neighborhood. Requires city and state. - Centro
state
UF used in structured searches for properties and vehicles and optionally in Catho PLP.
 string (UF 2 letters) Optional UF de 2 letters. Can be used alone (search by status) or together with city. - PR
businessType
Business type used in Zapimoveis, VivaReal and Chaves na Mão PLP to choose between sale and rent.
 "sale" | "rent" Conditional Required when url is not sent. Values: sale or rent. - sale
bedrooms
Room filter in real estate searches PLP. Accepts list of integers (ex: [2,3,4]).
 integer[] Optional Room filter. For Chaves na Mão the backend accepts a single value per request. - [3]
bathrooms
Bathroom filter in real estate searches PLP. Accepts list of integers (ex: [2,3,4]).
 integer[] Optional Bathroom filter. For Chaves na Mão the backend accepts a single value per request. - [2]
parkingSpots
Job filter in real estate searches PLP. Accepts list of integers (ex: [2,3,4]).
 integer[] Optional Job filter. For Chaves na Mão the backend accepts a single value per request. - [1]
propertyTypes
Property types for ZAP Properties, Chaves na Mão and VivaReal PLP. Accepted values depend on API; see specific rules below.
 array<string | integer> Optional List of property types. Friendly aliases accepted: apartment, house, penthouse, land, commercial_room, loft, flat, farm etc. - ["apartment"]
amenities
Amenities for Chaves na Mão and VivaReal PLP. Common aliases: pool, balcony, garden, furnished and backyard.
 array<string | integer> Optional List of amenities. Confirmed aliases: pool, balcony, garden, furnished and backyard. Numeric IDs are also accepted. - ["pool","balcony"]
directOwner
Direct/private advertiser filter on Chaves na Mão and VivaReal PLP.
 boolean Optional When true, applies the direct/private advertiser filter. - true
condominium
Filter for condominium properties in Chaves na Mão and VivaReal PLP.
 boolean Optional When true, applies the condominium filter. - true
includeLaunches
Controls the inclusion of entries in real estate searches PLP. In VivaReal, combines used listings and developments when true.
 boolean Optional When true, keeps posting /newEnterprise in response. The worker defaults to false. - false
priceMin
Minimum price for PLP searches for properties and vehicles.
 integer Optional Minimum price. Integer >= 0. - 500000
priceMax
Maximum price for PLP searches for properties and vehicles.
 integer Optional Maximum price. Integer >= 0 and >= priceMin. - 900000
areaMin
Minimum area (m²) for real estate searches PLP.
 integer Optional Minimum area in m². Integer >= 0. - 80
areaMax
Maximum area (m²) for real estate searches PLP.
 integer Optional Maximum area in m². Integer >= 0 and >= areaMin. - 180
sort
Ordering for VivaReal, Chaves na Mão, OLX and Webmotors PLP, Booking Review and Hotels Review. VivaReal: relevance/date/price/biggest_price/biggest_area. Webmotors: relevance/price/biggest_price/year_desc/mileage_asc. OLX: relevance/date/price/biggest_price/price_relevance. Booking/Hotels Review: most_relevant/newest_first/oldest_first/score_desc/score_asc.
 "relevance" | "date" | "price" | "biggest_price" | "biggest_area" | "price_relevance" | "most_relevant" | "newest_first" | "oldest_first" | "score_desc" | "score_asc" | "year_desc" | "mileage_asc" Optional Supported ordering: relevance, price or biggest_price. - price
target
Target source for extraction.
 enum Required Always required and must be chavesnamao.com.br. - chavesnamao.com.br
type
Extraction type: pdp, idp, plp, ilp, quote, review or places.
 enum Required Always required and must be plp. - plp
page
Pagination. In PLP, including Trivago, and in Reclame AQUI ILP starts in 1; in review (MercadoLivre, Booking and Hotels) starts in 0. The Reclame AQUI ILP even accepts the page 100.
 integer Optional 1-based pagination. 1 1

Request examples

PLP by friendly filters

Recommended flow: send businessType, location and optional filters. The worker validates the public page and queries the internal listing endpoint.

PLP by friendly filters 
{
  "target": "chavesnamao.com.br",
  "type": "plp",
  "businessType": "sale",
  "city": "Curitiba",
  "state": "PR",
  "neighborhood": "Centro",
  "propertyTypes": [
    "apartment"
  ],
  "amenities": [
    "pool",
    "balcony"
  ],
  "bedrooms": [
    3
  ],
  "bathrooms": [
    2
  ],
  "parkingSpots": [
    1
  ],
  "priceMin": 500000,
  "priceMax": 900000,
  "areaMin": 80,
  "areaMax": 180,
  "sort": "price",
  "directOwner": true,
  "page": 1
}

PLP by public URL

Use public URL when you want to preserve exactly one route from Chaves na Mão. page can still be sent to change pages.

PLP by public URL 
{
  "target": "chavesnamao.com.br",
  "type": "plp",
  "url": "https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/",
  "page": 1
}

PLP with coordinate filter

Send latitude and longitude together to filter by proximity. Chaves na Mão does not apply these coordinates to the listing endpoint; the worker consults the normal page and keeps the cards up to 2 km from the coordinates using the geolocation of the ad, neighborhood or city.

PLP with coordinate filter 
{
  "target": "chavesnamao.com.br",
  "type": "plp",
  "businessType": "sale",
  "city": "Curitiba",
  "state": "PR",
  "latitude": -25.4284,
  "longitude": -49.2733,
  "page": 1
}

Response schema

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

responseSchema 
{
  "source": "\"chavesnamao.com.br\"",
  "type": "\"plp\"",
  "parser": "\"1.0.0\"",
  "url": "string",
  "requestUrl": "string",
  "apiUrl": "string",
  "extractedAt": "string (ISO datetime)",
  "title": "string | null",
  "description": "string | null",
  "headingTitle": "string | null",
  "businessType": "\"sale\" | \"rent\" | null",
  "page": "integer",
  "totalPages": "integer | null",
  "totalResults": "integer | null",
  "primaryResults": "integer",
  "nextPage": "integer | null",
  "nextPageUrl": "string | null",
  "includeLaunches": "boolean",
  "launchesFilteredOut": "integer",
  "latitude": "number | null",
  "longitude": "number | null",
  "coordinateRadiusKm": "number | null",
  "coordinateFilteredOut": "integer",
  "filters": "object | null",
  "locations": "array<object>",
  "items": "array<object>"
}

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 
{
  "source": "chavesnamao.com.br",
  "type": "plp",
  "parser": "1.0.0",
  "url": "https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/?latitude=-25.4284&longitude=-49.2733",
  "requestUrl": "https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/?latitude=-25.4284&longitude=-49.2733",
  "apiUrl": "https://www.chavesnamao.com.br/api/realestate/listing/items/?viewport=desktop&level1=apartamentos-a-venda&level2=pr-curitiba&pg=1",
  "extractedAt": "2026-04-14T14:25:00.000Z",
  "title": "Apartamentos à venda em Curitiba, PR",
  "description": "Busca de apartamentos à venda em Curitiba.",
  "headingTitle": "Apartamentos à venda em Curitiba",
  "businessType": "sale",
  "page": 1,
  "totalPages": 2206,
  "totalResults": 33083,
  "primaryResults": 12,
  "nextPage": 2,
  "nextPageUrl": "https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/?latitude=-25.4284&longitude=-49.2733&pg=2",
  "includeLaunches": false,
  "launchesFilteredOut": 2,
  "latitude": -25.4284,
  "longitude": -49.2733,
  "coordinateRadiusKm": 2,
  "coordinateFilteredOut": 1,
  "filters": {
    "state": "PR",
    "city": "Curitiba",
    "neighborhood": "Centro",
    "propertyTypes": [
      {
        "id": 1,
        "key": "apartamentos",
        "label": "Apartamento",
        "saleSegment": "apartamentos-a-venda",
        "rentSegment": "apartamentos-para-alugar"
      }
    ],
    "amenities": [
      {
        "id": 5,
        "key": "pool",
        "label": "Piscina"
      },
      {
        "id": 13,
        "key": "balcony",
        "label": "Varanda"
      }
    ],
    "bedrooms": 3,
    "bathrooms": 2,
    "parkingSpots": 1,
    "priceMin": 500000,
    "priceMax": 900000,
    "areaMin": 80,
    "areaMax": 180,
    "sort": "price",
    "directOwner": true,
    "condominium": false,
    "raw": {
      "realtyTypeTransaction": "sell"
    }
  },
  "locations": [
    {
      "id": 6015,
      "name": "Curitiba",
      "slug": "pr-curitiba",
      "category": "city",
      "suffixLocation": "PR"
    }
  ],
  "items": [
    {
      "position": 1,
      "id": "31728852",
      "url": "https://www.chavesnamao.com.br/imovel/apartamento-a-venda-1-quarto-pr-curitiba-cajuru-38m2-RS250000/id-31728852/",
      "title": "Apartamento com 1 quarto à venda no Cajuru, Curitiba",
      "description": "Apartamento compacto à venda em Curitiba.",
      "reference": "V021",
      "category": "residential",
      "businessType": "sale",
      "transaction": "SELL",
      "realtyType": {
        "id": 1,
        "name": "Apartamento",
        "pluralName": "Apartamentos",
        "slug": "apartamentos",
        "prefix": "deste"
      },
      "prices": {
        "main": "R$ 250.000",
        "rawPrice": 250000,
        "maxPrice": 250000,
        "condominiumFee": 0,
        "iptuValue": 0
      },
      "area": {
        "useful": 38,
        "usefulMax": 38,
        "total": 38,
        "totalMax": 38
      },
      "counts": {
        "bedrooms": {
          "count": 1,
          "max": 1
        },
        "bathrooms": {
          "count": 1,
          "max": 1
        },
        "suites": {
          "count": 0,
          "max": 0
        },
        "garages": {
          "count": 0,
          "max": 0
        },
        "commercialRooms": {
          "count": 0,
          "max": 0
        }
      },
      "address": {
        "street": "Rua Exemplo, 123",
        "neighborhood": "Cajuru",
        "city": "Curitiba",
        "state": "PR",
        "zipCode": "82900-000",
        "addressComplement": "",
        "publicAddress": false,
        "latitude": -25.4493,
        "longitude": -49.2306
      },
      "advertiser": {
        "id": "13039",
        "name": "Prime Soho",
        "url": "https://www.chavesnamao.com.br/imobiliaria/prime-soho/id-13039/",
        "type": "PJ",
        "category": 0,
        "contractDate": "2024-07-30T03:00:00.000Z",
        "creci": "J-4321",
        "stockCount": 120,
        "logoUrl": "https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/logo-prime.png",
        "phones": {
          "cellphone": "(41) 99999-0000",
          "landline": "(41) 3333-2200",
          "commercial": "(41) 3333-2201",
          "public": true
        },
        "address": {
          "city": "Curitiba",
          "state": "PR"
        }
      },
      "images": [
        "https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/13039/31728852/pr-curitiba-apartamento-01.jpg"
      ],
      "featuredImage": "https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/13039/31728852/pr-curitiba-apartamento-01.jpg",
      "imageCount": 8,
      "privativeAmenities": [],
      "commonAmenities": [],
      "has360Tour": false,
      "videoUrl": "",
      "acceptTrade": true,
      "acceptTrades": true,
      "petFriendly": false,
      "highlighted": false,
      "active": true,
      "isLaunch": false,
      "launchStatus": "",
      "updatedAt": "2026-04-13T15:00:00.000Z",
      "status": "ACTIVE",
      "score": 7.9
    }
  ]
}

Complete field reference

PathTypeDescriptionExample
apiUrl string URL from the internal endpoint `/api/realestate/listing/items/` used to extract the structured listing. https://www.chavesnamao.com.br/api/realestate/listing/items/?viewport=desktop&level1=apartamentos-a-venda&level2=pr-curitiba&pg=1
businessType "sale" | "rent" | null Type of business inferred/applied in the search: sale or rent. sale
coordinateFilteredOut integer Number of items on the current page removed because they are outside the coordinate radius or do not have geolocation available. 1
coordinateRadiusKm number | null Radius in kilometers used by the coordinate filter. Today is 2 km when latitude/longitude are shipped. 2
description string | null Summary listing description when available. Busca de apartamentos à venda em Curitiba.
extractedAt string (ISO datetime) Timestamp ISO UTC when the extraction was completed. 2026-04-14T14:25:00.000Z
filters object | null Normalized block of filters observed/applied in the search. {"state":"PR","city":"Curitiba","neighborhood":"Centro","propertyTypes":[{"id":1,"key":"apartamentos","label":"Apartamento","saleSegment":"apartamentos-a-venda","rentSegment":"apartamentos-para-alugar"}],"amenities":[{"id":5,"key":"pool","label":"Piscina"},{"id":13,"key":"balcony","label":"Varanda"}],"bedrooms":3,"bathrooms":2,"parkingSpots":1,"priceMin":500000,"priceMax":900000,"areaMin":80,"areaMax":180,"sort":"price","directOwner":true,"condominium":false,"raw":{"realtyTypeTransaction":"sell"}}
headingTitle string | null Main title rendered/normalized for search. Apartamentos à venda em Curitiba
includeLaunches boolean Replicates the request behavior. false removes `/lancamento/` items from the final response. false
items array<object> List of structured ads returned for the queried page. [{"position":1,"id":"31728852","url":"https://www.chavesnamao.com.br/imovel/apartamento-a-venda-1-quarto-pr-curitiba-cajuru-38m2-RS250000/id-31728852/","title":"Apartamento com 1 quarto à venda no Cajuru, Curitiba","description":"Apartamento compacto à venda em Curitiba.","reference":"V021","category":"residential","businessType":"sale","transaction":"SELL","realtyType":{"id":1,"name":"Apartamento","pluralName":"Apartamentos","slug":"apartamentos","prefix":"deste"},"prices":{"main":"R$ 250.000","rawPrice":250000,"maxPrice":250000,"condominiumFee":0,"iptuValue":0},"area":{"useful":38,"usefulMax":38,"total":38,"totalMax":38},"counts":{"bedrooms":{"count":1,"max":1},"bathrooms":{"count":1,"max":1},"suites":{"count":0,"max":0},"garages":{"count":0,"max":0},"commercialRooms":{"count":0,"max":0}},"address":{"street":"Rua Exemplo, 123","neighborhood":"Cajuru","city":"Curitiba","state":"PR","zipCode":"82900-000","addressComplement":"","publicAddress":false,"latitude":-25.4493,"longitude":-49.2306},"advertiser":{"id":"13039","name":"Prime Soho","url":"https://www.chavesnamao.com.br/imobiliaria/prime-soho/id-13039/","type":"PJ","category":0,"contractDate":"2024-07-30T03:00:00.000Z","creci":"J-4321","stockCount":120,"logoUrl":"https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/logo-prime.png","phones":{"cellphone":"(41) 99999-0000","landline":"(41) 3333-2200","commercial":"(41) 3333-2201","public":true},"address":{"city":"Curitiba","state":"PR"}},"images":["https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/13039/31728852/pr-curitiba-apartamento-01.jpg"],"featuredImage":"https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/13039/31728852/pr-curitiba-apartamento-01.jpg","imageCount":8,"privativeAmenities":[],"commonAmenities":[],"has360Tour":false,"videoUrl":"","acceptTrade":true,"acceptTrades":true,"petFriendly":false,"highlighted":false,"active":true,"isLaunch":false,"launchStatus":"","updatedAt":"2026-04-13T15:00:00.000Z","status":"ACTIVE","score":7.9}]
latitude number | null Latitude sent in the request when the coordinate filter is active. -25.4284
launchesFilteredOut integer Number of entries removed by the `includeLaunches=false` filter. 2
locations array<object> Normalized locations returned by the Chaves na Mão payload. [{"id":6015,"name":"Curitiba","slug":"pr-curitiba","category":"city","suffixLocation":"PR"}]
longitude number | null Longitude sent in the request when the coordinate filter is active. -49.2733
nextPage integer | null Next page number, if applicable. 2
nextPageUrl string | null URL public of the next page when available. https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/?latitude=-25.4284&longitude=-49.2733&pg=2
page integer Current page normalized to base 1. 1
parser "1.0.0" Stable version of the API response format. 1.0.0
primaryResults integer Quantity of primary items returned on this page. 12
requestUrl string Same value as `url`; never exposes the queried internal endpoint. https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/?latitude=-25.4284&longitude=-49.2733
source "chavesnamao.com.br" Fixed identifier of the extracted source. chavesnamao.com.br
title string | null Title returned by the listing payload when available. Apartamentos à venda em Curitiba, PR
totalPages integer | null Total pages reported by the internal endpoint. 2206
totalResults integer | null Total results reported by the internal endpoint. 33083
type "plp" Type of extraction performed: plp. plp
url string URL effective public of PLP used in address validation. https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/?latitude=-25.4284&longitude=-49.2733

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 statusError codeMeaning
400INVALID_PAYLOADInvalid JSON or a request that violates the documented validation rules.
401UNAUTHORIZEDMissing authorization or an invalid API key or token.
402INSUFFICIENT_CREDITSThe account has insufficient credits for this operation.
403FORBIDDENThe account does not have access, or the API is temporarily disabled.
409EXECUTION_CONFLICTThe execution identifier conflicts with an incompatible execution state.
429RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTSA rate limit or simultaneous request limit was exceeded.
5xxUPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_FUNCTION_ERRORAn upstream, worker or gateway failure. Failed requests follow the platform refund policy.

Other Chaves na Mão operations