{
"openapi": "3.0.1",
"info": {
"title": "SpareRoom Property Scraper",
"description": "Scrape public SpareRoom UK room, flatshare and rental listings from filtered search URLs. Extract rent, location, property type, bedrooms, advertiser details and listing URLs for research, monitoring, APIs and AI-agent workflows.",
"version": "0.0",
"x-build-id": "fOayG2eb5vbN7vvRQ"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/vivid-softwares~spareroom-property-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-vivid-softwares-spareroom-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/vivid-softwares~spareroom-property-scraper/runs": {
"post": {
"operationId": "runs-sync-vivid-softwares-spareroom-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/vivid-softwares~spareroom-property-scraper/run-sync": {
"post": {
"operationId": "run-sync-vivid-softwares-spareroom-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": {
"startUrls": {
"title": "SpareRoom search or listing URLs",
"type": "array",
"description": "Search on spareroom.co.uk (UK) or spareroom.com (US), set any filters, then paste the results URL here. Every page of results is scraped, not just the first. Works with rooms for rent, rooms wanted and buddy-up searches, and with single listing URLs.",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"title": "URL of a web page",
"format": "uri"
}
}
}
},
"locations": {
"title": "Locations",
"type": "array",
"description": "Or just type places: a UK town, city, area or postcode (\"Bristol\", \"Clapham\", \"E1\", \"M14 5\"), or a US city or ZIP code (\"New York\", \"Los Angeles\", \"90210\"). Each location is searched with the filters below. Large cities are split automatically so you can get every listing, not only the 1,000 SpareRoom shows per search.",
"items": {
"type": "string"
}
},
"country": {
"title": "Country for locations",
"enum": [
"auto",
"uk",
"us"
],
"type": "string",
"description": "Which SpareRoom site to search for the locations above. URLs always use their own site.",
"default": "auto"
},
"adType": {
"title": "Listing type",
"enum": [
"offered",
"wanted",
"buddyup"
],
"type": "string",
"description": "Which kind of SpareRoom ad to collect for the locations above.",
"default": "offered"
},
"maxItems": {
"title": "Maximum listings",
"minimum": 1,
"type": "integer",
"description": "Stop after saving this many listings in total across all URLs and locations. You only pay for listings saved.",
"default": 100
},
"minRent": {
"title": "Minimum rent (per month)",
"minimum": 0,
"type": "integer",
"description": "Monthly rent in £ (UK) or $ (US). Weekly prices are converted by SpareRoom. For rooms-wanted ads this filters the seeker's budget."
},
"maxRent": {
"title": "Maximum rent (per month)",
"minimum": 0,
"type": "integer",
"description": "Monthly rent in £ (UK) or $ (US). Whole-property listings are compared on the price of the whole place."
},
"roomType": {
"title": "Room type",
"enum": [
"",
"double",
"single"
],
"type": "string",
"description": "Only rooms of this size.",
"default": ""
},
"postedBy": {
"title": "Posted by",
"enum": [
"",
"private_landlords",
"flatmates",
"live_in",
"live_out"
],
"type": "string",
"description": "Who placed the ad.",
"default": ""
},
"suitableFor": {
"title": "Suitable for",
"enum": [
"",
"females",
"males",
"couples"
],
"type": "string",
"description": "Only rooms the advertiser says are suitable for these people.",
"default": ""
},
"availableFrom": {
"title": "Available from",
"type": "string",
"description": "Rooms available around this move-in date. SpareRoom treats it as a window, so check each listing's available_from."
},
"milesFromMax": {
"title": "Search radius (miles)",
"minimum": 0,
"maximum": 40,
"type": "integer",
"description": "Include listings up to this many miles around each location. Leave empty for SpareRoom's default."
},
"sortBy": {
"title": "Sort order",
"enum": [
"days_since_placed",
"last_updated",
"price_low_to_high",
"price_high_to_low"
],
"type": "string",
"description": "Order in which listings are collected. Matters when Maximum listings is lower than the number of results.",
"default": "days_since_placed"
},
"keyword": {
"title": "Keyword",
"type": "string",
"description": "Only ads containing this word, for example \"ensuite\" or \"garden\"."
},
"billsIncluded": {
"title": "Bills included only",
"type": "boolean",
"description": "Only rooms where bills (utilities) are included in the rent.",
"default": false
},
"noDeposit": {
"title": "No deposit only",
"type": "boolean",
"description": "Only rooms with no deposit.",
"default": false
},
"petsAllowed": {
"title": "Pets allowed only",
"type": "boolean",
"description": "Only rooms that accept pets.",
"default": false
},
"parking": {
"title": "Parking only",
"type": "boolean",
"description": "Only properties with parking.",
"default": false
},
"shortLets": {
"title": "Short lets only",
"type": "boolean",
"description": "Only rooms where short lets are considered.",
"default": false
},
"photosOnly": {
"title": "Ads with photos only",
"type": "boolean",
"description": "Only ads that have photos.",
"default": false
},
"freeToContact": {
"title": "Free to contact only",
"type": "boolean",
"description": "Only ads anyone can contact without a paid SpareRoom upgrade (no Early Bird wait).",
"default": false
},
"disabledAccess": {
"title": "Disabled access only",
"type": "boolean",
"description": "Only properties with disabled access.",
"default": false
},
"scrapeDetails": {
"title": "Full listing details",
"type": "boolean",
"description": "Open every listing for its description, map coordinates, every room and price, deposit, bills, amenities, household, preferences, advertiser and photos. Turn off for a faster run with search-result data only (title, rent, area, postcode, property type, advertiser type).",
"default": true
},
"includePhotos": {
"title": "Include all photo URLs",
"type": "boolean",
"description": "Add the full-size URL of every listing photo. The main photo is always included.",
"default": true
},
"includeDuplicates": {
"title": "Include listings saved in previous runs",
"type": "boolean",
"description": "Off: listings you already got in an earlier run are skipped and not charged, so scheduled runs return only new ads. On: every matching listing is saved again, marked with seen_in_previous_run.",
"default": false
},
"reportDelisted": {
"title": "Report delisted listings",
"type": "boolean",
"description": "Compare each search with your previous run of it and list the ads that disappeared (let, expired, removed or no longer matching) in the DELISTED_LISTINGS record of the run's key-value store. Free.",
"default": true
},
"splitLargeSearches": {
"title": "Get more than 1,000 results per search",
"type": "boolean",
"description": "SpareRoom shows only the first 1,000 results of any search. When a search has more, it is split into rent bands so every listing can be collected. Works for locations and SpareRoom area URLs (saved search links with search_id cannot be split).",
"default": true
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Leave off for the fastest runs: the Actor connects to SpareRoom directly and moves to Apify Proxy automatically if SpareRoom starts refusing requests. Turn on to always use a proxy.",
"default": {
"useApifyProxy": false
}
}
}
},
"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
},
"PROXY_UNBLOCKER_UNITS": {
"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
},
"PROXY_UNBLOCKER_UNITS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}