realtor Properties API

openapi: 3.1.0
info:
  title: Realtor.com Property Data Agents Properties API
  description: The Realtor.com Property Data API provides programmatic access to real estate listing data from Realtor.com, one of the largest property listing platforms in the United States. It offers endpoints for searching properties by location, price range, bedrooms, bathrooms, and other criteria, as well as retrieving detailed property information including listing status, photos, and neighborhood data. The API supports both for-sale and for-rent property searches and provides access to school ratings, market trends, and comparable property data that developers can use to build real estate applications and analytics tools. The API is available through RapidAPI.
  version: '2.0'
  contact:
    name: Realtor.com API Support
    url: https://rapidapi.com/apidojo/api/realty-in-us
  termsOfService: https://www.realtor.com/terms
servers:
- url: https://realtor.p.rapidapi.com
  description: RapidAPI Production Server
security:
- rapidApiKey: []
tags:
- name: Properties
  description: Endpoints for searching, listing, and retrieving detailed property information including for-sale, for-rent, and recently sold listings.
paths:
  /properties/v3/list:
    post:
      operationId: listProperties
      summary: List properties
      description: Searches and returns a list of properties matching the specified criteria. Supports filtering by status (for sale, for rent, sold), location, price range, property type, number of bedrooms and bathrooms, lot size, and other attributes. Results can be sorted and paginated.
      tags:
      - Properties
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PropertyListRequest'
      responses:
        '200':
          description: Successfully returned property listings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyListResponse'
        '400':
          description: Bad request due to invalid search parameters
        '401':
          description: Unauthorized due to missing or invalid API key
        '429':
          description: Rate limit exceeded
  /properties/v2/detail:
    get:
      operationId: getPropertyDetail
      summary: Get property detail
      description: Returns comprehensive details for a specific property identified by its property ID. Includes listing information, price history, tax records, property features, photos, neighborhood data, nearby schools, and comparable properties.
      tags:
      - Properties
      parameters:
      - $ref: '#/components/parameters/propertyId'
      responses:
        '200':
          description: Successfully returned property details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyDetailResponse'
        '400':
          description: Bad request due to invalid property ID
        '401':
          description: Unauthorized due to missing or invalid API key
        '404':
          description: Property not found
        '429':
          description: Rate limit exceeded
  /properties/v2/list-by-mls:
    get:
      operationId: listPropertiesByMls
      summary: List properties by MLS
      description: Returns properties matching specific MLS (Multiple Listing Service) identifiers. Use this endpoint when you have MLS IDs and need to retrieve the corresponding property listings.
      tags:
      - Properties
      parameters:
      - name: mls_id
        in: query
        required: true
        description: The MLS identifier to search for. Can be a single MLS ID or a comma-separated list of MLS IDs.
        schema:
          type: string
      responses:
        '200':
          description: Successfully returned properties matching the MLS ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyListResponse'
        '400':
          description: Bad request due to invalid MLS ID
        '401':
          description: Unauthorized due to missing or invalid API key
        '429':
          description: Rate limit exceeded
  /properties/v2/list-similar-homes:
    get:
      operationId: listSimilarHomes
      summary: List similar homes for sale
      description: Returns properties similar to a specified property that are currently listed for sale. Useful for providing comparable listings and helping users discover alternative options in the same area and price range.
      tags:
      - Properties
      parameters:
      - $ref: '#/components/parameters/propertyId'
      responses:
        '200':
          description: Successfully returned similar properties
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyListResponse'
        '400':
          description: Bad request due to invalid property ID
        '401':
          description: Unauthorized due to missing or invalid API key
        '429':
          description: Rate limit exceeded
  /properties/v2/list-similar-rental-homes:
    get:
      operationId: listSimilarRentalHomes
      summary: List similar rental homes
      description: Returns rental properties similar to a specified property. Helps renters discover alternative rental options in the same area with comparable features and pricing.
      tags:
      - Properties
      parameters:
      - $ref: '#/components/parameters/propertyId'
      responses:
        '200':
          description: Successfully returned similar rental properties
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyListResponse'
        '400':
          description: Bad request due to invalid property ID
        '401':
          description: Unauthorized due to missing or invalid API key
        '429':
          description: Rate limit exceeded
