Docs · HTTP API

Search US rental listings

GET /api/v1/sample returns up to 10 live US rental listings for a city, state, rent range, bedroom count or map box, with no key.

Request

GET https://housingfeed.com/api/v1/sample?state=TX&city=Austin&min_beds=2&max_rent=2500

No key and no account. HTTPS, JSON, CORS open. /api/sample is an alias of the same endpoint.

Query parameters

All parameters are optional and combine with AND. Use tier=display to see only listings that are in the Display Feed: manager-direct US sources, live at the source within 30 days.

Parameter	Type	Meaning
`country`	string	Country code, e.g. US. With tier=display only US is valid.
`state`	string	US state code, e.g. TX.
`city`	string	City name, substring match.
`min_rent` alias `minRent`	number	Minimum monthly rent (in the listing's currency).
`max_rent` alias `maxRent`	number	Maximum monthly rent.
`min_beds` alias `minBeds`	integer	Minimum bedrooms.
`max_beds` alias `maxBeds`	integer	Maximum bedrooms.
`min_lat` alias `minLat`	number	Bounding box, south edge.
`max_lat` alias `maxLat`	number	Bounding box, north edge.
`min_lng` alias `minLng`	number	Bounding box, west edge.
`max_lng` alias `maxLng`	number	Bounding box, east edge.
`fresh_days` alias `freshDays`	integer default `90`	Only rows read in the last N days. Default 90; with tier=display capped at the Display Feed window (30).
`new_since_days` alias `newSinceDays`	integer	Only rows first seen in the last N days (delta feed).
`sort`	string default `best`	Ordering. best ranks geocoded rows with a photo first and spreads across sources.
`tier`	string	display restricts to the Display Feed universe: manager-direct US sources, live at source within 30 days, rent in a plausible band.
`require_photo` alias `requirePhoto`	string	Only rows with a photo.
`require_geo` alias `requireGeo`	string	Only rows with coordinates.

Response

A JSON object with the query it ran, a count and a sample array of at most 10 listing objects.

{
  "query": {
    "state": "TX",
    "city": "Austin",
    "min_beds": 2,
    "max_rent": 2500
  },
  "status": "complete",
  "complete": true,
  "count": 10,
  "sample": [
    "{ listing object }",
    "..."
  ]
}

Limits

At most 10 listings per call and about 30 calls per 10 minutes per IP. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and X-API-Version: 1; a 429 adds Retry-After.

HTTP status	code
`429`	`RATE_LIMITED`
`502`	`UPSTREAM_UNAVAILABLE`
`503`	`NOT_CONFIGURED`

Need more than ten?

The sample is a preview. For a whole city or state in your product, licensed customers pull the full file from the Feed API. For research queries over the whole database, use the Data API.

Want the full file for your market?

Tell us your cities and what you are building. You get a sample in the production format and the listing count for your markets, usually within one business day.

Request a sample