---
title: "Fetch real estate listings"
method: POST
path: "/v1/real-estate/listings"
tags: ["Market intelligence"]
---

# Fetch real estate listings

`POST /v1/real-estate/listings`

Fetches real estate listings by location and optional filters such as listing status, price ranges, home types, and property features. Data is available for all 50 US states, D.C., Puerto Rico, and all 13 Canadian provinces and territories.

<span>⚡ <strong>Rate limit:</strong> 300 requests per 1 minute</span>

<span>💰 <strong>Cost:</strong> 2 credits per page of results&nbsp;<span title="Pricing shown is default pricing. Actual pricing may vary.">ⓘ</span></span>

<span>⏱ <strong>Recommended timeout:</strong> 30 seconds&nbsp;<span title="Recommended timeout: set your HTTP client timeout to at least 30 seconds for this endpoint.">ⓘ</span></span>

## Request body

- object
  - `apiKey` string, required — Your Fiber API key
  - `location` union, required — Location input for listing search. Use `raw` for user-provided text and `structured` for exact city/state precision.
    - object
      - `type` 'raw', required
      - `rawQuery` string, required — Free-form location text. Accepts city, city + state/province, ZIP/postal code, or full address (e.g., 'Toronto, ON', 'Brooklyn NY', '10001', 'Trois-Rivières, QC'). Resolved via geocoding to a city + state/province before searching.
    - object
      - `type` 'structured', required
      - `city` string, required — City name (e.g., 'Toronto', 'Trois-Rivières').
      - `stateCode` string, required — Two-letter US state code or Canadian province code (e.g., 'NY', 'CA', 'QC', 'ON').
  - `nextPageToken` string, nullable — Pagination token from a previous response. Omit for the first page.
  - `sortBy` 'relevance' | 'newest' | 'priceAscending' | 'priceDescending' | 'paymentAscending' | 'paymentDescending' | 'bedroomCountDescending' | 'bathroomCountDescending' | 'floorAreaSqFtDescending' | 'lotAreaSqFtDescending' | 'estimatedPriceDescending' | 'estimatedPriceAscending' | 'null', nullable — Sort order for search results.
  - `listingStatus` 'forSale' | 'forRent' | 'sold' | 'null', nullable — Listing category to search.
  - `homeTypes` string[], nullable — Property types to include.
  - `price` object, nullable — Price range filter for sale and sold listings. Values must use the local market currency for the location (for example, CAD for Canada and USD for the United States).
    - `min` number, nullable
    - `max` number, nullable
  - `rent` object, nullable — Monthly rent range filter for rental listings. Values must use the local market currency for the location (for example, CAD for Canada and USD for the United States).
    - `min` number, nullable
    - `max` number, nullable
  - `bedrooms` object, nullable — Bedroom count filter. Use `min` to set the lower bound.
    - `min` integer, required
  - `bathrooms` object, nullable — Bathroom count filter. Use `min` to set the lower bound.
    - `min` number, required
  - `floorAreaSqFt` object, nullable — Interior living-area range in square feet.
    - `min` number, nullable
    - `max` number, nullable
  - `lotAreaSqFt` object, nullable — Lot-size range in square feet.
    - `min` number, nullable
    - `max` number, nullable
  - `yearBuilt` object, nullable — Year-built range.
    - `min` integer, nullable
    - `max` integer, nullable
  - `parkingSpots` object, nullable — Parking spots filter.
    - `min` integer, required — Minimum number of parking spots.
  - `keywords` string, nullable — Additional keyword terms to match in listing text. For broader matching, separate terms with commas (for example: 'pool,garage').
  - `features` object, nullable — Optional property feature filters.
    - `hasPool` boolean, nullable
    - `hasGarage` boolean, nullable
    - `hasAirConditioning` boolean, nullable
    - `isWaterfront` boolean, nullable
    - `isSingleStory` boolean, nullable
    - `hasOpenHouse` boolean, nullable
    - `includeUnderContract` boolean, nullable

## Response `200`

Default Response

