# Realtor.com: Search listings

`realtor/listings/search` · version 1.2.0 · pilot · 21 credits a call

One page of a realtor.com search, 42 homes for sale or sold, as the page shows them, with the MLS's wishes on AI use.

Categories: Real estate

## When to use

You need the homes of a realtor.com search (United States): price, beds, baths, surfaces, address and coordinates, status (for sale, pending, sold, a plan to build), listing date, photos, tours, open house, the brokerage or the builder, the contact line, and the listing's MLS and ids. Set the search up on realtor.com (place, filters, sort), then pass its URL; `next` gives the following page. A listing's MLS may ask that it not be given to AI: every listing comes with that wish in `ai_distribution_suppressed`, and honouring it is the caller's responsibility.

## Call

```bash
curl https://api.lobstr.io/v2/run \
  -H "Authorization: Bearer $LOBSTR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"source": "realtor", "operation": "listings/search", "options": {"url": "https://www.realtor.com/realestateandhomes-search/Austin_TX"}}'
```

The answer's `next` is the whole call for the following page: send it as it is. `null` on the last page.

Beside `options`, the call takes:

| Parameter | Type | Description |
|---|---|---|
| `fields` | array of string | The record fields to keep, by path (`title`, `address.city`); `object`, `id` and `position` always come. Left out: every field. |
| `limit` | integer | Only the first N records of this call (1 to 1000), in the call's order; the call costs the same, and `next` keeps the limit. Left out: every record. |

## Options

| Option | Type | Required | Default | Description |
|---|---|---|---|---|
| `url` | string (uri) | yes |  | A realtor.com search of homes for sale or sold, exactly as the browser shows it once set up: the place, then its filters as the page writes them in the path (beds-3, price-300000-600000, type-condo, show-recently-sold, sby-6 for newest first), its page the page to start at (pg-2 is the second page). A filter realtor.com does not read is refused, never ignored. realtor.com serves the first 10,000 results of a search (238 pages): narrow it (a price range, a smaller place) for more. |
| `cursor` | string |  |  | Where to go on, from `next` in an answer, as it is: opaque, and only for the search it was given with (otherwise `invalid_cursor`). Leave it out to start at the URL's page. |

## Record

Each item of `results`. Every field is always present, `null` when the site gives nothing.

