Documentation

Build with HousingFeed.

Start with the product you use. Display Feed delivery and Data API access have different setup instructions and usage rights.

Display Feed

From sample to integration.

Review a sample for your locations, then agree the delivery format and access details during setup. CSV and JSON exports are available; API delivery is arranged for your agreed scope.

  1. Check your sample.

    Inspect the populated fields, missing values and source links. Confirm the locations and listing details your product needs.

  2. Agree delivery and identifiers.

    Use the schema supplied with your sample. Customer exports use uid as the stable identifier; the Data API below uses id. Confirm the format before building your importer.

  3. Apply weekly updates.

    Add new records, update changed records by their identifier and remove delisted records from display on your next sync. Keep the source URL and verification date with each record.

Customer export fields

These are the current CSV columns, generated from the export format. JSON exports can contain additional fields; your supplied sample defines the format for your integration.

GroupCSV fields
Identity & sourceuid, listing_id, url, publisher_name
Locationaddress, street, city, state, zip, lat, lng
Rentrent_min, rent_max, rent_usd
Propertybeds, baths, sqft_min, sqft_max, property_type, furnished
Availability & contentavailable, image, n_photos, description, amenities
Verificationlast_seen_at

Missing values are not zero: preserve nulls in JSON and empty CSV cells. Zero bedrooms means a studio. Keep ZIP codes as strings so leading zeros survive.

Keep attribution with the listing.

Show the publishing manager or owner, link to the source listing and send enquiries there. Display photos using the supplied URLs. The public Data API and its credentials do not grant display rights.

Display rights →Licence terms →
Data API · internal use

Data API reference

The reference below covers the Apify Data API: authentication, query parameters, response fields and examples. It includes manager-direct sources and consumer portals. Public display requires a separate Display Feed licence.

Price: $3 per 1,000 rows on Apify (internal use only).

Data API product overview →

Try it live, no key needed

Preview up to 10 records. This public sample endpoint is a preview tool; the authenticated Data API endpoint and parameters are documented below.

GET /api/v1/sample live sample

Quickstart

The Data API is delivered as an Apify actor. You send one POST request with your filters as JSON and get an array of listing rows back synchronously. No SDK, no proxies, no infrastructure on your side.

One call to try it: replace YOUR_TOKEN with your Apify API token and run the request below. Leave the body as {} to get the freshest rows across all sources.
# 2-bed listings in Austin, TX under $2,500 a month
curl -X POST "https://api.apify.com/v2/acts/housingfeed~rental-listings-api/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"country":"US","state":"TX","city":"Austin","minBeds":2,"maxRent":2500,"maxItems":200}'

To request CSV from the endpoint above, append &format=csv after the token parameter.

Authentication

Every request needs your Apify API token, passed as a query-string parameter. You find it in your Apify account under Settings, Integrations. Keep it secret and treat it like a password.

No account yet? Open the Data API on Apify. Check the current pricing and account requirements before running a query.

Endpoint

MethodPOST
URLhttps://api.apify.com/v2/acts/housingfeed~rental-listings-api/run-sync-get-dataset-items
Query?token=YOUR_TOKEN
BodyJSON object of filters (all optional). See Input parameters.
ReturnsJSON array of listing rows. See Response schema.

run-sync-get-dataset-items runs the actor and returns the dataset in one blocking call, which suits direct queries. For large or scheduled pulls, use the standard async Apify run endpoints and read the dataset when the run finishes.

Input parameters

All fields are optional. Send an empty body {} to get the freshest rows across all sources and countries. This table is generated from the actor's input schema.

FieldTypeDescription
countrystringCountry code, one of US, CA, UK, PL, BE, IT, NO, ES, FR, DE, NL, IE, EU. US is the maintained market, re-read weekly; other countries are older portal snapshots. Blank = all countries.
statestringUS state code (CA, NY, TX) or region. Blank = all.
citystringCity name, partial match (for example Los Angeles), or a county (Hudson County; add the state when the name exists in several states). Blank = all.
zipstringExact ZIP or postal code, for example 94110. Blank = all.
minRent, maxRentintegerMonthly rent range, in the listing's own currency.
minBeds, maxBedsintegerBedroom range. Equal values match an exact bedroom count.
managerDirectOnlybooleanOnly listings published by property managers and owners on their own software or websites, no consumer portals. Default false. See the manager-direct example.
includePortalsbooleanAlso return listings from consumer portals and other countries, licensed for research and internal use only. Default false.
availableNowbooleanOnly listings marked available now. Default false.
withPhotosbooleanOnly listings with at least one photo. Default false.
propertyTypearray of stringsOnly these types: apartment, house, condo, townhouse, room, in any combination. Listings whose source does not state a type are left out of a filtered run. Blank = every type.
cursorstringThe nextCursor value from the previous run's OUTPUT record, with sort stable: the next page of the same query, each listing exactly once across pages. Blank on the first run.
newSinceDaysintegerNew listings only: records first seen by HousingFeed in the last N days (first_seen_at). Blank or 0 = no limit. See the new-listings example.
removedSinceDaysintegerRemovals instead of live listings: records our weekly liveness check confirmed gone at the source in the last N days (1 to 90), each with removed_at, newest first. Run it next to a newSinceDays pull and delete these ids from your copy.
timeWindowstringChanges instead of all live listings: new_7d or new_30d for listings first seen in that window, removed_7d or removed_30d for listings confirmed gone at the source, each with removed_at. Blank = all live listings. newSinceDays or removedSinceDays, if set, take precedence.
countOnlybooleanReturn one row with the number of matching listings (matched, estimated, query) instead of the listings, charged as one result. Default false.
freshDaysintegerExclude rows last collected more than N days ago (scraped_at). Default 30 (90 when country is not US); set 0 to disable the age filter (other filters and delisting exclusions still apply).
minLat, maxLatfloatBounding-box latitude bounds in decimal degrees. Pair with the longitude bounds to return only listings inside a map box.
minLng, maxLngfloatBounding-box longitude bounds. Any combination of the four bounds is allowed; geo filters return geocoded rows only, and boxes crossing the 180° antimeridian are unsupported.
sortstringResult ordering: best (default), newest, oldest, cheapest, rent_desc, stable. best puts geocoded rows with a photo first, freshest first, mixed across sources; newest and oldest order by scraped_at; cheapest and rent_desc by monthly rent.
maxItemsintegerRows to return, 1 to 25,000. Default 25. You are charged per returned row.
refreshbooleanRe-collect the portal sources live at query time instead of serving the database. Slow (minutes), portal tier only. Default false.

Response schema

The API returns a JSON array of listing rows. Every row has the same 41 fields in the same order whatever the source or country. Any field can be null. The coverage column marks fields whose fill rate depends on what the source publishes; an unmarked field is not a completeness guarantee. Inspect your sample for actual field availability. This table is generated from the API's public field list.

