# Realtor.com API scraper — US real estate data: for-sale, for-rent and recently-sold listings with full filters (price, beds, baths, property type, sqft, lot, year built, HOA, days-on-market, keywords), complete property detail with RealEstimate value, price & tax history, schools, photos, features and listing agent, multi-source home-value estimates (Collateral Analytics / Quantarium / Cotality), local market trends, location autocomplete and comparable homes — no API key required

> Search Realtor.com listings by location (for sale / for rent / recently sold), with structured filters: price, beds, baths, property type, sqft, lot size, year built, HOA, days-on-market and keywords. Paginate with offset.
> ReefAPI engine `realtor` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/realtor/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /realtor/v1/search — 2 credits
Search Realtor.com listings by location (for sale / for rent / recently sold), with structured filters: price, beds, baths, property type, sqft, lot size, year built, HOA, days-on-market and keywords. Paginate with offset.

**Parameters:**
- `location` (string, required) — Where to search — a US city, ZIP, neighborhood, county or state ('Austin, TX', '78704', 'Brooklyn, NY', 'TX').
- `status` (enum, optional, default "for_sale") — Listing status (synonyms rent/sale/recently_sold also accepted). [one of: for_sale, for_rent, sold]
- `sort` (enum, optional, default "newest") — Result ordering. [one of: newest, price_low, price_high, sold_date]
- `limit` (integer, optional, default 42) — Listings to return per call (1-200).
- `offset` (integer, optional, default 0) — Pagination offset — skip this many results (page through with offset += limit).
- `map_bounds` (object, optional) — Search an exact map viewport {west, east, south, north} in decimal degrees (alternative/addition to location).
- `price_min` (integer, optional) — Minimum price in USD (sale price, or monthly rent for status=for_rent).
- `price_max` (integer, optional) — Maximum price in USD.
- `beds_min` (integer, optional) — Minimum bedrooms (3 = 3+).
- `beds_max` (integer, optional) — Maximum bedrooms.
- `baths_min` (number, optional) — Minimum bathrooms (2 = 2+).
- `home_type` (string, optional) — Property type — one or several comma-separated. One of: single_family, condos, townhomes, multi_family, mobile, land, farm (e.g. 'single_family,condos').
- `sqft_min` (integer, optional) — Minimum living area in square feet.
- `sqft_max` (integer, optional) — Maximum living area in square feet.
- `lot_min` (integer, optional) — Minimum lot size in SQUARE FEET (43560 sqft = 1 acre).
- `lot_max` (integer, optional) — Maximum lot size in square feet.
- `year_built_min` (integer, optional) — Earliest year built.
- `year_built_max` (integer, optional) — Latest year built.
- `max_hoa` (integer, optional) — Maximum monthly HOA fee in USD.
- `days_on_max` (integer, optional) — Only listings on Realtor.com at most this many days (7 = new this week).
- `keywords` (string, optional) — Free-text listing keyword filter, comma-separated ('pool', 'waterfront', 'guest house').

**Returns:** results[]{property_id, url, list_price_usd, status, property_type, beds, baths, sqft, lot_sqft, year_built, realestimate_usd, address_line, city, state_code, postal_code, latitude, longitude, primary_photo_url, flags} + total + count + filters_applied

**Example request body:**
```json
{
  "location": "Austin, TX"
}
```

### POST /realtor/v1/detail — 3 credits
Full property record by property_id: RealEstimate value (+ range), price history, tax history, schools (with ratings), photos, interior/exterior feature groups, HOA, status flags, monthly-payment estimate and the listing agent/broker.

