# Homesnap Scraper - US For-Sale Listings, Prices & Property Data (`bujhmml/homesnap-real-estate-scraper`) Actor Scrape Homesnap (Homes.com / CoStar) homes for sale: address, price, beds, baths, sqft, lot size, coordinates, MLS id, status, HOA, year built, and photos. Search by place, ZIP, URL, or bounding box; filter by price, beds, baths, size, and property type. HTTP-first, runs on proxies. - **URL**: https://apify.com/bujhmml/homesnap-real-estate-scraper.md - **Developed by:** [Ihor Bielievskiy](https://apify.com/bujhmml) (community) - **Categories:** Real estate, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.40 / 1,000 listings This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Homesnap Scraper - US For-Sale Listings, Prices & Property Data Give it a place name, a ZIP, or a Homesnap city URL and get back clean, structured listings: address, price, beds, baths, square footage, lot size, coordinates, MLS id, listing status, HOA, year built, and photos. Filter by price, beds, baths, size, and property type. Export as JSON, CSV, or Excel. Homesnap now serves Homes.com / CoStar data. This actor calls Homesnap's own JSON listing API directly instead of driving a headless browser, so it's fast. > **Use a US residential proxy.** The Homesnap listing API serves degraded (empty) results to non-US and datacenter IPs — `Count` comes back `0` even for big markets. From a US residential IP it returns the real inventory. The default proxy config is US residential for exactly this reason; leave it on unless you know what you're doing. ### What it can scrape Set `listingType`: - **`for_sale`** — active for-sale listings (the default) - **`under_contract`** — listings under contract / pending - **`sold`** — recently sold homes Tell it where to look in whichever way is easiest: - **`search`** — a list of place names or ZIPs, e.g. `"Austin, TX"` or `"10028"`. - **`startUrls`** — Homesnap for-sale city URLs straight from the address bar. - **`cities`** — a list of `{ state, city }` objects. - **`boundingBox`** — a raw map viewport (`north` / `south` / `east` / `west`) for full manual control. Each location is resolved to its Homesnap area and the listings inside its bounding box are returned (up to 500 per location — the API's own viewport cap). ### Filtering and sorting All filters run on the actor side after the fetch, so they compose cleanly: | Filter | Meaning | |--------|---------| | `priceMin` / `priceMax` | Price range in USD. | | `bedsMin` | Minimum bedrooms. | | `bathsMin` | Minimum bathrooms (half-baths count as 0.5). | | `sqftMin` / `sqftMax` | Interior size range. | | `propertyTypes` | Keep only these type codes: `1` single family, `2` condo, `3` townhouse, `4` co-op, `5` multi-family, `6` land, `7` manufactured, `8` commercial. | | `sortBy` | `price_asc`, `price_desc`, `newest`, `beds_desc`, or `sqft_desc` (applied per location). | ### Input | Field | Description | |-------|-------------| | `search` | List of place names or ZIPs to resolve and scrape. | | `startUrls` | Homesnap for-sale city URLs (`/homes-for-sale/{City}/{State}`). | | `cities` | List of `{ state, city }` objects. | | `boundingBox` | Optional raw viewport `{ north, south, east, west }` in decimal degrees. | | `listingType` | `for_sale`, `under_contract`, or `sold`. | | `propertyTypes` | Optional list of property-type codes (see table above). | | `priceMin` / `priceMax` | Price range filter. | | `bedsMin` / `bathsMin` | Minimum beds / baths filter. | | `sqftMin` / `sqftMax` | Size range filter. | | `sortBy` | Result ordering within each location. | | `maxItems` | Stop after this many results across all locations (0 = no limit). | | `proxyConfiguration` | Apify Proxy — see the coverage note at the top. | | `impersonate` | Browser TLS fingerprint (`chrome` by default). | ```json { "search": ["Austin, TX"], "listingType": "for_sale", "priceMin": 300000, "priceMax": 900000, "bedsMin": 3, "propertyTypes": [1, 3], "sortBy": "price_asc", "maxItems": 200 } ```` ### Output fields | Field | Type | Notes | |-------|------|-------| | `listing_id` / `property_id` | int | Homesnap identifiers (used for dedupe). | | `mls_id` / `mls_number` | str / int | MLS source number and id. | | `status` | str | Human label: `for_sale`, `under_contract`, `sold`, `off_market`. | | `listing_status_code` / `mls_status_code` | int | Raw status codes. | | `transaction_type` / `transaction_type_label` | int / str | Code plus `for_sale` / `for_rent` when known. | | `address`, `unit`, `city`, `state`, `zip_code` | str | Address parts. | | `price`, `original_price` | float | USD. | | `price_per_sqft` | float | `price / sqft`, when both present. | | `beds`, `baths`, `baths_full`, `baths_half` | int / float | `baths` counts half-baths as 0.5. | | `sqft`, `lot_size` | int / float | Interior sqft and lot size. | | `year_built`, `unit_count` | int | | | `property_type` / `property_type_label` | int / str | Code plus label (`single_family`, `condo`, …) when known. | | `property_subtype` | int | Raw subtype code. | | `days_on_market` | int | | | `list_date` / `list_date_iso` | int / str | Epoch ms and ISO-8601 UTC. | | `hoa_fee`, `hoa_frequency` | float / str | | | `lat`, `lng` | float | Coordinates. | | `url`, `building_name` | str | | | `photo_urls` | list\[str] | CoStar CDN URLs, sized to 1024x768. | | `details` | str | Listing remarks when present. | Rows that fail to resolve or parse are emitted as typed error records (`error`, `error_type`, `area_id`, `detail`, `source_url`) instead — never silently dropped. ### Example output ```json { "listing_id": 227047402, "property_id": 400029947475, "mls_id": "RLS20099639", "status": "for_sale", "transaction_type": 1, "transaction_type_label": "for_sale", "address": "205 E 85th Street #THA", "unit": "THA", "city": "New York", "state": "NY", "zip_code": "10028", "price": 7295000.0, "price_per_sqft": 2206.59, "beds": 3, "baths": 4.0, "sqft": 3306, "lot_size": 0.0, "year_built": 2009, "property_type": 2, "property_type_label": "condo", "list_date": 1717200000000, "list_date_iso": "2024-06-01T00:00:00+00:00", "hoa_fee": 4749.0, "hoa_frequency": "Monthly", "lat": 40.777978, "lng": -73.953811, "building_name": "The Brompton", "url": "https://www.homesnap.com/NY/New-York/205-E-85th-Street/property/400029947475", "photo_urls": ["https://ahprd1cdn.csgpimgs.com/i2/.../1024x768/image.jpg"] } ``` ### How it works Two calls per city: 1. `POST /service/Misc/Search` resolves the city text to its Homesnap **area** (id + bounding box + state). 2. `POST /service/Listings/Search` returns the for-sale listings inside that bounding box, capped at `maximumListings` (max 500). The request carries the `X-CoStar-Brand` header and the criteria envelope the site's map uses. Photos come straight from the listing payload (CoStar CDN), so there's no extra request per home; the `{size}` slot is filled in for you. ### A few things worth knowing - **US residential proxy.** Covered at the top — without one, non-US / datacenter IPs get empty results. The default config handles this. - **500 listings per location.** That's the API's map-viewport cap, not the actor. For full coverage of a dense metro, scrape it by neighborhood / smaller cities, or pass tighter `boundingBox` viewports. - **Nothing fails silently.** If a city can't be resolved or a request is rejected (e.g. the API contract changes → HTTP 422), you get a typed error row for it (with the error class in `error_type`). If *every* location comes back empty or failed while a proxy is configured — the signature of a non-US/datacenter soft-block — the whole run is marked **failed** with a clear message instead of finishing green with zero items. So an empty *successful* run means "nothing found", never a hidden block. - **You're billed per valid listing delivered**, so error rows and duplicates don't cost you anything. ### Notes Only public, unauthenticated Homesnap pages are scraped. The data comes from Homesnap's public site (Homes.com / CoStar); follow their Terms and the laws that apply to you, and use it responsibly. Removal requests are honored. ### Who built this I build scrapers for my own projects and publish the ones that turn out genuinely useful. If you need a custom scraper, a data pipeline, or a change to this actor, I'm available for freelance work. GitHub: [github.com/bujhmml](https://github.com/bujhmml) · Site: [bujhmml.fun](https://bujhmml.fun) # Actor input Schema ## `search` (type: `array`): One entry per location: a place name, neighborhood, or ZIP code, e.g. "Austin, TX" or "10028". Each entry is resolved to a Homesnap area and its listings are returned. Easiest way to start. ## `startUrls` (type: `array`): Homesnap for-sale city URLs, e.g. https://www.homesnap.com/homes-for-sale/Washington/DC (paste what you see in the browser address bar). Choose For sale / Under contract / Sold with the Listing type option below. ## `cities` (type: `array`): Alternative to search/startUrls: list of { state, city } objects, e.g. { "state": "NY", "city": "New York" }. ## `boundingBox` (type: `object`): Optional raw map viewport instead of resolving a place. Object with numeric north, south, east, west (decimal degrees), e.g. { "north": 40.88, "south": 40.68, "east": -73.9, "west": -74.05 }. ## `listingType` (type: `string`): Which listings to scrape. ## `propertyTypes` (type: `array`): Keep only these property types. Codes: 1 single family, 2 condo, 3 townhouse, 4 co-op, 5 multi-family, 6 land, 7 manufactured, 8 commercial. Leave empty for all. ## `priceMin` (type: `integer`): Keep only listings at or above this price (USD). ## `priceMax` (type: `integer`): Keep only listings at or below this price (USD). ## `bedsMin` (type: `integer`): Keep only listings with at least this many bedrooms. ## `bathsMin` (type: `integer`): Keep only listings with at least this many bathrooms (half-baths count as 0.5). ## `sqftMin` (type: `integer`): Keep only listings at or above this interior size. ## `sqftMax` (type: `integer`): Keep only listings at or below this interior size. ## `sortBy` (type: `string`): Order results within each location before delivery. ## `maxItems` (type: `integer`): Stop after this many results across all locations. 0 = no limit (capped at 500 per location by the Homesnap API). ## `proxyConfiguration` (type: `object`): Apify Proxy. Use US RESIDENTIAL for full nationwide coverage; the Homesnap listing API serves degraded (empty) results to non-US / datacenter IPs. ## `impersonate` (type: `string`): curl\_cffi impersonation target used for requests. ## Actor input object example ```json { "search": [ "Austin, TX" ], "startUrls": [ { "url": "https://www.homesnap.com/homes-for-sale/New-York/NY" } ], "listingType": "for_sale", "sortBy": "none", "maxItems": 100, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" }, "impersonate": "chrome" } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "search": [ "Austin, TX" ], "startUrls": [ { "url": "https://www.homesnap.com/homes-for-sale/New-York/NY" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("bujhmml/homesnap-real-estate-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "search": ["Austin, TX"], "startUrls": [{ "url": "https://www.homesnap.com/homes-for-sale/New-York/NY" }], } # Run the Actor and wait for it to finish run = client.actor("bujhmml/homesnap-real-estate-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "search": [ "Austin, TX" ], "startUrls": [ { "url": "https://www.homesnap.com/homes-for-sale/New-York/NY" } ] }' | apify call bujhmml/homesnap-real-estate-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=bujhmml/homesnap-real-estate-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Homesnap Scraper - US For-Sale Listings, Prices & Property Data", "description": "Scrape Homesnap (Homes.com / CoStar) homes for sale: address, price, beds, baths, sqft, lot size, coordinates, MLS id, status, HOA, year built, and photos. Search by place, ZIP, URL, or bounding box; filter by price, beds, baths, size, and property type. HTTP-first, runs on proxies.", "version": "1.1", "x-build-id": "eJ2t0xatkTZP9Ge7m" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bujhmml~homesnap-real-estate-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bujhmml-homesnap-real-estate-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/bujhmml~homesnap-real-estate-scraper/runs": { "post": { "operationId": "runs-sync-bujhmml-homesnap-real-estate-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/bujhmml~homesnap-real-estate-scraper/run-sync": { "post": { "operationId": "run-sync-bujhmml-homesnap-real-estate-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": { "search": { "title": "Search (place or ZIP)", "maxItems": 200, "type": "array", "description": "One entry per location: a place name, neighborhood, or ZIP code, e.g. \"Austin, TX\" or \"10028\". Each entry is resolved to a Homesnap area and its listings are returned. Easiest way to start.", "items": { "type": "string" } }, "startUrls": { "title": "Homesnap city URLs", "maxItems": 200, "type": "array", "description": "Homesnap for-sale city URLs, e.g. https://www.homesnap.com/homes-for-sale/Washington/DC (paste what you see in the browser address bar). Choose For sale / Under contract / Sold with the Listing type option below.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "cities": { "title": "Cities (state + city)", "maxItems": 200, "type": "array", "description": "Alternative to search/startUrls: list of { state, city } objects, e.g. { \"state\": \"NY\", \"city\": \"New York\" }." }, "boundingBox": { "title": "Bounding box (advanced)", "type": "object", "description": "Optional raw map viewport instead of resolving a place. Object with numeric north, south, east, west (decimal degrees), e.g. { \"north\": 40.88, \"south\": 40.68, \"east\": -73.9, \"west\": -74.05 }." }, "listingType": { "title": "Listing type", "enum": [ "for_sale", "under_contract", "sold" ], "type": "string", "description": "Which listings to scrape.", "default": "for_sale" }, "propertyTypes": { "title": "Property types", "maxItems": 8, "type": "array", "description": "Keep only these property types. Codes: 1 single family, 2 condo, 3 townhouse, 4 co-op, 5 multi-family, 6 land, 7 manufactured, 8 commercial. Leave empty for all." }, "priceMin": { "title": "Min price", "minimum": 0, "type": "integer", "description": "Keep only listings at or above this price (USD)." }, "priceMax": { "title": "Max price", "minimum": 0, "type": "integer", "description": "Keep only listings at or below this price (USD)." }, "bedsMin": { "title": "Min beds", "minimum": 0, "type": "integer", "description": "Keep only listings with at least this many bedrooms." }, "bathsMin": { "title": "Min baths", "minimum": 0, "type": "integer", "description": "Keep only listings with at least this many bathrooms (half-baths count as 0.5)." }, "sqftMin": { "title": "Min square feet", "minimum": 0, "type": "integer", "description": "Keep only listings at or above this interior size." }, "sqftMax": { "title": "Max square feet", "minimum": 0, "type": "integer", "description": "Keep only listings at or below this interior size." }, "sortBy": { "title": "Sort results", "enum": [ "none", "price_asc", "price_desc", "newest", "beds_desc", "sqft_desc" ], "type": "string", "description": "Order results within each location before delivery.", "default": "none" }, "maxItems": { "title": "Max results", "minimum": 0, "type": "integer", "description": "Stop after this many results across all locations. 0 = no limit (capped at 500 per location by the Homesnap API).", "default": 100 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify Proxy. Use US RESIDENTIAL for full nationwide coverage; the Homesnap listing API serves degraded (empty) results to non-US / datacenter IPs.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } }, "impersonate": { "title": "Browser TLS fingerprint", "enum": [ "chrome", "chrome131", "chrome124", "safari17_0" ], "type": "string", "description": "curl_cffi impersonation target used for requests.", "default": "chrome" } } }, "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 } } } } } } } } } } ```