components:
  schemas:
    PropertyDescription:
      type: object
      description: Detailed property description and features.
      properties:
        beds:
          type: integer
          description: Number of bedrooms.
        baths:
          type: integer
          description: Total number of bathrooms.
        baths_full:
          type: integer
          description: Number of full bathrooms.
        baths_half:
          type: integer
          description: Number of half bathrooms.
        sqft:
          type: integer
          description: Interior living area in square feet.
        lot_sqft:
          type: integer
          description: Lot area in square feet.
        type:
          type: string
          description: Property type such as single_family, condo, or townhome.
        year_built:
          type: integer
          description: Year the property was built.
        garage:
          type: integer
          description: Number of garage spaces.
        stories:
          type: integer
          description: Number of stories in the property.
        text:
          type: string
          description: Free-text description of the property from the listing.
    PriceHistoryEntry:
      type: object
      description: A single entry in the property price history.
      properties:
        date:
          type: string
          format: date
          description: Date of the price event.
        price:
          type: number
          description: Price in dollars at the time of the event.
        event:
          type: string
          description: Type of price event such as listed, sold, or price_changed.
        source:
          type: string
          description: Data source for the price record.
    NearbySchool:
      type: object
      description: Information about a school near the property.
      properties:
        name:
          type: string
          description: Name of the school.
        education_levels:
          type: array
          description: Grade levels served such as elementary, middle, or high.
          items:
            type: string
        rating:
          type: integer
          description: School rating on a scale of 1 to 10.
          minimum: 1
          maximum: 10
        distance_in_miles:
          type: number
          description: Distance from the property in miles.
        funding_type:
          type: string
          description: Funding type such as public or private.
    TaxHistoryEntry:
      type: object
      description: A single entry in the property tax assessment history.
      properties:
        year:
          type: integer
          description: Tax assessment year.
        tax:
          type: number
          description: Annual property tax amount in dollars.
        assessment:
          type: object
          description: Property tax assessment details.
          properties:
            total:
              type: number
              description: Total assessed value in dollars.
            land:
              type: number
              description: Assessed land value in dollars.
            building:
              type: number
              description: Assessed building value in dollars.
    PropertyListResponse:
      type: object
      description: Response containing a list of property results with pagination metadata.
      properties:
        status:
          type: integer
          description: HTTP status code of the response.
        data:
          type: object
          description: Container for property listing results.
          properties:
            home_search:
              type: object
              description: Search results container.
              properties:
                count:
                  type: integer
                  description: Total number of matching properties.
                total:
                  type: integer
                  description: Total results available.
                results:
                  type: array
                  description: Array of property summary objects.
                  items:
                    $ref: '#/components/schemas/PropertySummary'
    Location:
      type: object
      description: Geographic location information for a property.
      properties:
        address:
          type: object
          description: Structured address information.
          properties:
            line:
              type: string
              description: Street address line.
            city:
              type: string
              description: City name.
            state_code:
              type: string
              description: Two-letter state abbreviation.
            state:
              type: string
              description: Full state name.
            postal_code:
              type: string
              description: Five-digit zip code.
            county:
              type: string
              description: County name.
            coordinate:
              type: object
              description: Geographic coordinates.
              properties:
                lat:
                  type: number
                  description: Latitude.
                lon:
                  type: number
                  description: Longitude.
        neighborhood_name:
          type: string
          description: Name of the neighborhood.
    PropertyDetailResponse:
      type: object
      description: Response containing comprehensive details about a specific property.
      properties:
        status:
          type: integer
          description: HTTP status code of the response.
        data:
          type: object
          description: Container for property detail data.
          properties:
            property_detail:
              type: object
              description: Full property detail object.
              properties:
                property_id:
                  type: string
                  description: Unique identifier for the property.
                listing_id:
                  type: string
                  description: Unique identifier for the listing.
                status:
                  type: string
                  description: Current listing status.
                list_price:
                  type: number
                  description: Current listing price in dollars.
                list_date:
                  type: string
                  format: date-time
                  description: Date the property was listed.
                description:
                  $ref: '#/components/schemas/PropertyDescription'
                location:
                  $ref: '#/components/schemas/Location'
                photos:
                  type: array
                  description: Array of property photo objects.
                  items:
                    type: object
                    properties:
                      href:
                        type: string
                        format: uri
                        description: URL of the property photo.
                      description:
                        type: string
                        description: Caption or description of the photo.
                price_history:
                  type: array
                  description: Historical price changes for the property.
                  items:
                    $ref: '#/components/schemas/PriceHistoryEntry'
                tax_history:
                  type: array
                  description: Property tax assessment history.
                  items:
                    $ref: '#/components/schemas/TaxHistoryEntry'
                schools:
                  type: array
                  description: Nearby schools with ratings and distance.
                  items:
                    $ref: '#/components/schemas/NearbySchool'
                mls:
                  type: object
                  description: MLS listing information.
                  properties:
                    id:
                      type: string
                      description: MLS listing identifier.
                    name:
                      type: string
                      description: MLS name.
                    abbreviation:
                      type: string
                      description: MLS abbreviation.
    PropertySummary:
      type: object
      description: Summary information about a property listing.
      properties:
        property_id:
          type: string
          description: Unique identifier for the property.
        listing_id:
          type: string
          description: Unique identifier for the listing.
        status:
          type: string
          description: Current listing status such as for_sale, for_rent, or sold.
        list_price:
          type: number
          description: Current listing price in dollars.
        list_date:
          type: string
          format: date-time
          description: Date the property was listed.
        last_sold_price:
          type: number
          description: Price at which the property last sold.
        last_sold_date:
          type: string
          format: date
          description: Date the property last sold.
        description:
          type: object
          description: Property description details.
          properties:
            beds:
              type: integer
              description: Number of bedrooms.
            baths:
              type: integer
              description: Number of bathrooms.
            sqft:
              type: integer
              description: Interior square footage.
            lot_sqft:
              type: integer
              description: Lot size in square feet.
            type:
              type: string
              description: Property type such as single_family, condo, or townhome.
            year_built:
              type: integer
              description: Year the property was constructed.
            garage:
              type: integer
              description: Number of garage spaces.
            stories:
              type: integer
              description: Number of stories.
        location:
          $ref: '#/components/schemas/Location'
        photos:
          type: array
          description: Array of property photo URLs.
          items:
            type: object
            properties:
              href:
                type: string
                format: uri
                description: URL of the property photo.
        tags:
          type: array
          description: Tags describing property features.
          items:
            type: string
    PropertyListRequest:
      type: object
      description: Request body for searching and filtering property listings.
      properties:
        status:
          type: array
          description: Listing status filter. Common values include for_sale, for_rent, recently_sold, and ready_to_build.
          items:
            type: string
            enum:
            - for_sale
            - for_rent
            - recently_sold
            - ready_to_build
        postal_code:
          type: string
          description: Five-digit postal code to search within.
        city:
          type: string
          description: City name to search within.
        state_code:
          type: string
          description: Two-letter state code to search within.
        limit:
          type: integer
          description: Maximum number of results to return per page.
          default: 20
          maximum: 200
        offset:
          type: integer
          description: Number of results to skip for pagination.
          default: 0
        sort:
          type: object
          description: Sorting configuration for results.
          properties:
            direction:
              type: string
              description: Sort direction.
              enum:
              - asc
              - desc
            field:
              type: string
              description: Field to sort by such as list_date, list_price, or sqft.
        price_min:
          type: integer
          description: Minimum listing price filter in dollars.
        price_max:
          type: integer
          description: Maximum listing price filter in dollars.
        beds_min:
          type: integer
          description: Minimum number of bedrooms filter.
        beds_max:
          type: integer
          description: Maximum number of bedrooms filter.
        baths_min:
          type: integer
          description: Minimum number of bathrooms filter.
        baths_max:
          type: integer
          description: Maximum number of bathrooms filter.
        sqft_min:
          type: integer
          description: Minimum square footage filter.
        sqft_max:
          type: integer
          description: Maximum square footage filter.
        lot_sqft_min:
          type: integer
          description: Minimum lot size in square feet filter.
        lot_sqft_max:
          type: integer
          description: Maximum lot size in square feet filter.
        prop_type:
          type: array
          description: Property type filter.
          items:
            type: string
            enum:
            - single_family
            - multi_family
            - condo
            - townhome
            - mobile
            - land
            - farm
        age_min:
          type: integer
          description: Minimum year built filter.
        age_max:
          type: integer
          description: Maximum year built filter.
  parameters:
    propertyId:
      name: property_id
      in: query
      required: true
      description: Unique property identifier returned from search or list endpoints.
      schema:
        type: string
  securitySchemes:
    rapidApiKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
      description: API key provided by RapidAPI for authenticating requests.
externalDocs:
  description: Realtor.com Property Data API Documentation
  url: https://rapidapi.com/apidojo/api/realty-in-us