| Field | Type | Description |
|---|---|---|
| `object` | `"listing"` | The kind of record: a listing, whichever site it comes from. |
| `id` | string | realtor.com's property id (9229990651); repeated in ids.property_id. |
| `position` | integer | Its place in the search, across pages (page 2 starts at 43). |
| `url` | string | null (uri) | The listing on realtor.com. |
| `status` | string | null | realtor.com's status: for_sale, sold, ready_to_build (a builder's plan). |
| `status_label` | string | null | The status as the card says it: House for sale, Pending, Sold, Condo for sale. |
| `property_type` | string | null | single_family, condos, townhomes, multi_family, coop, condop, land, mobile... |
| `plan_name` | string | null | A builder's plan's name (Plan 1908 Modeled); null for a home. |
| `price` | object |  |
| `price.amount` | number | null | The asking price; null when realtor.com hides it. |
| `price.currency` | `"USD"` |  |
| `price.from` | boolean | A starting price (a plan's: From $407,775). |
| `price.hidden` | boolean | realtor.com hides the price (sold homes in some states). |
| `price_reduced_by` | number | null | The last price cut, in USD, when the card shows one. |
| `sold_price` | number | null | The sale price of a sold home, when realtor.com shows it. |
| `beds` | number | null |  |
| `baths` | number | null | Bathrooms, a half bath counting 0.5 (2.5). |
| `living_area_sqft` | number | null | The living area, in square feet. |
| `lot_sqft` | number | null | The lot, in square feet. |
| `address` | object | The home's address; a plan's is its builder's sales office. Null parts when the MLS hides them. |
| `address.line` | string | null |  |
| `address.unit` | string | null | Unit 1601. |
| `address.city` | string | null |  |
| `address.state_code` | string | null | TX. |
| `address.postal_code` | string | null |  |
| `address.county_fips` | string | null | The county's FIPS code (48453, Travis). |
| `location` | object | null |  |
| `location.lat` | number |  |
| `location.lng` | number |  |
| `listed_at` | string | null (date-time) | When it was listed on realtor.com, UTC. |
| `photos` | array of string | The photos the card holds (1 to 3); the listing has photo_count. |
| `photo_count` | number | null |  |
| `tours` | object |  |
| `tours.three_d` | boolean |  |
| `tours.video` | boolean |  |
| `tours.virtual` | boolean |  |
| `open_house` | string | null | The next open house as the card says it: Open house 11/14. |
| `flags` | object |  |
| `flags.new_construction` | boolean |  |
| `flags.new_listing` | boolean |  |
| `flags.pending` | boolean |  |
| `flags.contingent` | boolean |  |
| `flags.foreclosure` | boolean |  |
| `flags.price_reduced` | boolean |  |
| `flags.plan` | boolean | A builder's plan, not a built home. |
| `flags.to_be_built` | boolean |  |
| `flags.builder_promotion` | boolean | The builder runs a promotion (a credit, a rate). |
| `flags.promoted` | boolean | A placement paid on realtor.com. |
| `flags.spotlight` | boolean | realtor.com's Spotlight placement. |
| `flags.verified` | boolean | realtor.com's verified badge. |
| `builder` | object | null |  |
| `builder.name` | string | null |  |
| `builder.logo_url` | string | null |  |
| `community` | object | null | A new-home community the listing belongs to. |
| `community.id` | string | null |  |
| `community.name` | string | null |  |
| `community.promotions` | array of string | Its promotions by kind: flex_cash... |
| `brokerage` | object |  |
| `brokerage.name` | string | null |  |
| `brokerage.logo_url` | string | null |  |
| `attribution` | string | null | As the card credits it: Brokered by Cervera Real Estate Inc., Built by D.R. Horton. |
| `contact` | object |  |
| `contact.label` | string | null | The card's contact button: Contact agent, Contact builder. |
| `contact.phone` | object | null | The line that button calls, when realtor.com gives one: a lead line of the office, not always its own. |
| `contact.phone.number` | string | null | E.164: +18662776005. |
| `contact.phone.as_written` | string |  |
| `listing_source` | object |  |
| `listing_source.type` | string | null | mls, or new_home for a builder. |
| `listing_source.id` | string | null | The MLS's or the builder feed's code (AUTX). |
| `listing_source.listing_id` | string | null | The listing's id in that MLS or feed. |
| `ai_distribution_suppressed` | boolean | The listing's MLS asks that it not be given to AI (realtor.com's suppression flag). It is delivered as the page has it; honouring that wish is the caller's responsibility. |
| `display_suppressed` | array of string | What realtor.com hides of the listing at its MLS's request: address, sold_price, last_sold_price, schools, avm, foreclosure... |
| `ids` | object | Every id realtor.com gives with the listing. |
| `ids.property_id` | string |  |
| `ids.listing_id` | string | null |  |
| `ids.plan_id` | string | null |  |
| `ids.spec_id` | string | null |  |
| `ids.community_id` | string | null |  |
| `ids.mls_listing_id` | string | null |  |
| `ids.z_pals_id` | string | null | realtor.com's `source.z_pals_id`, under its own name, when it gives one (30044001_Z000005139); the site says nothing of its meaning. |
| `ids.z_property_id` | string | null | realtor.com's `source.z_property_id`, under its own name, when it gives one (64777770); the site says nothing of its meaning. |
| `source_url` | string (uri) | The search page these values were read from, its page included. |
| `observed_at` | string (date-time) | When they were read |

Example:

```json
{
  "object": "listing",
  "id": "9229990651",
  "position": 1,
  "url": "https://www.realtor.com/realestateandhomes-detail/9505-Buckstitch-Saddle-Dr_Austin_TX_78724_M92299-90651",
  "status": "for_sale",
  "status_label": "House for sale",
  "property_type": "single_family",
  "plan_name": null,
  "price": {
    "amount": 407775,
    "currency": "USD",
    "from": false,
    "hidden": false
  },
  "price_reduced_by": null,
  "sold_price": null,
  "beds": 4,
  "baths": 3,
  "living_area_sqft": 2298,
  "lot_sqft": 6534,
  "address": {
    "line": "9505 Buckstitch Saddle Dr",
    "unit": null,
    "city": "Austin",
    "state_code": "TX",
    "postal_code": "78724",
    "county_fips": "48453"
  },
  "location": {
    "lat": 30.32543,
    "lng": -97.5923
  },
  "listed_at": "2026-11-12T00:07:46Z",
  "photos": [
    "https://nh.rdcpix.com/example-photo.jpg"
  ],
  "photo_count": 36,
  "tours": {
    "three_d": false,
    "video": false,
    "virtual": true
  },
  "open_house": null,
  "flags": {
    "new_construction": true,
    "new_listing": true,
    "pending": false,
    "contingent": false,
    "foreclosure": false,
    "price_reduced": false,
    "plan": false,
    "to_be_built": false,
    "builder_promotion": false,
    "promoted": false,
    "spotlight": false,
    "verified": false
  },
  "builder": {
    "name": "D.R. Horton",
    "logo_url": null
  },
  "community": null,
  "brokerage": {
    "name": "D.R. Horton",
    "logo_url": null
  },
  "attribution": "Built by D.R. Horton",
  "contact": {
    "label": "Contact builder",
    "phone": {
      "number": "+18662776005",
      "as_written": "(866) 277-6005"
    }
  },
  "listing_source": {
    "type": "new_home",
    "id": "DRHB",
    "listing_id": "270-27513-275140000-0014"
  },
  "ai_distribution_suppressed": false,
  "display_suppressed": [],
  "ids": {
    "property_id": "9229990651",
    "listing_id": "2997404931",
    "plan_id": null,
    "spec_id": null,
    "community_id": null,
    "mls_listing_id": "270-27513-275140000-0014",
    "z_pals_id": null,
    "z_property_id": null
  },
  "source_url": "https://www.realtor.com/realestateandhomes-search/Austin_TX",
  "observed_at": "2026-11-13T12:00:00Z"
}
```

## Price

21 credits a call, whatever the page holds: a short last page costs a whole call. An empty page and a failed call are free.

## Errors

| Code | Status | Retry | Message |
|---|---|---|---|
| `invalid_url` | 422 | no | This URL is not a realtor.com search this operation reads. |
| `place_not_found` | 422 | no | realtor.com knows no such place; write it as its search does (Austin_TX, New-York_NY, 78701). |
| `site_challenge` | 503 | yes | realtor.com asked to prove a person is there; retry in a minute (not charged). |
| `site_unavailable` | 503 | yes | realtor.com did not answer in time or refused the call; retry later (not charged). |
| `unexpected_answer` | 424 | no | realtor.com answered in a shape we do not read yet; we are told and fix it, and it is not charged. |
| `missing_api_key` | 401 | no | No API key: send it as `Authorization: Bearer <key>`. |
| `invalid_api_key` | 401 | no | The key is not valid, or not anymore. |
| `insufficient_credits` | 402 | no | The call costs more credits than are left. |
| `unknown_operation` | 404 | no | No such source and operation in the catalog. |
| `timeout` | 408 | yes | The call did not finish within its deadline (not charged). |
| `invalid_body` | 422 | no | The body is not a call: source, operation, options. |
| `invalid_options` | 422 | no | An option is missing or out of its contract; `param` names it. |
| `invalid_idempotency_key` | 400 | no | The Idempotency-Key header is not printable ASCII, or too long. |
| `concurrency_limit` | 429 | yes | The plan's calls at a time are all in progress (Free 1, Starter 2, Pro 10, Team 50); retry when one has finished (not charged, never queued). |
| `service_busy` | 503 | yes | Too many calls at once on the account; retry in a few seconds. |
| `balance_unavailable` | 503 | yes | The balance could not be read; retry in a few seconds. |

## Changelog

- **1.2.0** (2026-11-15): `ids` also holds the two ids realtor.com gives with some listings' source, `z_pals_id` and `z_property_id`, under their own names, null when it gives none.
- **1.1.0** (2026-11-13): `next` keeps the search as it was written and goes on with `cursor`, opaque, as every paged operation of the API (Google's page tokens): copy `next` as before. The URL is no longer rewritten with the next page; its pg-N still starts at any page.
- **1.0.0** (2026-11-13): First version on the API v2: one page of a realtor.com search, 42 homes for sale or sold, with price, beds, baths, surfaces, address, coordinates, status, photos, tours, open house, the brokerage or builder, the contact line, the MLS and its ids, and the MLS's wish on AI use; a filter realtor.com does not read is refused, never ignored.

Schema: https://api.lobstr.io/v2/catalog/realtor/listings/search · All operations: https://api.lobstr.io/v2/catalog.md
