Realtor.com Property Search API in Python: ZIP Code Rentals and Property IDs
ZIP 10001 is a small dataset on purpose. One Manhattan postal code, one rental page, a few dozen listing rows at most β not a national inventory dump and not a hydrated home. Each row is a card: an address fragment, an advertised rent that may be missing, and a property_id the search actually returned. That identifier is the only thing a later detail call can use. This Realtor.com property search API Python ZIP code tutorial starts there, with the live-tested location 10001.
The Realtor Property Data API is an unofficial, read-only JSON service. It is not an official Realtor.com product, an MLS/IDX feed, an automated valuation, or proof that a unit is still for rent. Listings move. Fields go null. Opening this page or copying the script does not send a data request.
One ZIP is enough to start
property-search-rent takes a location. A five-digit ZIP is enough. You do not need a city slug, a map polygon, or a place token from autocomplete to pull the first page of advertised rentals. Keep the code as a string so a ZIP that starts with zero does not collapse. The documented rental example is location=10001 with sort=newest and page=1.
Sign in and copy an authorized platform key from the dashboard. The script reads OPENDATA_API_KEY from the server environment. Leave YOUR_API_KEY as a placeholder in any URL you paste until you deliberately run a request. No Realtor.com account, cookie, or session is involved. The key travels on the query string, so run production calls server-side and redact URLs from logs, screenshots, and tickets.
If a user typed a city name and you need to disambiguate, property-auto-complete can return suggestion id values such as city:New York, NY. That id selects a search area. It is not a home. Do not put it in a detail query, and do not invent one. A miss is {"data":[]} with no status field β a valid empty suggestion list, not a reason to substitute another city.
For-sale and sold inventories are different operations: property-search-buy was live-tested with New York, NY, property-search-sold with Austin, TX. A ZIP rental search does not quietly include them.
Search returns rows, not homes
A successful rental search still has two business layers on top of HTTP. The gateway envelope is code, message, and data; gateway code 200 is platform business success, HTTP 200 is not. Inside that envelope, rental search adds its own status, message, and a flat array also named data. Those cards sit at gateway.data.data. They are listing rows, not detail objects.
An impossible sale-location check once returned HTTP 200 with status=false, data=null, and a pagination-flavored error message. That is a failed search, not an empty page of homes. Do not retry it as if the page index were wrong.
Each row may carry property_id, listing_id, status=for_rent, location.address (including postal_code), list_date, nullable list_price / list_price_min / list_price_max, bedroom and bathroom values or ranges under description, and photo hrefs. Advertised rent is an offer, not a signed lease. A missing list_price means unavailable, not zero. If only a min/max range is present, label a range; do not invent a single number.
Those fields are enough to shortlist. They are not a narrative, a tax history, or a photo-rights grant. Hydrating every card is a credit choice, not a requirement of search.
The id you must keep
property-v2-detail does not accept a ZIP. Its required query is an identifier the search already returned β in the live-tested path, a property_id. You cannot mint that value from the postal code, from an address you typed, or from an autocomplete place id. If search gave you no property_id, there is nothing to enrich.
Keep property_id and listing_id as strings, as a pair from the same row. Detail uses property_id as query. Where another route needs both keys, take them from that same row; do not mix a property from one listing with a listing from another. Location suggestion ids never substitute.
Install requests, export the key on the server, then run. The script prints a local eight-card sample without claiming the server returned only eight rows, and it refuses the detail call until a search row actually produced an id.
import os
import requests
BASE = "https://api.opendata-api.com/api/project/realtor"
API_KEY = os.environ["OPENDATA_API_KEY"]
def call(operation, **params):
try:
response = requests.get(
f"{BASE}/{operation}",
params={**params, "key": API_KEY},
timeout=30,
)
except requests.RequestException:
raise RuntimeError("Request failed; use redacted diagnostics") from None
if not response.ok:
raise RuntimeError(f"HTTP {response.status_code}")
gateway = response.json()
if not isinstance(gateway, dict) or gateway.get("code") != 200:
raise RuntimeError("Gateway business failure; inspect code/message safely")
payload = gateway.get("data")
if not isinstance(payload, dict):
raise ValueError("Unexpected operation payload")
if "status" in payload and payload["status"] is not True:
raise RuntimeError("Operation business failure; inspect status/message safely")
return payload
search = call("property-search-rent", location="10001", sort="newest", page=1)
rows = search.get("data")
if not isinstance(rows, list):
raise ValueError("Expected a flat listing array")
# Identity handoff: collect property_id values before any detail call.
kept = []
print("Actual rows:", len(rows), "Reported page:", search.get("currentPage"))
for row in rows[:8]:
property_id = row.get("property_id")
address = (row.get("location") or {}).get("address") or {}
price = row.get("list_price")
rent = "Advertised rent unavailable" if price is None else f"Advertised rent: {price}"
print(property_id, address.get("postal_code"), rent)
if property_id:
kept.append(str(property_id))
if not kept:
print("No property ID available for enrichment")
else:
selected = kept[0]
detail = call("property-v2-detail", query=selected)
home = detail.get("data")
if not isinstance(home, dict):
raise ValueError("Expected a detail object")
if str(home.get("property_id")) != selected:
raise ValueError("Detail identity differs from the selected property")
print(home.get("property_id"), home.get("last_update_date"))
The live detail check matched a sale-search property's ids, address, and asking price. A fresh rental property_id is an enrichment candidate, not a guarantee that detail will populate. Compare the returned identity before you store anything. Preserve nulls. Stamp a retrieval time; last_update_date is not a live-availability promise.
What a ZIP search will not cover
This workflow will not give you a complete ZIP inventory, a historical rent roll, owner contacts, or redistribution rights for photos and listing text. Access is not an MLS/IDX license. Confirm permitted use independently.
Requested pageSize=8 still returned 30 rows in live search tests. Treat the array length as the truth, not resultsPerPage, totalResultCount, or totalPages. Deduplicate property_id/listing_id pairs across pages, stop on empty or repeated pages, and cap how far you walk. Autocomplete limit=5 similarly returned ten suggestions β apply a local display cap.
Sold search is a different identity stream. Austin rows can include last_sold_date and a nullable last_sold_price. A missing sale price is not a zero-dollar close, list_price is still an asking figure, and newest did not necessarily order by sale date. Optional filters (pets, move-in date, price bands) and address/URL forms of detail were not individually verified. Agent, coordinate, commute, dedicated photo, and financing routes remain evaluation candidates; any mortgage figures are nonbinding estimates.
A ZIP gets you rows. The rows get you an id. The id β and only that id β is what a later detail call can use.