**Parameters:**
- `property_id` (string, required) — Realtor.com property id (from a search result's property_id, or the M-code in a listing URL).

**Returns:** property{property_id, address_line, list_price_usd, realestimate_usd, realestimate_range_usd, beds, baths, sqft, lot_sqft, year_built, description_text, hoa_fee_usd, photos[], schools[], price_history[], tax_history[], feature_groups[], flags, advertisers[]} (agent email requires include_pii)

**Example request body:**
```json
{
  "property_id": "7211899596"
}
```

### POST /realtor/v1/estimates — 2 credits
Multi-source home-value estimates (AVMs) for a property — Realtor.com surfaces several independent valuation models (Collateral Analytics, Quantarium, Cotality/CoreLogic), each with its own value and high/low range. Returns the full set plus the best estimate. The valuation surface for pricing a home.

**Parameters:**
- `property_id` (string, required) — Realtor.com property id (from a search result's property_id, or the M-code in a listing URL).

**Returns:** property_id, estimates[]{source_name, source_type, estimate_usd, estimate_high_usd, estimate_low_usd, date, is_best}, best_estimate{}, count

**Example request body:**
```json
{
  "property_id": "7211899596"
}
```

### POST /realtor/v1/sold — 2 credits
Recently-sold homes by location (or map bounds), with the same structured filters as search — the comparable-sales surface for valuing a home.

**Parameters:**
- `location` (string, required) — Where to search — a US city, ZIP, neighborhood, county or state ('Austin, TX', '78704', 'Brooklyn, NY', 'TX').
- `sort` (enum, optional, default "newest") — Result ordering. [one of: newest, price_low, price_high, sold_date]
- `limit` (integer, optional, default 42) — Listings to return per call (1-200).
- `offset` (integer, optional, default 0) — Pagination offset — skip this many results (page through with offset += limit).
- `map_bounds` (object, optional) — Search an exact map viewport {west, east, south, north} in decimal degrees (alternative/addition to location).
- `price_min` (integer, optional) — Minimum price in USD (sale price, or monthly rent for status=for_rent).
- `price_max` (integer, optional) — Maximum price in USD.
- `beds_min` (integer, optional) — Minimum bedrooms (3 = 3+).
- `beds_max` (integer, optional) — Maximum bedrooms.
- `baths_min` (number, optional) — Minimum bathrooms (2 = 2+).
- `home_type` (string, optional) — Property type — one or several comma-separated. One of: single_family, condos, townhomes, multi_family, mobile, land, farm (e.g. 'single_family,condos').
- `sqft_min` (integer, optional) — Minimum living area in square feet.
- `sqft_max` (integer, optional) — Maximum living area in square feet.
- `lot_min` (integer, optional) — Minimum lot size in SQUARE FEET (43560 sqft = 1 acre).
- `lot_max` (integer, optional) — Maximum lot size in square feet.
- `year_built_min` (integer, optional) — Earliest year built.
- `year_built_max` (integer, optional) — Latest year built.
- `max_hoa` (integer, optional) — Maximum monthly HOA fee in USD.
- `days_on_max` (integer, optional) — Only listings on Realtor.com at most this many days (7 = new this week).
- `keywords` (string, optional) — Free-text listing keyword filter, comma-separated ('pool', 'waterfront', 'guest house').

**Returns:** results[] (same card shape; status=sold, last_sold_price_usd / last_sold_date) + total + count + filters_applied

**Example request body:**
```json
{
  "location": "Austin, TX"
}
```

### POST /realtor/v1/market_trends — 1 credit
Local housing-market intelligence for a US city or ZIP — median listing price, median sold price, median price per square foot, median days-on-market and median rent. The market-overview surface for a neighborhood or metro.

**Parameters:**
- `location` (string, required) — Market area to report on — a US city ('Austin, TX', 'Las Vegas, NV') or a 5-digit ZIP code ('78704').

**Returns:** slug_id, location, geo_type, market{median_listing_price_usd, median_sold_price_usd, median_price_per_sqft_usd, median_days_on_market, median_rent_price_usd}

**Example request body:**
```json
{
  "location": "Austin, TX"
}
```

### POST /realtor/v1/comps — 2 credits
Comparable homes near a property — synthesized from recently-sold and active listings around the subject's coordinates, scored by distance, beds and sqft.

**Parameters:**
- `property_id` (string, required) — Realtor.com property id (from a search result's property_id, or the M-code in a listing URL).
- `radius_miles` (number, optional, default 2) — Search radius around the subject in miles.
- `max_comps` (integer, optional, default 12) — How many comparables to return.
- `include_active` (boolean, optional, default false) — Also include currently-active listings as comps (default: recently-sold only).

**Returns:** subject{property_id, address_line, list_price_usd, beds, baths, sqft} + comps[]{property_id, address_line, last_sold_price_usd, last_sold_date, list_price_usd, beds, baths, sqft, distance_miles} + radius_miles + method

**Example request body:**
```json
{
  "property_id": "7211899596"
}
```

### POST /realtor/v1/autocomplete — 1 credit
Location autocomplete — suggest Realtor.com cities, ZIPs, neighborhoods, counties and schools for a free-text query. Resolve a fuzzy term before searching, or power a search box.

**Parameters:**
- `query` (string, required) — Free-text location to autocomplete — a partial city, ZIP, neighborhood, county or school ('Austi', '787', 'Brookl').
- `limit` (integer, optional, default 10) — Max suggestions to return (1-25).

**Returns:** suggestions[]{id, type, name, city, state_code, postal_code, neighborhood, latitude, longitude, geo_id} + count + query

**Example request body:**
```json
{
  "query": "Austin"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=realtor
- Human docs page: https://reefapi.com/docs/realtor
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt