{ "openapi": "3.0.1", "info": { "title": "Imovirtual Scraper - Portugal Property Listings & Agents", "description": "Scrape Imovirtual.com property listings across Portugal with GPS coordinates, energy certificate, build year, agency phone numbers and the full advert text β€” not just the search-card summary.", "version": "1.0", "x-build-id": "rd80obUjtEkdZg7hg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~imovirtual-property-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-imovirtual-property-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/sian.agency~imovirtual-property-scraper/runs": { "post": { "operationId": "runs-sync-sian.agency-imovirtual-property-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/sian.agency~imovirtual-property-scraper/run-sync": { "post": { "operationId": "run-sync-sian.agency-imovirtual-property-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "operation": { "title": "🎯 What do you want to scrape?", "enum": [ "search", "detail", "agency" ], "type": "string", "description": "Pick one per run. Property Search walks Imovirtual's own result pages for any district or island and returns up to 70 listings a page, sale and rental alike. Switch on Full property details and each listing is expanded with its map coordinates, energy certificate, build year and the advertiser's phone number. Property Detail does the same for advert links you paste in. Agency Profile returns the firm itself: address, phone, website, portfolio size and the districts it lists in.", "default": "search" }, "transaction": { "title": "🀝 Sale or rental", "enum": [ "comprar", "arrendar" ], "type": "string", "description": "Which side of the market to read. Imovirtual keeps sale and rental adverts in separate result pages, so a run returns one or the other. On a rental the money field carries the monthly rent in euros; on a sale it carries the asking price. Ignored when you paste your own Search URLs β€” those are read exactly as given.", "default": "comprar" }, "propertyType": { "title": "🏠 Property type", "enum": [ "apartamento", "moradia", "terreno", "imoveis-comerciais", "armazens", "garagem", "quarto", "empreendimento" ], "type": "string", "description": "Which section of Imovirtual to read. Rooms exist only as rentals and new developments only as sales, so pairing either with the other deal type returns nothing β€” the run stops at validation and nothing is charged. Counts above are Imovirtual's own nationwide totals for sale, measured 2026-09-08.", "default": "apartamento" }, "locations": { "title": "πŸ“ Districts and islands", "uniqueItems": true, "type": "array", "description": "Which parts of Portugal to read. Every value is one of Imovirtual's own 29 top-level areas β€” the 18 mainland districts plus the 11 Atlantic islands β€” or `todo-o-pais` for the whole country in a single run. Areas are read one after another and the result cap applies per area. A council, parish or neighbourhood is narrower than the site indexes at this level: paste that page's Imovirtual address into Search URLs instead.", "items": { "type": "string", "enum": [ "todo-o-pais", "lisboa", "porto", "faro", "setubal", "braga", "aveiro", "leiria", "coimbra", "santarem", "viseu", "viana-do-castelo", "vila-real", "braganca", "castelo-branco", "guarda", "evora", "beja", "portalegre", "ilha-da-madeira", "ilha-de-porto-santo", "ilha-de-sao-miguel", "ilha-terceira", "ilha-do-faial", "ilha-do-pico", "ilha-de-sao-jorge", "ilha-de-santa-maria", "ilha-da-graciosa", "ilha-das-flores", "ilha-do-corvo" ], "enumTitles": [ "πŸ‡΅πŸ‡Ή Todo o paΓ­s β€” the whole of Portugal", "πŸ™οΈ Lisboa", "πŸŒ‰ Porto", "πŸ–οΈ Faro (Algarve)", "βš“ SetΓΊbal", "β›ͺ Braga", "🚀 Aveiro", "πŸ•―οΈ Leiria", "πŸŽ“ Coimbra", "🐴 SantarΓ©m", "🍷 Viseu", "🌊 Viana do Castelo", "πŸ‡ Vila Real", "🌰 BraganΓ§a", "🏞️ Castelo Branco", "πŸ§€ Guarda", "πŸ›οΈ Γ‰vora", "β˜€οΈ Beja", "🌾 Portalegre", "🌺 Ilha da Madeira", "🏝️ Ilha de Porto Santo", "πŸŒ‹ Ilha de SΓ£o Miguel", "πŸ‹ Ilha Terceira", "⛰️ Ilha do Faial", "πŸ—» Ilha do Pico", "πŸ„ Ilha de SΓ£o Jorge", "🏜️ Ilha de Santa Maria", "🌿 Ilha Graciosa", "🌸 Ilha das Flores", "πŸͺ¨ Ilha do Corvo" ] }, "default": [ "lisboa" ] }, "searchUrls": { "title": "πŸ”— Search URLs", "type": "array", "description": "Paste Imovirtual result-page addresses to read them exactly as given β€” the fastest way to reproduce a search you already built on the site, including councils, parishes, neighbourhoods and map areas that are narrower than the district list above. When this is filled the deal type, property type, districts and every filter below are ignored, because the address already carries them.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "listingUrls": { "title": "πŸ“„ Advert URLs", "type": "array", "description": "Imovirtual advert addresses to expand, one row each, for the Property Detail operation. Every link looks like https://www.imovirtual.com/pt/anuncio/{slug}-ID{code} β€” copy it straight from the browser bar. A link the site no longer serves is reported as not found and is not charged.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "agencyUrls": { "title": "🏒 Agency URLs", "type": "array", "description": "Imovirtual estate-agency addresses to profile, one row each, for the Agency Profile operation. Every link looks like https://www.imovirtual.com/pt/empresas/agencias-imobiliarias/{slug}-ID{id} β€” the link behind the agency name on any advert.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "fullDetails": { "title": "πŸ”¬ Full property details", "type": "boolean", "description": "Open every listing a search returns and add what the result card does not carry. That is map coordinates, the energy certificate, build year, bathroom count, condition, building type, fitted features, the advertiser's phone number, the complete photo set, floor plans and the full advert text. Each expanded listing is one extra page read and is billed as a Property Detail on top of the listing. Leave it off for a fast price-and-area sweep.", "default": false }, "maxResults": { "title": "πŸ”’ Maximum listings per area", "minimum": 1, "maximum": 10000, "type": "integer", "description": "How many listings to keep for each district, island or search URL before moving to the next one. Imovirtual serves up to 70 listings per page read, so 100 costs two reads. Free-plan runs are capped lower regardless of what you set here.", "default": 100 }, "priceMin": { "title": "πŸ’Ά Minimum price (€)", "minimum": 0, "type": "integer", "description": "Only keep listings at or above this price in euros β€” the asking price on a sale, the monthly rent on a rental. Leave at 0 for no minimum. Applied by Imovirtual itself, so a narrowed run reads fewer pages and costs less.", "default": 0 }, "priceMax": { "title": "πŸ’Ά Maximum price (€)", "minimum": 0, "type": "integer", "description": "Only keep listings at or below this price in euros. Leave at 0 for no maximum.", "default": 0 }, "areaMin": { "title": "πŸ“ Minimum area (mΒ²)", "minimum": 0, "type": "integer", "description": "Only keep listings of at least this floor area in square metres. Leave at 0 for no minimum. On land this is the plot size.", "default": 0 }, "areaMax": { "title": "πŸ“ Maximum area (mΒ²)", "minimum": 0, "type": "integer", "description": "Only keep listings of at most this floor area in square metres. Leave at 0 for no maximum.", "default": 0 }, "typology": { "title": "πŸ›οΈ Typology (T0-T4+)", "uniqueItems": true, "type": "array", "description": "Portuguese bedroom typology, the way Portuguese buyers search: T0 is a studio, T1 has one bedroom, T4+ has four or more. Pick as many as you want; leave empty for every typology. Imovirtual stores this as a room count that runs one ahead of the T number, and this actor does the conversion for you β€” each row carries both the typology and the raw room count.", "items": { "type": "string", "enum": [ "T0", "T1", "T2", "T3", "T4+" ], "enumTitles": [ "πŸ›‹οΈ T0 β€” studio, no separate bedroom", "πŸ›οΈ T1 β€” one bedroom", "πŸ›οΈ T2 β€” two bedrooms", "πŸ›οΈ T3 β€” three bedrooms", "πŸ›οΈ T4+ β€” four bedrooms or more" ] }, "default": [] }, "market": { "title": "πŸ—οΈ New build or resale", "enum": [ "any", "primary", "secondary" ], "type": "string", "description": "Whether to keep newly built property, resale property, or both. Imovirtual's own split for Lisbon apartments on 2026-09-08 was 4,661 new build against 11,812 resale.", "default": "any" }, "ownerType": { "title": "πŸ‘€ Listed by", "enum": [ "any", "private", "agency" ], "type": "string", "description": "Whether to keep adverts placed by private owners, by estate agencies, or both. Private owners are rare on Imovirtual β€” 153 of 16,474 Lisbon apartments for sale on 2026-09-08 β€” which is exactly why they are worth isolating for direct-approach outreach.", "default": "any" }, "buildYearMin": { "title": "πŸ“… Built no earlier than", "minimum": 0, "maximum": 2100, "type": "integer", "description": "Only keep property built in this year or later, as a four-digit year. Leave at 0 for any age. Useful for screening out stock that will need work: 4,240 of 16,474 Lisbon apartments for sale were built in 2015 or later.", "default": 0 }, "listedWithinDays": { "title": "πŸ• Listed within", "enum": [ "any", "1", "3", "7", "14", "30", "60" ], "type": "string", "description": "Only keep adverts first published within this window β€” the setting to use on a daily schedule so each run returns what is genuinely new. Lisbon apartments for sale published in the last 24 hours numbered 198 on 2026-09-08, against 16,474 in total.", "default": "any" }, "sortBy": { "title": "↕️ Sort by", "enum": [ "default", "priceAsc", "priceDesc", "newest" ], "type": "string", "description": "The order Imovirtual returns listings in, which decides which ones you get when the result cap bites before the result set runs out. Cheapest-first paired with a low cap is how you pull the bottom of a market rather than a random slice of it.", "default": "default" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }