housingfeed-com Sample API

openapi: 3.2.0
info:
  title: HousingFeed rental listings Sample API
  version: '2026-10-27'
  summary: US rental listings collected directly from property managers (Display Feed, licensed for display) and a pay-per-row Data API over the whole database.
  description: 'HousingFeed has two products on one database.


    **Display Feed**: manager-direct US rental listings, verified weekly, licensed for public display in the licensee''s product with attribution and a link back to the source (terms: https://housingfeed.com/display-feed-terms). Licensees pull it from the Feed API (`/api/v1/feed`, a key issued after an order form) or as CSV/JSONL files. Request a sample at https://housingfeed.com/display-feed#sample.


    **MCP server** for AI assistants: https://housingfeed.com/mcp (streamable HTTP). `rent_summary` and `search_rentals_sample` need no key; the feed tools read a licensee''s feed with its key.


    **Data API**: the whole database (US maintained; other countries are older portal snapshots), pay per row on Apify, internal use only (research, analytics, internal tools, model evaluation). No public display rights.


    This document describes the two machine-callable surfaces: the keyless 10-row live sample on housingfeed.com and the Data API actor on Apify. Field coverage varies by source; every field is nullable.


    **Versioning and deprecation.** The housingfeed.com endpoints are version 1, reachable at `/api/v1/sample` (canonical) and `/api/sample` (alias); every response carries `X-API-Version: 1`. Fields are only ever added, never renamed or removed, within a version. A breaking change ships as `/api/v2/...`; the old version keeps working for at least 6 months and its responses carry `Deprecation` and `Sunset` headers (RFC 8594) from the day the new version is announced, with the timeline repeated on /docs. The Data API actor follows Apify''s actor versioning; its input schema is copied into this file on every build.


    **Rate limits.** The sample endpoint allows roughly 30 requests per 10 minutes per IP and returns the RFC RateLimit header fields (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`) on every response and `Retry-After` on 429.'
  termsOfService: https://housingfeed.com/terms
  contact:
    name: HousingFeed (Iron Holding B.V.)
    url: https://housingfeed.com/contact
    email: hello@housingfeed.com
servers:
- url: https://housingfeed.com
  description: housingfeed.com (keyless sample)
tags:
- name: Sample
paths:
  /api/v1/sample:
    get:
      operationId: getLiveSample
      summary: Ten real listings from the live database, no key (v1; /api/sample is an alias)
      description: Same query semantics as the Data API, hard-capped at 10 rows, roughly 30 requests per 10 minutes per IP. Use `tier=display` to see only listings that are in the Display Feed universe.
      parameters:
      - name: country
        in: query
        required: false
        schema:
          type: string
        description: Country code, e.g. `US`. With `tier=display` only `US` is valid.
      - name: state
        in: query
        required: false
        schema:
          type: string
        description: US state code, e.g. `TX`.
      - name: city
        in: query
        required: false
        schema:
          type: string
        description: City name, substring match.
      - name: min_rent
        in: query
        required: false
        schema:
          type: number
        description: 'Minimum monthly rent (in the listing''s currency). Alias: `minRent`.'
      - name: max_rent
        in: query
        required: false
        schema:
          type: number
        description: 'Maximum monthly rent. Alias: `maxRent`.'
      - name: min_beds
        in: query
        required: false
        schema:
          type: integer
        description: 'Minimum bedrooms. Alias: `minBeds`.'
      - name: max_beds
        in: query
        required: false
        schema:
          type: integer
        description: 'Maximum bedrooms. Alias: `maxBeds`.'
      - name: min_lat
        in: query
        required: false
        schema:
          type: number
        description: 'Bounding box, south edge. Alias: `minLat`.'
      - name: max_lat
        in: query
        required: false
        schema:
          type: number
        description: 'Bounding box, north edge. Alias: `maxLat`.'
      - name: min_lng
        in: query
        required: false
        schema:
          type: number
        description: 'Bounding box, west edge. Alias: `minLng`.'
      - name: max_lng
        in: query
        required: false
        schema:
          type: number
        description: 'Bounding box, east edge. Alias: `maxLng`.'
      - name: fresh_days
        in: query
        required: false
        schema:
          type: integer
          default: 90
        description: 'Only rows read in the last N days. Default 90; with `tier=display` capped at the Display Feed window (30). Alias: `freshDays`.'
      - name: new_since_days
        in: query
        required: false
        schema:
          type: integer
        description: 'Only rows first seen in the last N days (delta feed). Alias: `newSinceDays`.'
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - best
          - newest
          - oldest
          - cheapest
          - rent_desc
          default: best
        description: Ordering. `best` ranks geocoded rows with a photo first and spreads across sources.
      - name: tier
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
        description: '`display` restricts to the Display Feed universe: manager-direct US sources, live at source within 30 days, rent in a plausible band.'
      - name: require_photo
        in: query
        required: false
        schema:
          type: string
          enum:
          - '1'
        description: 'Only rows with a photo. Alias: `requirePhoto`.'
      - name: require_geo
        in: query
        required: false
        schema:
          type: string
          enum:
          - '1'
        description: 'Only rows with coordinates. Alias: `requireGeo`.'
      responses:
        '200':
          description: Up to 10 listings.
          headers:
            RateLimit-Limit:
              schema:
                type: string
              description: Requests allowed per window (about 30 per 10 minutes per IP).
            RateLimit-Remaining:
              schema:
                type: string
              description: Requests left in the current window.
            RateLimit-Reset:
              schema:
                type: string
              description: Seconds until the window resets.
            X-API-Version:
              schema:
                type: string
              description: API version header.
      tags:
      - Sample
externalDocs:
  description: Human documentation
  url: https://housingfeed.com/docs