> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Listings
> Search a realtor.com (US) or realtor.ca (CA) market for property listings.
## Query Parameters
Free-text location: a city ("Austin, TX"), a ZIP/postal code, or a region ("Toronto, ON"). Required unless you pass a Canada bounding box (`lat_min`/`lat_max`/`lng_min`/`lng_max`).
Which market to search: `us` (realtor.com, USD) or `ca` (realtor.ca, CAD).
Listing status filter.
| Value | Description |
| ---------- | ---------------------------------- |
| `for_sale` | Active for-sale listings (default) |
| `for_rent` | Rental listings |
| `sold` | Recently sold listings |
| `pending` | Pending / under contract |
Minimum list price in the market's local currency.
Maximum list price in the market's local currency.
Minimum number of bedrooms.
Minimum number of bathrooms.
Minimum interior square footage. **US market only.**
Maximum interior square footage. **US market only.**
Comma-separated list of property types. **US market only.**
Values: `single_family`, `condos`, `townhomes`, `multi_family`, `mobile`, `land`.
Sort order for results.
| Value | Description |
| ------------- | -------------------- |
| `relevant` | Best match (default) |
| `newest` | Most recently listed |
| `price_low` | Cheapest first |
| `price_high` | Most expensive first |
| `photo_count` | Most photos first |
Page number for paginated results.
Results per page. Range: `1` - `200`.
South edge of a bounding box. **Canada power-user option** (realtor.ca caps \~600 results per box).
North edge of a bounding box. **Canada only.**
West edge of a bounding box. **Canada only.**
East edge of a bounding box. **Canada only.**
## Response
The market that was searched (`us` or `ca`).
ISO 3166-1 alpha-2 country code for the market (`US` or `CA`).
Total number of matching listings.
Number of listings returned on this page.
Current page number.
Total number of pages available.
Array of matching properties.
Portal property id.
Portal listing id (nullable).
MLS number (nullable).
Market (`us` or `ca`).
ISO country code.
Full URL to the listing.
Listing status (`for_sale`, `for_rent`, `sold`, `pending`).
`sale` or `rent` (nullable).
ISO 4217 currency code.
List price (nullable).
Human-formatted price, e.g. `$450,000` (nullable).
Lower bound of a price range, if listed as a range (nullable).
Upper bound of a price range (nullable).
Price per square foot (nullable).
Amount the price was reduced (nullable).
Last sold price (nullable).
Last sold date as a Unix timestamp (nullable).
Last sold date as an ISO-8601 string (nullable).
Monthly HOA fee (nullable).
Property type (e.g. `single_family`) (nullable).
Property sub-type (nullable).
Number of bedrooms (nullable).
Total number of bathrooms (nullable).
Full bathrooms (nullable).
Half bathrooms (nullable).
Interior square footage (nullable).
Lot square footage (nullable).
Year the property was built (nullable).
Number of stories (nullable).
Garage spaces (nullable).
Total rooms (nullable).
Parking spaces (nullable).
Address with `line`, `city`, `state`, `state_code`, `postal_code`, `country`, `neighborhood`, `county`, and `coordinate` (`{lat, lon}`).
Listing description (nullable).
Primary photo URL (nullable).
Total number of photos.
Photo objects with `href`, `href_high`, `href_med`, `href_low`, `tags[]`, `description`.
Virtual tour URLs.
Video URLs.
Boolean flags: `is_new_listing`, `is_pending`, `is_contingent`, `is_foreclosure`, `is_new_construction`, `is_price_reduced`, `is_coming_soon`.
Feature tags.
List date as a Unix timestamp (nullable).
List date as an ISO-8601 string (nullable).
Last update as a Unix timestamp (nullable).
Last update as an ISO-8601 string (nullable).
Days on market (nullable).
Listing agents (see the [Agent object](/api-reference/endpoint/realtor/get-property)).
Source MLS id (nullable).
Source MLS name (nullable).
Open house objects with `start_utc`, `start_at`, `end_utc`, `end_at`, `description`, `time_zone`, `href`.
### Example Response
```json theme={null}
{
"market": "us",
"country": "US",
"total": 842,
"count": 20,
"page": 1,
"total_pages": 43,
"results": [
{
"property_id": "1234567890",
"listing_id": "2960000001",
"mls_number": "ACT1234567",
"market": "us",
"country": "US",
"url": "https://www.realtor.com/realestateandhomes-detail/1234567890",
"status": "for_sale",
"transaction_type": "sale",
"currency": "USD",
"list_price": 450000,
"list_price_formatted": "$450,000",
"price_per_sqft": 250,
"hoa_fee": 45,
"property_type": "single_family",
"beds": 3,
"baths": 2,
"baths_full": 2,
"baths_half": 0,
"sqft": 1800,
"lot_sqft": 6500,
"year_built": 2015,
"address": {
"line": "123 Main St",
"city": "Austin",
"state": "Texas",
"state_code": "TX",
"postal_code": "78701",
"country": "US",
"neighborhood": "Downtown",
"county": "Travis",
"coordinate": { "lat": 30.2672, "lon": -97.7431 }
},
"primary_photo": "https://ap.rdcpix.com/abc/s.jpg",
"photo_count": 32,
"flags": { "is_new_listing": true, "is_price_reduced": false },
"days_on_market": 4,
"agents": [{ "agent_id": "A1", "name": "Jane Doe", "email": "jane@realty.com" }]
}
]
}
```
Each search request costs **8 credits**. Failed requests are not charged.
## OpenAPI
````yaml GET /v1/realtor/search
openapi: 3.1.0
info:
title: ScrapeBadger Realtor API
version: 1.0.0
description: >-
Unified real-estate scraping API over realtor.com (US) and realtor.ca
(Canada) for searching listings, fetching full property detail (price/tax
history, schools, agents, estimates), location autocomplete, and reference
data.
servers:
- url: https://scrapebadger.com
description: Production
security:
- apiKeyAuth: []
paths:
/v1/realtor/search:
get:
tags:
- Realtor Search
summary: Search Listings
description: >-
Search a realtor.com (US) or realtor.ca (CA) market for property
listings.
operationId: searchRealtorListings
parameters:
- name: location
in: query
required: true
schema:
type: string
description: >-
Free-text location (city, ZIP/postal code, or region). Required
unless a Canada bounding box is supplied.
- name: market
in: query
schema:
type: string
default: us
enum:
- us
- ca
description: 'Market to search: us (realtor.com, USD) or ca (realtor.ca, CAD).'
- name: status
in: query
schema:
type: string
default: for_sale
enum:
- for_sale
- for_rent
- sold
- pending
description: Listing status filter.
- name: price_min
in: query
schema:
type: number
minimum: 0
description: Minimum list price in the market's local currency.
- name: price_max
in: query
schema:
type: number
minimum: 0
description: Maximum list price in the market's local currency.
- name: beds_min
in: query
schema:
type: integer
minimum: 0
description: Minimum number of bedrooms.
- name: baths_min
in: query
schema:
type: integer
minimum: 0
description: Minimum number of bathrooms.
- name: sqft_min
in: query
schema:
type: integer
minimum: 0
description: Minimum interior square footage (US market only).
- name: sqft_max
in: query
schema:
type: integer
minimum: 0
description: Maximum interior square footage (US market only).
- name: property_type
in: query
schema:
type: string
description: >-
Comma-separated property types (US market only): single_family,
condos, townhomes, multi_family, mobile, land.
- name: sort
in: query
schema:
type: string
default: relevant
enum:
- relevant
- newest
- price_low
- price_high
- photo_count
description: Sort order for results.
- name: page
in: query
schema:
type: integer
default: 1
minimum: 1
description: Page number for paginated results.
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 200
description: Results per page (1-200).
- name: lat_min
in: query
schema:
type: number
description: >-
South edge of a bounding box (Canada power-user option; realtor.ca
caps ~600 results per box).
- name: lat_max
in: query
schema:
type: number
description: North edge of a bounding box (Canada only).
- name: lng_min
in: query
schema:
type: number
description: West edge of a bounding box (Canada only).
- name: lng_max
in: query
schema:
type: number
description: East edge of a bounding box (Canada only).
responses:
'200':
description: Matching listings
content:
application/json:
schema:
type: object
properties:
market:
type: string
country:
type: string
total:
type:
- integer
- 'null'
count:
type: integer
page:
type: integer
total_pages:
type:
- integer
- 'null'
results:
type: array
items:
$ref: '#/components/schemas/Property'
components:
schemas:
Property:
type: object
properties:
property_id:
type: string
listing_id:
type:
- string
- 'null'
mls_number:
type:
- string
- 'null'
market:
type: string
country:
type:
- string
- 'null'
url:
type:
- string
- 'null'
status:
type:
- string
- 'null'
transaction_type:
type:
- string
- 'null'
currency:
type:
- string
- 'null'
list_price:
type:
- number
- 'null'
list_price_formatted:
type:
- string
- 'null'
list_price_min:
type:
- number
- 'null'
list_price_max:
type:
- number
- 'null'
price_per_sqft:
type:
- number
- 'null'
price_reduced_amount:
type:
- number
- 'null'
last_sold_price:
type:
- number
- 'null'
last_sold_date_utc:
type:
- number
- 'null'
last_sold_date_at:
type:
- string
- 'null'
hoa_fee:
type:
- number
- 'null'
property_type:
type:
- string
- 'null'
sub_type:
type:
- string
- 'null'
beds:
type:
- integer
- 'null'
baths:
type:
- number
- 'null'
baths_full:
type:
- integer
- 'null'
baths_half:
type:
- integer
- 'null'
sqft:
type:
- integer
- 'null'
lot_sqft:
type:
- integer
- 'null'
year_built:
type:
- integer
- 'null'
stories:
type:
- integer
- 'null'
garage:
type:
- integer
- 'null'
rooms:
type:
- integer
- 'null'
parking_spaces:
type:
- integer
- 'null'
address:
$ref: '#/components/schemas/Address'
description_text:
type:
- string
- 'null'
primary_photo:
type:
- string
- 'null'
photo_count:
type:
- integer
- 'null'
photos:
type: array
items:
$ref: '#/components/schemas/Photo'
virtual_tours:
type: array
items:
type: string
videos:
type: array
items:
type: string
flags:
$ref: '#/components/schemas/Flags'
tags:
type: array
items:
type: string
list_date_utc:
type:
- number
- 'null'
list_date_at:
type:
- string
- 'null'
last_update_utc:
type:
- number
- 'null'
last_update_at:
type:
- string
- 'null'
days_on_market:
type:
- integer
- 'null'
agents:
type: array
items:
$ref: '#/components/schemas/Agent'
source_mls_id:
type:
- string
- 'null'
source_mls_name:
type:
- string
- 'null'
open_houses:
type: array
items:
$ref: '#/components/schemas/OpenHouse'
Address:
type: object
properties:
line:
type:
- string
- 'null'
city:
type:
- string
- 'null'
state:
type:
- string
- 'null'
state_code:
type:
- string
- 'null'
postal_code:
type:
- string
- 'null'
country:
type:
- string
- 'null'
neighborhood:
type:
- string
- 'null'
county:
type:
- string
- 'null'
coordinate:
$ref: '#/components/schemas/Coordinate'
Photo:
type: object
properties:
href:
type:
- string
- 'null'
href_high:
type:
- string
- 'null'
href_med:
type:
- string
- 'null'
href_low:
type:
- string
- 'null'
tags:
type: array
items:
type: string
description:
type:
- string
- 'null'
Flags:
type: object
properties:
is_new_listing:
type:
- boolean
- 'null'
is_pending:
type:
- boolean
- 'null'
is_contingent:
type:
- boolean
- 'null'
is_foreclosure:
type:
- boolean
- 'null'
is_new_construction:
type:
- boolean
- 'null'
is_price_reduced:
type:
- boolean
- 'null'
is_coming_soon:
type:
- boolean
- 'null'
Agent:
type: object
properties:
agent_id:
type:
- string
- 'null'
name:
type:
- string
- 'null'
first_name:
type:
- string
- 'null'
last_name:
type:
- string
- 'null'
title:
type:
- string
- 'null'
type:
type:
- string
- 'null'
email:
type:
- string
- 'null'
phones:
type: array
items:
$ref: '#/components/schemas/Phone'
photo:
type:
- string
- 'null'
href:
type:
- string
- 'null'
office:
$ref: '#/components/schemas/Office'
broker:
type:
- string
- 'null'
nrds_id:
type:
- string
- 'null'
state_license:
type:
- string
- 'null'
OpenHouse:
type: object
properties:
start_utc:
type:
- number
- 'null'
start_at:
type:
- string
- 'null'
end_utc:
type:
- number
- 'null'
end_at:
type:
- string
- 'null'
description:
type:
- string
- 'null'
time_zone:
type:
- string
- 'null'
href:
type:
- string
- 'null'
Coordinate:
type: object
properties:
lat:
type:
- number
- 'null'
lon:
type:
- number
- 'null'
Phone:
type: object
properties:
number:
type:
- string
- 'null'
type:
type:
- string
- 'null'
ext:
type:
- string
- 'null'
primary:
type:
- boolean
- 'null'
Office:
type: object
properties:
name:
type:
- string
- 'null'
email:
type:
- string
- 'null'
href:
type:
- string
- 'null'
logo:
type:
- string
- 'null'
phones:
type: array
items:
$ref: '#/components/schemas/Phone'
address:
$ref: '#/components/schemas/Address'
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
````