Imovelweb APIimovelweb.com.br ↗
Search and retrieve Brazilian apartment listings from imovelweb.com.br. Get prices, room counts, features, and full descriptions via 2 structured endpoints.
What is the Imovelweb API?
The Imovelweb API provides access to apartment listings on imovelweb.com.br through 2 endpoints. Use search_apartments to query listings by city, state, or neighborhood and get back paginated summaries — including price, location, size, and rooms — then call get_listing_details with any returned URL to retrieve the full property description and complete feature list.
curl -X GET 'https://api.parse.bot/scraper/2ade82c9-9917-40f4-93e5-34773a7c4950/search_apartments?city=curitiba&page=1&state=parana&neighborhood=juveve' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace imovelweb-com-br-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Imovelweb SDK — search apartments and drill into listing details."""
from parse_apis.imovelweb_scraper_api import Imovelweb, ListingNotFound
client = Imovelweb()
# Search apartments in Juvevê, Curitiba — limit caps total items fetched
for listing in client.listingsummaries.search(neighborhood="juveve", city="curitiba", state="parana", limit=5):
print(listing.location, listing.price, listing.features_summary)
# Drill down: take one listing and fetch its full details
summary = client.listingsummaries.search(neighborhood="juveve", city="curitiba", limit=1).first()
if summary:
detail = summary.details()
print(detail.full_description)
for feature in detail.all_features:
print(feature)
# Fetch a listing directly by URL
detail = client.listings.get(url="https://www.imovelweb.com.br/propriedades/apartamento-exemplo-123.html")
print(detail.url, detail.all_features)
# Typed error handling: catch ListingNotFound for removed listings
try:
gone = client.listings.get(url="https://www.imovelweb.com.br/propriedades/removed-listing-000.html")
except ListingNotFound as exc:
print(f"Listing removed: {exc.url}")
print("exercised: listingsummaries.search / summary.details / listings.get / ListingNotFound")
Search for apartments for sale on Imovelweb by location (neighborhood, city, state). Returns paginated listing summaries with price, location, features, and detail-page URLs. Each page returns up to ~30 results. Pagination advances via the page parameter. When no listings match, returns an empty array.
| Param | Type | Description |
|---|---|---|
| city | string | City name. |
| page | integer | Page number for pagination (1-based). |
| state | string | State name. |
| neighborhood | string | Neighborhood name. Accents are normalized automatically (e.g. 'juveve' for Juvevê). |
{
"type": "object",
"fields": {
"city": "string city searched",
"page": "integer current page number",
"count": "integer total number of listings on this page",
"listings": "array of listing summary objects each containing id, price, location, description, features_summary, url, and optional size_m2, rooms, bathrooms, parking_spaces",
"neighborhood": "string neighborhood searched"
},
"sample": {
"data": {
"city": "curitiba",
"page": 1,
"count": 30,
"listings": [
{
"id": "3001029401",
"url": "https://www.imovelweb.com.br/propriedades/apartamento-com-3-suites-e-4-vagas-de-garagem-a-venda-3001029401.html",
"price": "R$ 4.990.000",
"rooms": 3,
"size_m2": 517,
"location": "Juvevê, Curitiba",
"bathrooms": 5,
"description": "Explore a exclusividade e o conforto deste apartamento...",
"parking_spaces": 4,
"features_summary": "517 m² tot. 3 quartos 5 ban. 4 vagas"
}
],
"neighborhood": "juveve"
},
"status": "success"
}
}About the Imovelweb API
What the API Covers
The API covers apartment-for-sale listings on imovelweb.com.br, one of Brazil's major real estate portals. Both endpoints return structured data in English-friendly field names, handling Portuguese accent normalization automatically — for example, passing juveve resolves listings in Juvevê.
search_apartments
Accepts optional city, state, neighborhood, and page parameters. The response includes a listings array where each object carries: id, price, location, description, features_summary, url, and optional fields size_m2, rooms, bathrooms, and par. The count field tells you how many listings are on the current page, and page confirms which page was returned. Pagination is controlled by incrementing the page parameter.
get_listing_details
Accepts a single required url parameter — the full imovelweb.com.br listing URL, typically taken from a search_apartments result's url field. The response returns all_features as an array of strings (covering area, rooms, bathrooms, and other property attributes) and full_description as a free-text string, or null when the listing has no description text. This is the right endpoint for building a detailed property record or populating a comparison view.
Scope and Limitations
The current endpoints cover apartment listings only. Rental listings, houses, commercial properties, and land parcels are outside the current scope. Neighborhood names with accents can be passed without diacritics. Listing freshness reflects what is currently published on the site at query time.
The Imovelweb API is a managed, monitored endpoint for imovelweb.com.br — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when imovelweb.com.br changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official imovelweb.com.br API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Aggregate apartment prices by neighborhood to build a Brazilian real estate price index
- Track listing counts per city and page to estimate market inventory over time
- Pull
size_m2,rooms, andpricefrom search results to calculate price-per-square-meter comparisons - Feed
full_descriptionandall_featuresinto an LLM to auto-tag property amenities - Monitor a specific Imovelweb listing URL for changes in price or description
- Build a filtered apartment search tool for specific Brazilian cities or neighborhoods
- Populate a property portfolio tracker with structured listing data from São Paulo or Curitiba neighborhoods
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does imovelweb.com.br have an official public developer API?+
What does search_apartments return for each listing in the results array?+
id, price, location, description, features_summary, and url. Where the source data is present, size_m2, rooms, bathrooms, and par are also included. Fields like size_m2 or rooms may be absent if the listing does not publish that data.Does the API cover rental listings, houses, or commercial properties?+
How does pagination work in search_apartments?+
page parameter to advance through result pages. The response returns the current page number and a count of listings on that page. There is no total-page-count field in the response, so you continue paginating until count drops to zero or a page returns no listings.Can I retrieve images or contact details from a listing?+
get_listing_details returns all_features and full_description only. Listing photos, agent contact details, and map coordinates are not exposed. You can fork the API on Parse and revise it to add those fields.