Imovirtual APIimovirtual.com ↗
Search and retrieve Portugal property listings from Imovirtual. Access apartments, houses, land, commercial properties, and new developments via 3 endpoints.
What is the Imovirtual API?
The Imovirtual API gives developers access to Portugal's real estate market through 3 endpoints covering property search, listing details, and new developments. Use search_listings to filter by transaction type, location, price range, area, and typology across the full national inventory, or call get_listing_detail to retrieve coordinates, descriptions, images, and agency information for a single property identified by its slug.
curl -X GET 'https://api.parse.bot/scraper/9dbe3d15-ad61-44de-a1b9-5d9c8fd76c88/search_listings?page=1&sort=created_at_first%3Adesc&area_max=200&area_min=50&location=todo-o-pais&typology=T2&price_max=500000&price_min=100000&transaction=comprar&property_type=apartamento' \ -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 imovirtual-com-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.
"""Imovirtual SDK — search Portuguese real estate, filter by price/type, and drill into details."""
from parse_apis.imovirtual_api import Imovirtual, Transaction, PropertyType, Sort, ListingNotFound
client = Imovirtual()
# Search apartments for sale in Lisbon, sorted by newest, capped at 5 results
for listing in client.listings.search(
transaction=Transaction.BUY,
property_type=PropertyType.APARTMENT,
location="lisboa/lisboa",
sort=Sort.NEWEST,
limit=5,
):
print(listing.title, listing.total_price, listing.area_in_square_meters)
# Drill into the first result's full details via .refresh()
listing = client.listings.search(
transaction=Transaction.RENT,
property_type=PropertyType.HOUSE,
location="porto/porto",
price_max=2000,
limit=1,
).first()
if listing:
detail = listing.refresh()
print(detail.title, detail.description, detail.latitude, detail.longitude)
# Direct lookup by slug when you already have one
try:
full = client.listings.get(slug="apartamento-t2-oeiras-ID1hUyk")
print(full.title, full.market, full.owner_name)
except ListingNotFound as exc:
print(f"Listing gone: {exc.slug}")
# Browse new developments across all of Portugal
for dev in client.developments.search(location="todo-o-pais", limit=3):
print(dev.title, dev.investment_state, dev.investment_units_number)
print("exercised: listings.search / listings.get / listing.refresh / developments.search")
Search for real estate listings on Imovirtual with filters for transaction type, property type, location, price range, area range, typology, and sort order. Returns paginated results with listing summaries. Each page contains up to 36 items. The location path is hierarchical (district/council or 'todo-o-pais' for all Portugal).
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| sort | string | Sorting order. |
| area_max | integer | Maximum area in square meters. |
| area_min | integer | Minimum area in square meters. |
| location | string | Location path. Use 'todo-o-pais' for all of Portugal or a hierarchical path like 'lisboa/lisboa', 'porto/porto', 'porto/vila-nova-de-gaia'. |
| typology | string | Comma-separated room typologies (e.g., 'T0,T1,T2,T3,T4,T5'). |
| price_max | integer | Maximum price in euros. |
| price_min | integer | Minimum price in euros. |
| transaction | string | Transaction type. |
| property_type | string | Property type to search for. |
{
"type": "object",
"fields": {
"items": "array of listing summary objects with id, title, slug, estate, transaction, location, images, totalPrice, areaInSquareMeters, roomsNumber",
"page_count": "integer total number of pages",
"total_count": "integer total number of matching listings",
"current_page": "integer current page number"
}
}About the Imovirtual API
What the API Covers
Imovirtual is one of Portugal's primary property portals. The API surfaces three distinct endpoints: search_listings for paginated property searches, get_listing_detail for full single-property records, and search_developments for new housing developments (empreendimentos). All monetary values are in euros and area measurements are in square meters.
search_listings and search_developments
search_listings accepts filters including transaction type (buy/rent), property type, location as a hierarchical path (e.g. lisboa/lisboa or todo-o-pais for all of Portugal), price_min/price_max, area_min/area_max, and comma-separated typology values such as T0,T1,T2. Results are paginated at up to 36 items per page; the response includes total_count, page_count, and current_page alongside the items array. Each item carries id, title, slug, estate, transaction, location, images, totalPrice, areaInSquareMeters, and room count. search_developments narrows to new development projects, returning additional fields like investmentState, investmentUnitsNumber, and investmentUnitsAreaInSquareMeters.
get_listing_detail
get_listing_detail takes a slug obtained from search results (e.g. apartamento-t2-oeiras-ID1hUyk) and returns the full ad object: id, title, description, full price breakdown, location with geographic coordinates, a complete images array, property characteristics, and owner or agency contact details. This is the endpoint to use when you need floor plans, feature lists, or precise geolocation for a specific property.
Coverage and Limitations
Location paths follow Imovirtual's own hierarchy — district then municipality, e.g. setubal/setubal. The search_listings endpoint returns up to 36 listings per page; iterating page up to page_count retrieves the full result set. Data reflects what is publicly listed on Imovirtual at the time of the request; archived or expired listings are not accessible.
The Imovirtual API is a managed, monitored endpoint for imovirtual.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when imovirtual.com 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 imovirtual.com 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?+
- Build a Portugal property price map using coordinates and
totalPricefromsearch_listingsandget_listing_detail. - Monitor rental price trends in Lisbon and Porto by polling
search_listingswith transaction and location filters over time. - Aggregate new development pipeline data using
search_developmentsfields likeinvestmentStateandinvestmentUnitsNumber. - Create a typology comparison tool filtering by
T1,T2,T3across multiple districts to surface price-per-sqm differences. - Populate a CRM with agency and owner contact details from
get_listing_detailfor lead generation in the Portuguese market. - Build an area-based property alert system using
area_min/area_maxandprice_maxfilters insearch_listings. - Cross-reference development project locations with municipal data by extracting coordinates from
get_listing_detail.
| 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 Imovirtual have an official developer API?+
How does location filtering work in search_listings?+
location parameter follows a hierarchical path format matching Imovirtual's own district/municipality structure. Pass todo-o-pais to search all of Portugal, or a path like lisboa/lisboa or porto/matosinhos to narrow to a specific area. The hierarchy is district first, then municipality.Does get_listing_detail return contact information for the listing agent or owner?+
ad object returned by get_listing_detail includes owner and agency details alongside the property description, price, coordinates, images, and characteristics. The exact fields present depend on whether the listing was posted by a private owner or an agency.Can I retrieve sold or historical property listings?+
Are commercial properties covered alongside residential listings?+
search_listings covers multiple property types including apartments, houses, land, and commercial properties. The estate field in each result item identifies the property type. search_developments is specifically scoped to new development projects (empreendimentos) and does not expose general commercial or residential resale inventory in that endpoint.