FieldTypeMeaningCoverage
idstringStable opaque listing key (hf_ + 20 characters), the same in every run. Dedupe on it across runs and diff a newSinceDays pull against your own store.
source_typestringmanager_direct (published by the property manager or owner on their own software or website) or portal.
listing_idstringThe source's own listing identifier.
urlstringLink to the listing at its source.
addressstringFull address as published.
streetstringStreet component of the address.
citystringCity as labelled at the source.
canonical_citystringMetro rollup of city: borough and ward labels collapse to the parent metro (New York boroughs to New York). Group on this for market-level aggregation.
statestringState or region code.
zipstringZIP or postal code.
countrystringCountry code supplied by the source or inferred from its platform.
latfloatLatitude in decimal degrees.varies by source
lngfloatLongitude in decimal degrees.varies by source
rent_minnumberLowest monthly rent advertised, in the native currency.
rent_maxnumberHighest monthly rent advertised, when supplied; may be null.
currencystringNative currency code, derived from the country.
rent_usdnumberApproximate USD rent using configured conversion rates, not a live exchange-rate quote.
rent_per_sqftnumberrent_usd divided by sqft_min; null when the size is missing or implausible.
rent_per_sqmnumberThe same figure per square metre.
bedsfloatBedroom count (0 = studio).
bathsfloatBathroom count.
sqft_minnumberLower bound of the floor area, in square feet.varies by source
sqft_maxnumberUpper bound of the floor area, in square feet.varies by source
property_typestringCommon labels include apartment, house, condo, townhouse, studio, room and other source labels.
furnishedbooleanFurnished status when supplied; null when unknown.
availablestringAvailability as published, for example "Now" or a date.varies by source
units_availableintegerUnit count for floorplan-level rows.
granularitystring"unit" or "floorplan".
imagestringPrimary photo URL.varies by source
imagesarray of stringsCollected photo URLs; not necessarily the complete source gallery.varies by source
descriptionstringCollected listing description; may be cleaned during processing.varies by source
amenitiesarray of stringsAmenity labels as published.varies by source
first_seen_atstringISO-8601 timestamp of the first time HousingFeed saw this listing.
last_seen_atstringISO-8601 timestamp of the last time the listing was verified live at its source.
scraped_atstringISO-8601 timestamp of the collection run that produced this row.
days_listedintegerWhole days since HousingFeed first saw the listing (to removed_at for a removed listing). Counts from our first sighting, so a listing live before then is understated.
neighborhoodstringOfficial neighbourhood the listing's coordinates fall in: New York City's Neighborhood Tabulation Areas and Jersey City's neighbourhoods. null elsewhere and without coordinates.varies by source
neighborhood_groupstringThe borough (New York City) or area (Jersey City) of neighborhood.varies by source
publisher_namestringWho publishes the listing, as the source states it: the community's own name, the management company behind the listing, or Private landlord. null when the source states nothing. Credit this name when you show the listing.varies by source
publisher_companystringThe management company a community page names beside the community ("managed by"), when stated. null otherwise.varies by source
rent_basisstringWhat rent_min means. per_bed: the price of one bed in a shared unit (student housing, co-living), not the rent of the whole unit. quoted_term, range or single_price: how the price relates to the lease term. null when not labelled.varies by source

Freshness fields

Three timestamps tell you how current each row is, so you can judge freshness yourself instead of trusting a label.

Delisted rows are excluded from responses. An ID missing from a filtered or capped query is not proof of removal. Reconcile only against a complete agreed snapshot or an explicit removal set; never delete records because a request failed.

Example response

One real row from the sample endpoint, rendered in schema order. The build refreshes it; the images list is shortened to three URLs for display.

[
  {
    "id": "hf_eb57be383a9cf12e1770",
    "source_type": "manager_direct",
    "listing_id": "2806628-0-311",
    "url": "https://www.camdenliving.com/apartments/dallas-tx/camden-henderson/available-apartments?unit=311",
    "address": "5222 Belmont Ave #311, Dallas, TX 75206",
    "street": "5222 Belmont Ave",
    "city": "Dallas",
    "canonical_city": null,
    "state": "TX",
    "zip": "75206",
    "country": "US",
    "lat": 32.815137,
    "lng": -96.780076,
    "rent_min": 2479,
    "rent_max": 2479,
    "currency": "USD",
    "rent_usd": 2479,
    "rent_per_sqft": 2.04,
    "rent_per_sqm": 21.96,
    "beds": 2,
    "baths": 2,
    "sqft_min": 1214,
    "sqft_max": 1214,
    "property_type": "apartment",
    "furnished": null,
    "available": "2026-12-17",
    "units_available": null,
    "granularity": "unit",
    "image": "https://images.ctfassets.net/pg6xj64qk0kh/1W3nx3z0hnEx03xCAsARR2/2ab2f134fd7b4ac25f076d4ed024f5ae/camden-henderson-apartments-dallas-tx-kitchen-living-room.jpg",
    "images": [
      "https://images.ctfassets.net/pg6xj64qk0kh/1W3nx3z0hnEx03xCAsARR2/2ab2f134fd7b4ac25f076d4ed024f5ae/camden-henderson-apartments-dallas-tx-kitchen-living-room.jpg",
      "https://images.ctfassets.net/pg6xj64qk0kh/2gpx4clED397oAFOPUw2Wm/0b6b7fe339bf4b473fb90806ed603a35/camden-henderson-apartments-dallas-tx-kitchen-with-large-island.jpg",
      "https://images.ctfassets.net/pg6xj64qk0kh/43hC6WYmfRlhfU9RpgHR1V/10429d7274e6faeba80bd85521947c88/camden-henderson-apartments-dallas-tx-exterior-building-with-dallas-skyline.jpg"
    ],
    "description": "Camden Henderson offers unique one, two and three bedroom apartment homes located in Knox-Henderson between Lower Greenville and Uptown Dallas, TX. Our office",
    "amenities": [
      "Balcony / patio",
      "Yard"
    ],
    "first_seen_at": "2026-09-08T18:10:10+00:00",
    "last_seen_at": "2026-11-15T05:29:03+00:00",
    "scraped_at": "2026-11-15T05:29:03+00:00",
    "days_listed": 68,
    "neighborhood": null,
    "neighborhood_group": null,
    "publisher_name": null,
    "publisher_company": null,
    "rent_basis": null
  }
]

