Skip to main content
GET
/
v1
/
realtor
/
search
Search Listings
curl --request GET \
  --url https://scrapebadger.com/v1/realtor/search \
  --header 'x-api-key: <api-key>'
{
  "market": "<string>",
  "country": "<string>",
  "total": 123,
  "count": 123,
  "page": 123,
  "total_pages": 123,
  "results": [
    {
      "property_id": "<string>",
      "listing_id": "<string>",
      "mls_number": "<string>",
      "market": "<string>",
      "country": "<string>",
      "url": "<string>",
      "status": "<string>",
      "transaction_type": "<string>",
      "currency": "<string>",
      "list_price": 123,
      "list_price_formatted": "<string>",
      "list_price_min": 123,
      "list_price_max": 123,
      "price_per_sqft": 123,
      "price_reduced_amount": 123,
      "last_sold_price": 123,
      "last_sold_date_utc": 123,
      "last_sold_date_at": "<string>",
      "hoa_fee": 123,
      "property_type": "<string>",
      "sub_type": "<string>",
      "beds": 123,
      "baths": 123,
      "baths_full": 123,
      "baths_half": 123,
      "sqft": 123,
      "lot_sqft": 123,
      "year_built": 123,
      "stories": 123,
      "garage": 123,
      "rooms": 123,
      "parking_spaces": 123,
      "address": {
        "line": "<string>",
        "city": "<string>",
        "state": "<string>",
        "state_code": "<string>",
        "postal_code": "<string>",
        "country": "<string>",
        "neighborhood": "<string>",
        "county": "<string>",
        "coordinate": {
          "lat": 123,
          "lon": 123
        }
      },
      "description_text": "<string>",
      "primary_photo": "<string>",
      "photo_count": 123,
      "photos": [
        {
          "href": "<string>",
          "href_high": "<string>",
          "href_med": "<string>",
          "href_low": "<string>",
          "tags": [
            "<string>"
          ],
          "description": "<string>"
        }
      ],
      "virtual_tours": [
        "<string>"
      ],
      "videos": [
        "<string>"
      ],
      "flags": {
        "is_new_listing": true,
        "is_pending": true,
        "is_contingent": true,
        "is_foreclosure": true,
        "is_new_construction": true,
        "is_price_reduced": true,
        "is_coming_soon": true
      },
      "tags": [
        "<string>"
      ],
      "list_date_utc": 123,
      "list_date_at": "<string>",
      "last_update_utc": 123,
      "last_update_at": "<string>",
      "days_on_market": 123,
      "agents": [
        {
          "agent_id": "<string>",
          "name": "<string>",
          "first_name": "<string>",
          "last_name": "<string>",
          "title": "<string>",
          "type": "<string>",
          "email": "<string>",
          "phones": [
            {
              "number": "<string>",
              "type": "<string>",
              "ext": "<string>",
              "primary": true
            }
          ],
          "photo": "<string>",
          "href": "<string>",
          "office": {
            "name": "<string>",
            "email": "<string>",
            "href": "<string>",
            "logo": "<string>",
            "phones": [
              {
                "number": "<string>",
                "type": "<string>",
                "ext": "<string>",
                "primary": true
              }
            ],
            "address": {
              "line": "<string>",
              "city": "<string>",
              "state": "<string>",
              "state_code": "<string>",
              "postal_code": "<string>",
              "country": "<string>",
              "neighborhood": "<string>",
              "county": "<string>",
              "coordinate": {
                "lat": 123,
                "lon": 123
              }
            }
          },
          "broker": "<string>",
          "nrds_id": "<string>",
          "state_license": "<string>"
        }
      ],
      "source_mls_id": "<string>",
      "source_mls_name": "<string>",
      "open_houses": [
        {
          "start_utc": 123,
          "start_at": "<string>",
          "end_utc": 123,
          "end_at": "<string>",
          "description": "<string>",
          "time_zone": "<string>",
          "href": "<string>"
        }
      ]
    }
  ]
}

Query Parameters

location
string
required
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).
market
string
default:"us"
Which market to search: us (realtor.com, USD) or ca (realtor.ca, CAD).
status
string
default:"for_sale"
Listing status filter.
ValueDescription
for_saleActive for-sale listings (default)
for_rentRental listings
soldRecently sold listings
pendingPending / under contract
price_min
number
Minimum list price in the market’s local currency.
price_max
number
Maximum list price in the market’s local currency.
beds_min
integer
Minimum number of bedrooms.
baths_min
integer
Minimum number of bathrooms.
sqft_min
integer
Minimum interior square footage. US market only.
sqft_max
integer
Maximum interior square footage. US market only.
property_type
string
Comma-separated list of property types. US market only.Values: single_family, condos, townhomes, multi_family, mobile, land.
sort
string
default:"relevant"
Sort order for results.
ValueDescription
relevantBest match (default)
newestMost recently listed
price_lowCheapest first
price_highMost expensive first
photo_countMost photos first
page
integer
default:1
Page number for paginated results.
limit
integer
Results per page. Range: 1 - 200.
lat_min
number
South edge of a bounding box. Canada power-user option (realtor.ca caps ~600 results per box).
lat_max
number
North edge of a bounding box. Canada only.
lng_min
number
West edge of a bounding box. Canada only.
lng_max
number
East edge of a bounding box. Canada only.

Response

market
string
The market that was searched (us or ca).
country
string
ISO 3166-1 alpha-2 country code for the market (US or CA).
total
integer
Total number of matching listings.
count
integer
Number of listings returned on this page.
page
integer
Current page number.
total_pages
integer
Total number of pages available.
results
array
Array of matching properties.

Example Response

{
  "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.

Authorizations

x-api-key
string
header
required

Query Parameters

location
string
required

Free-text location (city, ZIP/postal code, or region). Required unless a Canada bounding box is supplied.

market
enum<string>
default:us

Market to search: us (realtor.com, USD) or ca (realtor.ca, CAD).

Available options:
us,
ca
status
enum<string>
default:for_sale

Listing status filter.

Available options:
for_sale,
for_rent,
sold,
pending
price_min
number

Minimum list price in the market's local currency.

Required range: x >= 0
price_max
number

Maximum list price in the market's local currency.

Required range: x >= 0
beds_min
integer

Minimum number of bedrooms.

Required range: x >= 0
baths_min
integer

Minimum number of bathrooms.

Required range: x >= 0
sqft_min
integer

Minimum interior square footage (US market only).

Required range: x >= 0
sqft_max
integer

Maximum interior square footage (US market only).

Required range: x >= 0
property_type
string

Comma-separated property types (US market only): single_family, condos, townhomes, multi_family, mobile, land.

sort
enum<string>
default:relevant

Sort order for results.

Available options:
relevant,
newest,
price_low,
price_high,
photo_count
page
integer
default:1

Page number for paginated results.

Required range: x >= 1
limit
integer

Results per page (1-200).

Required range: 1 <= x <= 200
lat_min
number

South edge of a bounding box (Canada power-user option; realtor.ca caps ~600 results per box).

lat_max
number

North edge of a bounding box (Canada only).

lng_min
number

West edge of a bounding box (Canada only).

lng_max
number

East edge of a bounding box (Canada only).

Response

200 - application/json

Matching listings

market
string
country
string
total
integer | null
count
integer
page
integer
total_pages
integer | null
results
object[]