- object
  - `output` object, required
    - `runId` string, required — Unique identifier for this search request.
    - `totalResultCount` integer, nullable — Total number of matching listings.
    - `regionName` string, nullable — Region name interpreted for this search query.
    - `nextPageToken` string, nullable — Token for retrieving the next page. Pass this exact value as `nextPageToken` in the next request. Null if no more pages.
    - `properties` object[], required — Properties returned for this page.
      - `price` object, nullable — Price represented in both USD and local listing currency.
        - `usd` object, required — Listing price converted to USD when conversion data is available.
          - `currency` string, nullable — ISO 4217 currency code for the listing price.
          - `amount` number, nullable — Numeric listing price amount.
        - `local` object, required — Listing price in the local market currency.
          - `currency` string, nullable — ISO 4217 currency code for the listing price.
          - `amount` number, nullable — Numeric listing price amount.
      - `position` integer, nullable — Result position on this page.
      - `listingId` string, required — Unique listing identifier.
      - `address` string, nullable — Full property address.
      - `street` string, nullable — Street address.
      - `city` string, nullable — City name.
      - `state` string, nullable — State or province code.
      - `postalCode` string, nullable — Postal or ZIP code.
      - `unitNumber` string, nullable — Unit or apartment number, when the listing is part of a multi-unit building.
      - `bedroomCount` integer, nullable — Number of bedrooms.
      - `bathroomCount` number, nullable — Number of bathrooms.
      - `estimatedPrice` object, nullable — Estimated property value in USD and local currency.
        - `usd` object, required — Listing price converted to USD when conversion data is available.
          - `currency` string, nullable — ISO 4217 currency code for the listing price.
          - `amount` number, nullable — Numeric listing price amount.
        - `local` object, required — Listing price in the local market currency.
          - `currency` string, nullable — ISO 4217 currency code for the listing price.
          - `amount` number, nullable — Numeric listing price amount.
      - `estimatedMonthlyRent` object, nullable — Estimated monthly rent in USD and local currency.
        - `usd` object, required — Listing price converted to USD when conversion data is available.
          - `currency` string, nullable — ISO 4217 currency code for the listing price.
          - `amount` number, nullable — Numeric listing price amount.
        - `local` object, required — Listing price in the local market currency.
          - `currency` string, nullable — ISO 4217 currency code for the listing price.
          - `amount` number, nullable — Numeric listing price amount.
      - `priceChangeAmount` object, nullable — Latest absolute price change in USD and local currency.
        - `usd` object, required — Listing price converted to USD when conversion data is available.
          - `currency` string, nullable — ISO 4217 currency code for the listing price.
          - `amount` number, nullable — Numeric listing price amount.
        - `local` object, required — Listing price in the local market currency.
          - `currency` string, nullable — ISO 4217 currency code for the listing price.
          - `amount` number, nullable — Numeric listing price amount.
      - `priceReductionNote` string, nullable — Formatted price-reduction note.
      - `taxAssessedValue` object, nullable — Tax-assessed property value in USD and local currency.
        - `usd` object, required — Listing price converted to USD when conversion data is available.
          - `currency` string, nullable — ISO 4217 currency code for the listing price.
          - `amount` number, nullable — Numeric listing price amount.
        - `local` object, required — Listing price in the local market currency.
          - `currency` string, nullable — ISO 4217 currency code for the listing price.
          - `amount` number, nullable — Numeric listing price amount.
      - `floorAreaSqFt` integer, nullable — Living area in square feet.
      - `lotAreaSqFt` number, nullable — Lot size in square feet.
      - `homeType` string, nullable — Property type label.
      - `listingLifecycleStatus` string, nullable — Listing lifecycle status.
      - `listingStatusLabel` string, nullable — Human-readable listing status label.
      - `listingType` string, nullable — Listing type.
      - `dateSold` string, nullable — Sold date.
      - `datePriceChanged` string, nullable — Latest price-change date.
      - `newConstructionType` string, nullable — New-construction type.
      - `timeOnMarketDays` integer, nullable — Number of days this listing has been on market.
      - `url` string, nullable — Listing URL.
      - `thumbnailUrl` string, nullable — Listing thumbnail URL.
      - `imageUrls` string[], nullable — Listing image URLs.
      - `streetViewUrl` string, nullable — Street-view URL.
      - `has3dModel` boolean, nullable — Whether a 3D model is available.
      - `brokerName` string, nullable — Listing broker name.
      - `builderName` string, nullable — Builder name.
      - `isShowcaseListing` boolean, nullable — Whether the listing is marked as showcase.
      - `isFeaturedListing` boolean, nullable — Whether the listing is marked as featured.
      - `primaryTag` object, nullable — Primary listing tag.
        - `type` string, nullable
        - `text` string, nullable
      - `listingTags` object[], nullable — Additional listing tags.
        - `type` string, nullable
        - `text` string, nullable
      - `contactPhone` string, nullable — Listing contact phone number.
      - `openHouse` object, nullable — Open-house details.
        - `description` string, nullable
        - `startDate` string, nullable
        - `endDate` string, nullable
      - `buildingName` string, nullable — Building name.
      - `rentalUnits` object[], nullable — Individual rental units available in a multi-unit building.
        - `price` object, nullable — Unit asking price in USD and local currency.
          - `usd` object, required — Listing price converted to USD when conversion data is available.
            - `currency` string, nullable — ISO 4217 currency code for the listing price.
            - `amount` number, nullable — Numeric listing price amount.
          - `local` object, required — Listing price in the local market currency.
            - `currency` string, nullable — ISO 4217 currency code for the listing price.
            - `amount` number, nullable — Numeric listing price amount.
        - `bedroomCount` integer, nullable — Number of bedrooms in the unit. 0 indicates a studio.
        - `isRoomForRent` boolean, nullable — Whether the unit is a single room for rent.
      - `availabilityCount` integer, nullable — Count of available units.
      - `baseRent` object, nullable — Base-rent range in USD and local currency.
        - `min` object, nullable — Minimum base rent in USD and local currency.
          - `usd` object, required — Listing price converted to USD when conversion data is available.
            - `currency` string, nullable — ISO 4217 currency code for the listing price.
            - `amount` number, nullable — Numeric listing price amount.
          - `local` object, required — Listing price in the local market currency.
            - `currency` string, nullable — ISO 4217 currency code for the listing price.
            - `amount` number, nullable — Numeric listing price amount.
        - `max` object, nullable — Maximum base rent in USD and local currency.
          - `usd` object, required — Listing price converted to USD when conversion data is available.
            - `currency` string, nullable — ISO 4217 currency code for the listing price.
            - `amount` number, nullable — Numeric listing price amount.
          - `local` object, required — Listing price in the local market currency.
            - `currency` string, nullable — ISO 4217 currency code for the listing price.
            - `amount` number, nullable — Numeric listing price amount.
      - `availabilityDate` string, nullable — Availability date.
      - `isInstantTourEnabled` boolean, nullable — Whether instant tour is enabled.
      - `factsAndFeatures` object, nullable — Additional facts and features.
      - `countryCode` string, nullable — ISO 3166-1 alpha-3 country code (for example: 'CAN').
      - `latitude` number, nullable — Latitude coordinate.
      - `longitude` number, nullable — Longitude coordinate.
    - `warnings` string[], nullable — Non-fatal advisories about how this page was served. For example, 'Sort \'priceAscending\' is applied from page 2 onwards.' when the requested sort cannot be honored on page 1. Omitted or null when there's nothing to flag.
  - `chargeInfo` union, required
    - object — Credits were charged immediately for this operation
      - `method` 'charged-now', required
      - `creditsCharged` number, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits will be charged after the operation completes
      - `method` 'charging-later', required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits that were charged for an asynchronous operation
      - `method` 'charged-for-async-process', required
      - `creditsCharged` number, required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — No credits were charged for this operation
      - `method` 'free', required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits were refunded for this operation
      - `method` 'credits-refunded', required
      - `creditsRefunded` number, required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
  - `warnings` object[], nullable — Warnings about extraneous fields in request
    - `field` string, required — Full path to extraneous field (e.g., 'searchParams.ExtraField')
    - `message` string, required — Warning message
  - `advice` string[], nullable — Tips, recommendations, and suggestions for using this API effectively.

## Other responses

- `400` — Default Response
- `401` — Default Response
- `402` — Default Response
- `403` — Default Response
- `404` — Default Response
- `422` — Default Response
- `429` — Default Response
- `500` — Default Response
- `503` — Default Response

---

[API](https://skmtc.net/fiber/apis/fiber-ai-api.md) · [All operations](https://skmtc.net/fiber/apis/fiber-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fiber/fiber-ai-api/versions/0c537984b99f/schema)