openapi: 3.0.0
info:
  title: Redfin Search API
  description: |
    The Redfin Search API returns the homes Redfin lists for a place or a map area: for sale, coming soon, pending or sold. Each property includes its Redfin ID, link, address, coordinates and status, plus, when Redfin shows them, its MLS number, price, beds, baths, square footage, lot size, year built, photos, listing remarks, key facts, open house and listing agent.

    Search a city, ZIP code, neighborhood, county or state by name with `q`. City, ZIP code, neighborhood and county pages can also be searched by their Redfin URL. Search a map area with `bounding_box`. Redfin's Canadian site, `redfin.ca`, is searched by `bounding_box`. The response names the place it searched in `search_information.region`, with the total number of matching homes and their price range.

    Results come `num` homes at a time, up to 350, and `page` reaches every matching home. A place Redfin does not know, or a page past the last one, returns an `error` message in place of the results. Redfin times out on some very large states, such as Texas, and those searches end with an error.

    **Cross-linking**: a city, neighborhood, county or ZIP code `search_information.region.link` is a Redfin URL that `q` accepts, and each property's `link` opens its Redfin page.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Redfin Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine to use for the search
          schema:
            type: string
            enum: ["redfin_search"]
            default: "redfin_search"
        - name: q
          in: query
          required: false
          description: A city, ZIP code, neighborhood, county or state, such as `Seattle, WA` or `98101`, or a Redfin city, neighborhood, county or ZIP code URL, such as `https://www.redfin.com/city/16163/WA/Seattle`. URL filters, status paths, query parameters and fragments are not accepted. Use `listing_status`, `home_type` and price parameters to filter results. Either `q` or `bounding_box` is required.
          schema:
            type: string
        - name: bounding_box
          in: query
          required: false
          description: 'Map area to search, as `[[north,east],[south,west]]`: the top-right corner first, then the bottom-left corner, such as `[[47.63,-122.32],[47.60,-122.36]]`. URL filters, status paths, query parameters and fragments are not accepted. Use `listing_status`, `home_type` and price parameters to filter results. Either `q` or `bounding_box` is required.'
          schema:
            type: string
        - name: redfin_domain
          in: query
          required: false
          description: Redfin site to search. `redfin.ca` lists Canadian homes and is searched with `bounding_box`.
          schema:
            type: string
            enum: ["redfin.com", "redfin.ca"]
            default: "redfin.com"
        - name: listing_status
          in: query
          required: false
          description: Listing status to search. `for_sale` includes homes coming soon, and `pending` includes contingent homes.
          schema:
            type: string
            enum: ["for_sale", "coming_soon", "pending", "sold"]
            default: "for_sale"
        - name: sold_within_days
          in: query
          required: false
          description: Number of days back a sold search reaches. Applies to `listing_status=sold` only, where it defaults to `90`.
          schema:
            type: integer
            enum: [7, 30, 90, 180, 365, 730, 1095, 1825]
        - name: home_type
          in: query
          required: false
          description: Comma-separated home types to include, such as `condo,townhouse`. Supported values are `house`, `condo`, `townhouse`, `multi_family`, `land`, `other`, `manufactured` and `co_op`. All types are included by default.
          schema:
            type: string
        - name: price_min
          in: query
          required: false
          description: Minimum price, in US dollars on `redfin.com` and Canadian dollars on `redfin.ca`.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: price_max
          in: query
          required: false
          description: Maximum price, in US dollars on `redfin.com` and Canadian dollars on `redfin.ca`.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: beds_min
          in: query
          required: false
          description: Minimum number of bedrooms. `0` includes studios.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: beds_max
          in: query
          required: false
          description: Maximum number of bedrooms.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: baths_min
          in: query
          required: false
          description: Minimum number of bathrooms, such as `1.5`.
          schema:
            type: number
            minimum: 0
        - name: sqft_min
          in: query
          required: false
          description: Minimum interior size in square feet.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: sqft_max
          in: query
          required: false
          description: Maximum interior size in square feet.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: lot_size_min
          in: query
          required: false
          description: Minimum lot size in square feet. An acre is `43560`.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: lot_size_max
          in: query
          required: false
          description: Maximum lot size in square feet.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: year_built_min
          in: query
          required: false
          description: Earliest year built.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: year_built_max
          in: query
          required: false
          description: Latest year built.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: hoa_max
          in: query
          required: false
          description: Maximum monthly HOA fee. `0` keeps homes without an HOA fee.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: parking_spots
          in: query
          required: false
          description: Minimum number of parking spots.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: stories_min
          in: query
          required: false
          description: Minimum number of stories.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: days_on_redfin
          in: query
          required: false
          description: Keeps homes listed on Redfin for at most this many days.
          schema:
            type: integer
            enum: [1, 3, 7, 14, 30]
        - name: has_garage
          in: query
          required: false
          description: Set to `true` to keep homes with a garage.
          schema:
            type: boolean
        - name: has_pool
          in: query
          required: false
          description: Set to `true` to keep homes with a pool.
          schema:
            type: boolean
        - name: is_waterfront
          in: query
          required: false
          description: Set to `true` to keep waterfront homes.
          schema:
            type: boolean
        - name: is_open_house
          in: query
          required: false
          description: Set to `true` to keep homes with an upcoming open house.
          schema:
            type: boolean
        - name: is_new_construction
          in: query
          required: false
          description: Set to `true` to keep new construction homes.
          schema:
            type: boolean
        - name: sort_by
          in: query
          required: false
          description: Sort order. `newest` puts the most recently listed homes first, `sqft` and `lot_size` the largest first, `price_per_sqft` the lowest price per square foot first, and `recently_sold` the latest sales first in a sold search.
          schema:
            type: string
            enum: ["relevance", "newest", "price_asc", "price_desc", "sqft", "lot_size", "price_per_sqft", "recently_sold"]
            default: "relevance"
        - name: page
          in: query
          required: false
          description: Results page number. Each page holds `num` homes, and pages run to the last matching home.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: num
          in: query
          required: false
          description: Number of homes per page.
          schema:
            type: integer
            minimum: 1
            maximum: 350
            default: 40
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        properties:
          type: array
          items:
            $ref: '#/components/schemas/Property'
          description: Homes on the results page, in the order Redfin lists them
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Message explaining why the search returned no results
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Redfin URL of the place searched
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Engine used for the search
        q:
          type: string
          description: Place or Redfin region URL searched
        bounding_box:
          type: string
          description: Map area searched
        redfin_domain:
          type: string
          description: Redfin site searched
        listing_status:
          type: string
          description: Listing status searched
        sold_within_days:
          type: string
          description: Number of days back the sold search reached
        home_type:
          type: string
          description: Home types included
        price_min:
          type: string
          description: Minimum price applied
        price_max:
          type: string
          description: Maximum price applied
        beds_min:
          type: string
          description: Minimum number of bedrooms applied
        beds_max:
          type: string
          description: Maximum number of bedrooms applied
        baths_min:
          type: string
          description: Minimum number of bathrooms applied
        sqft_min:
          type: string
          description: Minimum square footage applied
        sqft_max:
          type: string
          description: Maximum square footage applied
        lot_size_min:
          type: string
          description: Minimum lot size applied
        lot_size_max:
          type: string
          description: Maximum lot size applied
        year_built_min:
          type: string
          description: Earliest year built applied
        year_built_max:
          type: string
          description: Latest year built applied
        hoa_max:
          type: string
          description: Maximum monthly HOA fee applied
        parking_spots:
          type: string
          description: Minimum number of parking spots applied
        stories_min:
          type: string
          description: Minimum number of stories applied
        days_on_redfin:
          type: string
          description: Maximum number of days on Redfin applied
        has_garage:
          type: string
          description: Garage filter applied
        has_pool:
          type: string
          description: Pool filter applied
        is_waterfront:
          type: string
          description: Waterfront filter applied
        is_open_house:
          type: string
          description: Open house filter applied
        is_new_construction:
          type: string
          description: New construction filter applied
        sort_by:
          type: string
          description: Sort order applied
        page:
          type: string
          description: Results page number
        num:
          type: string
          description: Number of homes per page
    SearchInformation:
      type: object
      properties:
        total_results:
          type: integer
          description: Number of homes that match the search
        min_price:
          type: integer
          description: Lowest price among the homes that match the search
        max_price:
          type: integer
          description: Highest price among the homes that match the search
        average_price:
          type: integer
          description: Average price of the homes that match the search
        region:
          $ref: '#/components/schemas/Region'
    Region:
      type: object
      required: [id, type, name, link]
      properties:
        id:
          type: string
          description: Redfin ID of the place searched
        type:
          type: string
          enum: ["city", "neighborhood", "zipcode", "county", "state"]
          description: Kind of place searched
        name:
          type: string
          description: Name of the place searched with its city, state and country
        link:
          type: string
          description: Redfin URL of the place searched
    Property:
      type: object
      required: [position, property_id, link, address, city, state, zipcode, country, latitude, longitude, currency, home_type, home_status]
      properties:
        position:
          type: integer
          description: Position of the home in the results, counting from the first page
        property_id:
          type: string
          description: Redfin ID of the property
        listing_id:
          type: string
          description: Redfin ID of the listing
        mls:
          $ref: '#/components/schemas/Mls'
        link:
          type: string
          description: Redfin URL of the property
        address:
          type: string
          description: Full address of the property
        street:
          type: string
          description: Street address without the unit
        unit:
          type: string
          description: Unit number
        city:
          type: string
          description: City
        state:
          type: string
          description: State or province code
        zipcode:
          type: string
          description: ZIP or postal code
        country:
          type: string
          description: Two-letter country code
        neighborhood:
          type: string
          description: Neighborhood the property is in
        latitude:
          type: number
          description: Latitude of the property
        longitude:
          type: number
          description: Longitude of the property
        price:
          type: string
          description: Formatted price of the home
        extracted_price:
          type: integer
          description: Price of the home as a number
        is_last_list_price:
          type: boolean
          description: Whether the price of a sold home is its last list price because the sale price is not public
        currency:
          type: string
          description: Currency code of the price
        price_per_sqft:
          type: integer
          description: Price per square foot
        hoa_fee:
          type: integer
          description: Monthly HOA fee
        beds:
          type: integer
          description: Number of bedrooms
        baths:
          type: number
          description: Number of bathrooms, with a half bathroom counted as 0.5
        baths_full:
          type: integer
          description: Number of full bathrooms
        baths_half:
          type: integer
          description: Number of half bathrooms
        sqft:
          type: integer
          description: Interior size in square feet
        lot_sqft:
          type: integer
          description: Lot size in square feet
        year_built:
          type: integer
          description: Year the home was built
        stories:
          type: number
          description: Number of stories
        home_type:
          type: string
          enum: ["house", "condo", "townhouse", "multi_family", "land", "other", "manufactured", "co_op"]
          description: Type of home
        home_status:
          type: string
          enum: ["for_sale", "coming_soon", "pending", "sold"]
          description: Listing status of the home
        status_text:
          type: string
          description: Listing status as the listing service words it
        days_on_market:
          type: integer
          description: Number of days the home has been on the market
        date_sold:
          type: string
          format: date
          description: Date of the home's most recent sale
        open_house:
          $ref: '#/components/schemas/OpenHouse'
        thumbnail:
          type: string
          description: URL of the first photo as a thumbnail
        images:
          type: array
          items:
            type: string
          description: URLs of the listing's photos
        photo_count:
          type: integer
          description: Number of photos of the listing
        description:
          type: string
          description: Listing remarks, which Redfin shortens in search results
        key_facts:
          type: array
          items:
            type: string
          description: Short facts Redfin highlights about the home
        tags:
          type: array
          items:
            type: string
          description: Feature tags from the listing
        badges:
          type: array
          items:
            type: string
          description: Badges Redfin shows on the home's card
        broker:
          type: string
          description: Name of the listing brokerage
        agents:
          type: array
          items:
            $ref: '#/components/schemas/Agent'
          description: Agents of the sale
        virtual_tour:
          type: string
          description: URL of the 3D walkthrough
        has_3d_tour:
          type: boolean
          description: Whether the listing has a 3D walkthrough
        has_video_tour:
          type: boolean
          description: Whether the listing has a video tour
        has_virtual_tour:
          type: boolean
          description: Whether the listing has a virtual tour
        has_floor_plan:
          type: boolean
          description: Whether the listing has an interactive floor plan
        is_redfin:
          type: boolean
          description: Whether Redfin is the listing brokerage
        is_hot:
          type: boolean
          description: Whether Redfin expects the home to sell soon
        is_new_construction:
          type: boolean
          description: Whether the home is new construction
        builder_name:
          type: string
          description: Name of the builder of a new construction home
    Mls:
      type: object
      required: [id]
      properties:
        id:
          type: string
          description: Listing number in the listing service
        name:
          type: string
          description: Name of the listing service
    OpenHouse:
      type: object
      required: [start_date, end_date, description]
      properties:
        start_date:
          type: string
          format: date-time
          description: Start of the next open house in the home's time zone
        end_date:
          type: string
          format: date-time
          description: End of the next open house in the home's time zone
        description:
          type: string
          description: Open house title as the listing gives it
    Agent:
      type: object
      required: [type, name]
      properties:
        type:
          type: string
          enum: ["listing", "buyer"]
          description: Side of the sale the agent represented
        name:
          type: string
          description: Name of the agent
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page number
        total_results:
          type: integer
          description: Number of homes that match the search
        total_pages:
          type: integer
          description: Number of pages that hold the matching homes
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
