openapi: 3.0.0
info:
  title: Realtor.com Search API
  description: |
    Search Realtor.com listings in the United States: homes for sale, rentals, recently sold homes and pending sales.

    Properties come with their address, coordinates, price, beds, baths, square footage, lot size, year built, home type, listing flags, photos, tags, open houses, HOA fee, pet policy, MLS details, listing agents and Realtor.com's estimated value when available.

    Search by a location (city, ZIP code, neighborhood, county, state or school district), a map area, or a circle around a point, and filter by price, beds, baths, size, year built, HOA fee, garage spaces, time on market, keywords, home type and features such as a pool or a basement.

    Realtor.com returns at most the first 10,000 results of a search. Narrow a larger search with filters or a smaller area to reach the rest.

    **Cross-linking**: parameters and property fields this API shares with the Zillow API have the same names there.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Realtor.com Property Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["realtor_search"]
            default: "realtor_search"
        - name: q
          in: query
          required: false
          description: 'Location to search in the United States: a city and state, ZIP code, neighborhood, county, state or school district (e.g., "Seattle, WA", "98101", "King County, WA"). A two-letter state code searches the whole state. Either q, bounding_box, or lat, lon and radius are required.'
          schema:
            type: string
            maxLength: 100
        - name: bounding_box
          in: query
          required: false
          description: 'Map area to search in. Format: [[ne_lat,ne_lng],[sw_lat,sw_lng]]. Cannot be used together with q or with lat, lon and radius.'
          schema:
            type: string
        - name: lat
          in: query
          required: false
          description: Latitude of the center of a circle to search in. Use it with lon and radius.
          schema:
            type: number
            minimum: -90
            maximum: 90
        - name: lon
          in: query
          required: false
          description: Longitude of the center of the circle. Use it with lat and radius.
          schema:
            type: number
            minimum: -180
            maximum: 180
        - name: radius
          in: query
          required: false
          description: Radius in miles. With lat and lon it is the radius of the circle, and with q it widens the location by this many miles.
          schema:
            type: number
            minimum: 0
            exclusiveMinimum: true
            maximum: 50
        - name: listing_status
          in: query
          required: false
          description: Type of listing to search for. `for_sale` includes pending and contingent sales, and `pending` returns only those.
          schema:
            type: string
            enum: ["for_sale", "for_rent", "sold", "pending"]
            default: "for_sale"
        - name: home_type
          in: query
          required: false
          description: 'Comma-separated list of property types to include: `house`, `condo`, `townhouse`, `multi_family`, `apartment`, `land`, `manufactured` and `farm`.'
          schema:
            type: string
        - name: price_min
          in: query
          required: false
          description: Minimum price in US dollars, the monthly rent for rentals.
          schema:
            type: number
            minimum: 0
        - name: price_max
          in: query
          required: false
          description: Maximum price in US dollars, the monthly rent for rentals.
          schema:
            type: number
            minimum: 0
        - name: beds_min
          in: query
          required: false
          description: Minimum number of bedrooms.
          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.
          schema:
            type: number
            minimum: 0
        - name: baths_max
          in: query
          required: false
          description: Maximum number of bathrooms.
          schema:
            type: number
            minimum: 0
        - name: sqft_min
          in: query
          required: false
          description: Minimum living area in square feet.
          schema:
            type: number
            minimum: 0
        - name: sqft_max
          in: query
          required: false
          description: Maximum living area in square feet.
          schema:
            type: number
            minimum: 0
        - name: lot_size_min
          in: query
          required: false
          description: Minimum lot size in square feet.
          schema:
            type: number
            minimum: 0
        - name: lot_size_max
          in: query
          required: false
          description: Maximum lot size in square feet.
          schema:
            type: number
            minimum: 0
        - name: year_built_min
          in: query
          required: false
          description: Earliest year built.
          schema:
            type: integer
            minimum: 1800
            maximum: 2147483647
        - name: year_built_max
          in: query
          required: false
          description: Latest year built.
          schema:
            type: integer
            minimum: 1800
            maximum: 2147483647
        - name: hoa_max
          in: query
          required: false
          description: Maximum monthly HOA fee in US dollars.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
        - name: parking_spots
          in: query
          required: false
          description: Minimum number of garage spaces.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: days_on_realtor
          in: query
          required: false
          description: Only listings added within this many days, or months for values ending in `m`. On sold listings, only homes sold within that time.
          schema:
            type: string
            enum: ["1", "7", "14", "30", "90", "6m", "12m", "24m", "36m"]
        - name: keywords
          in: query
          required: false
          description: Comma-separated keywords the listing must mention.
          schema:
            type: string
        - name: has_pool
          in: query
          required: false
          description: Only homes with a swimming pool.
          schema:
            type: boolean
        - name: has_garage
          in: query
          required: false
          description: Only homes with a garage.
          schema:
            type: boolean
        - name: has_ac
          in: query
          required: false
          description: Only homes with central air conditioning.
          schema:
            type: boolean
        - name: has_basement
          in: query
          required: false
          description: Only homes with a basement.
          schema:
            type: boolean
        - name: is_waterfront
          in: query
          required: false
          description: Only waterfront homes.
          schema:
            type: boolean
        - name: is_single_story
          in: query
          required: false
          description: Only single-story homes.
          schema:
            type: boolean
        - name: is_open_house
          in: query
          required: false
          description: Only homes with an open house in the next 7 days.
          schema:
            type: boolean
        - name: is_new_construction
          in: query
          required: false
          description: Only new construction.
          schema:
            type: boolean
        - name: is_foreclosure
          in: query
          required: false
          description: Only foreclosures.
          schema:
            type: boolean
        - name: is_dog_friendly
          in: query
          required: false
          description: Only homes that allow dogs.
          schema:
            type: boolean
        - name: is_cat_friendly
          in: query
          required: false
          description: Only homes that allow cats.
          schema:
            type: boolean
        - name: sort_by
          in: query
          required: false
          description: Sort order. Without it, Realtor.com's relevance order, or the newest sale first on sold listings. On sold listings, `newest` and the price sorts use the sale.
          schema:
            type: string
            enum: ["relevance", "newest", "price_asc", "price_desc", "beds", "baths", "sqft", "lot_size", "photo_count", "last_updated"]
        - name: page
          in: query
          required: false
          description: Page number. Realtor.com returns at most the first 10,000 results of a search, so the last page is 10,000 divided by num, rounded up.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: num
          in: query
          required: false
          description: Number of properties per page.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 42
      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
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        properties:
          type: array
          description: Properties on this page.
          items:
            $ref: '#/components/schemas/Property'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Message explaining why the search returned no properties, such as a location Realtor.com could not find.
    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: Realtor.com URL for this search
        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
        q:
          type: string
        bounding_box:
          type: string
        lat:
          type: string
        lon:
          type: string
        radius:
          type: string
        listing_status:
          type: string
        home_type:
          type: string
        price_min:
          type: string
        price_max:
          type: string
        beds_min:
          type: string
        beds_max:
          type: string
        baths_min:
          type: string
        baths_max:
          type: string
        sqft_min:
          type: string
        sqft_max:
          type: string
        lot_size_min:
          type: string
        lot_size_max:
          type: string
        year_built_min:
          type: string
        year_built_max:
          type: string
        hoa_max:
          type: string
        parking_spots:
          type: string
        days_on_realtor:
          type: string
        keywords:
          type: string
        has_pool:
          type: string
        has_garage:
          type: string
        has_ac:
          type: string
        has_basement:
          type: string
        is_waterfront:
          type: string
        is_single_story:
          type: string
        is_open_house:
          type: string
        is_new_construction:
          type: string
        is_foreclosure:
          type: string
        is_dog_friendly:
          type: string
        is_cat_friendly:
          type: string
        sort_by:
          type: string
        page:
          type: string
        num:
          type: string
    SearchInformation:
      type: object
      required: [total_results]
      properties:
        total_results:
          type: integer
          description: Number of properties Realtor.com matched for the search.
    Property:
      type: object
      required: [position, property_id, address, state, link, home_status]
      properties:
        position:
          type: integer
          description: Position on this page, starting at 1.
        property_id:
          type: string
          description: Realtor.com property identifier.
        listing_id:
          type: string
          description: Realtor.com identifier of this listing of the property.
        address:
          type: string
          description: Full address.
        street:
          type: string
          description: Street address without the unit.
        unit:
          type: string
          description: Unit or apartment number.
        city:
          type: string
          description: City.
        state:
          type: string
          description: Two-letter state code.
        zipcode:
          type: string
          description: ZIP code.
        county:
          type: string
          description: County.
        latitude:
          type: number
          description: Latitude.
        longitude:
          type: number
          description: Longitude.
        price:
          type: string
          description: Price as Realtor.com shows it, a monthly range for rental buildings.
        extracted_price:
          type: integer
          description: Price in US dollars, the sale price for sold homes, the monthly rent for rentals and the lowest rent for rental buildings.
        min_base_rent:
          type: integer
          description: Lowest monthly rent in a rental building.
        max_base_rent:
          type: integer
          description: Highest monthly rent in a rental building.
        list_price:
          type: integer
          description: Asking price of a sold home before its sale.
        price_change:
          type: integer
          description: Price cut since the home was listed, as a negative number of US dollars.
        price_per_sqft:
          type: integer
          description: Price per square foot in US dollars.
        last_sold_price:
          type: integer
          description: Price of the home's previous sale.
        last_sold_date:
          type: string
          format: date
          description: Date of the home's previous sale.
        date_sold:
          type: string
          format: date
          description: Date a sold home sold.
        date_pending:
          type: string
          format: date-time
          description: Time the sale or lease went pending.
        list_date:
          type: string
          format: date-time
          description: Time the home was listed.
        last_updated:
          type: string
          format: date-time
          description: Time the listing last changed.
        beds:
          type: integer
          description: Number of bedrooms.
        beds_min:
          type: integer
          description: Fewest bedrooms among the units of a rental building.
        beds_max:
          type: integer
          description: Most bedrooms among the units of a rental building.
        baths:
          type: number
          description: Number of bathrooms, with a half bathroom as 0.5.
        baths_text:
          type: string
          description: Bathrooms as Realtor.com shows them, such as `2.5` or `4.5+` for four full and more than one half bathroom.
        baths_min:
          type: number
          description: Fewest bathrooms among the units of a rental building.
        baths_max:
          type: number
          description: Most bathrooms among the units of a rental building.
        baths_full:
          type: integer
          description: Number of full bathrooms.
        baths_half:
          type: integer
          description: Number of half bathrooms.
        sqft:
          type: integer
          description: Living area in square feet.
        sqft_min:
          type: integer
          description: Smallest living area among the units of a rental building, in square feet.
        sqft_max:
          type: integer
          description: Largest living area among the units of a rental building, in square feet.
        lot_sqft:
          type: integer
          description: Lot size in square feet.
        year_built:
          type: integer
          description: Year built.
        stories:
          type: integer
          description: Number of stories.
        garage:
          type: integer
          description: Number of garage spaces.
        home_type:
          type: string
          description: Realtor.com home type, such as `single_family`, `condos`, `townhomes` or `apartment`.
        home_sub_type:
          type: string
          description: Realtor.com home sub type, such as `condo` or `townhouse`.
        home_status:
          type: string
          description: Listing status, `for_sale`, `for_rent` or `sold`.
        building_name:
          type: string
          description: Name of the building or community.
        units:
          type: array
          description: Units listed for rent in the building.
          items:
            $ref: '#/components/schemas/Unit'
        hoa_fee:
          type: integer
          description: Monthly HOA fee in US dollars.
        thumbnail:
          type: string
          description: URL of the main photo.
        images:
          type: array
          description: URLs of the listing photos.
          items:
            type: string
        photo_count:
          type: integer
          description: Number of photos in the listing.
        has_3d_model:
          type: boolean
          description: Whether the listing has a 3D tour.
        virtual_tour:
          type: string
          description: URL of the listing's virtual tour.
        link:
          type: string
          description: URL of the listing on Realtor.com.
        is_new_listing:
          type: boolean
          description: Whether Realtor.com marks the listing as new.
        is_pending:
          type: boolean
          description: Whether the sale is pending.
        is_contingent:
          type: boolean
          description: Whether the sale is contingent.
        is_foreclosure:
          type: boolean
          description: Whether the home is a foreclosure.
        is_price_reduced:
          type: boolean
          description: Whether the price was cut.
        is_new_construction:
          type: boolean
          description: Whether the home is new construction.
        is_coming_soon:
          type: boolean
          description: Whether the listing is coming soon.
        tags:
          type: array
          description: Realtor.com feature tags, such as `garage_1_or_more` or `central_air`.
          items:
            type: string
        open_house:
          type: array
          description: Upcoming open houses.
          items:
            $ref: '#/components/schemas/OpenHouse'
        pet_policy:
          $ref: '#/components/schemas/PetPolicy'
        broker:
          type: string
          description: Name of the listing office.
        mls:
          $ref: '#/components/schemas/Mls'
        agents:
          type: array
          description: Agents and managers who list the home.
          items:
            $ref: '#/components/schemas/Agent'
        estimated_value:
          type: integer
          description: Estimated value of the home in US dollars, as Realtor.com shows it.
    OpenHouse:
      type: object
      required: [start_date, end_date]
      properties:
        start_date:
          type: string
          description: Local start time of the open house.
        end_date:
          type: string
          description: Local end time of the open house.
        description:
          type: string
          description: Note about the open house.
    Unit:
      type: object
      properties:
        price:
          type: string
          description: Rent as Realtor.com shows it.
        extracted_price:
          type: integer
          description: Monthly rent in US dollars.
        beds:
          type: integer
          description: Number of bedrooms.
        baths:
          type: number
          description: Number of bathrooms, with a half bathroom as 0.5.
        sqft:
          type: integer
          description: Living area in square feet.
        availability_date:
          type: string
          format: date
          description: Date the unit is available.
    PetPolicy:
      type: object
      description: Whether the listing allows dogs and cats.
      properties:
        dogs:
          type: string
          enum: ["allowed", "not_allowed"]
          description: Whether dogs are allowed.
        cats:
          type: string
          enum: ["allowed", "not_allowed"]
          description: Whether cats are allowed.
    Mls:
      type: object
      required: [id, name, listing_id]
      properties:
        id:
          type: string
          description: Identifier of the multiple listing service.
        name:
          type: string
          description: Name of the multiple listing service.
        listing_id:
          type: string
          description: Listing number in the multiple listing service.
    Agent:
      type: object
      required: [type]
      properties:
        type:
          type: string
          description: Role, such as `seller`, `co_seller`, `management` or `community`.
        name:
          type: string
          description: Name of the agent or manager.
        phone:
          type: string
          description: Phone number.
        office:
          type: string
          description: Office name.
        broker:
          type: string
          description: Broker name.
    Pagination:
      type: object
      required: [current, total_results, total_pages]
      properties:
        current:
          type: integer
          description: Current page number.
        total_results:
          type: integer
          description: Number of properties Realtor.com matched for the search.
        total_pages:
          type: integer
          description: Number of pages within the first 10,000 results.
        next:
          type: string
          description: Realtor.com URL of the next page.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