Query examples

These examples use the input parameters documented above. Source filters do not grant display rights or guarantee that every matching row qualifies for the Display Feed.

New listings: first seen this week

Select rows first seen in the last seven days and deduplicate by id. This does not return changed or removed records. Results are capped by maxItems; a capped query is not a complete sync.

{ "country": "US", "state": "NY", "newSinceDays": 7, "maxItems": 1000 }

Manager-direct sources only

Restrict the query to listings published by property managers and owners on their own software or websites rather than portals. Each row's source_type says which kind it is.

{ "managerDirectOnly": true, "state": "FL", "maxItems": 2000 }
Confirm your source scope. Manager-direct sources are the ones HousingFeed can license for public display. Pulling them through the Data API is fine for internal use, analytics and research. Showing them to your users needs a Display Feed licence; the Display Feed terms set out attribution, source links and delisting.

Bounding box

Pass a map box and get the geocoded rows inside it, all sources, one schema. Downtown Miami:

{ "minLat": 25.70, "maxLat": 25.86, "minLng": -80.32, "maxLng": -80.10, "maxItems": 500 }

Freshness & cadence

Sources are not all on the same clock, and the API does not pretend they are.

Display Feed sources are checked weekly. Data API sources have different collection schedules; the dated source list below describes the saved coverage snapshot. Check each returned record’s timestamps. A scheduled refresh does not guarantee a successful verification of all records.

Every row carries first_seen_at, last_seen_at and scraped_at, and freshDays (default 30 days) keeps old snapshot rows out unless you ask for them. Confirm source scope and freshness when requesting your sample.

Display Feed sources are checked weekly. Data API source schedules vary; inspect returned timestamps and confirm freshness in your sample.

Limits & pricing

The Data API costs $3 per 1,000 rows on Apify (internal use only). Each run returns at most 25,000 rows. To read more than that, page with cursor and sort stable, or contact us for a complete export.

Versioning, rate limits and errors on housingfeed.com

The keyless sample lives at /api/v1/sample (/api/sample is an alias). Every response carries X-API-Version: 1 and the RFC RateLimit fields (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset; about 30 requests per 10 minutes per IP), with Retry-After on a 429. Errors are JSON with a stable code (RATE_LIMITED, UPSTREAM_UNAVAILABLE, NOT_FOUND) and a hint. Treat this endpoint as a preview. A partial response means some sources failed; complete describes request completion, not a complete inventory export. Results remain capped at 10 records. The full contract, including the Data API actor's input schema, is openapi.json.

Rights

The Data API grants internal use only: research, analytics, internal tools and model evaluation within the general terms. Public display requires the Display Feed licence. See the Display Feed and the Display Feed terms.

Need help integrating? Email hello@housingfeed.com and we will get you set up.
Let's talk

What are you building?

Tell us about your product and the listings you need. We’ll check the fit and send sample data, coverage details and a quote.

Prefer email? hello@housingfeed.com →

Want to look first? See 10 live listings now, no form →

US listings only (all 50 states and DC). Usually a reply within one business day. No newsletter.

Thanks. Let's build from here.

We've received your request and will usually reply within one business day.