--- title: "Fetch Occupancy Metrics for a Market." method: POST path: "/market/{marketId}/metrics/occupancy" tags: ["market_data"] --- # Fetch Occupancy Metrics for a Market. `POST /market/{marketId}/metrics/occupancy` This endpoint provides **12 to 60 months** of historical monthly **occupancy** data for a Market. * Each month shows the following metrics: * The month. * The average occupancy rate of Listings in that month. * The number of unique active Listings that were not booked in that month. * The number of booked Listings in that month. * The number of days available in that month. * The number of days booked in that month. * Supports some [**Listing Filters**](/#tag/listing_filters) to calculate historical occupancy for certain types of STR Listings within the Market. * Supports requests to calculate custom **percentiles** for occupancy rates within the Market. ## Path parameters - `marketId` string, required — AirDNA ID for the Market. This can often be found as `market_id`. ## Request body - MarketMetricsBaseRequestPercentilesSchema — Schema representing the base request for retrieving metrics for a Market or Submarket. - `num_months` integer, required — The number of months to request metrics for. - `filters` union[] — Array of filters that can be used to refine your search results. - union - union - object — Filter the `field` by numerical data. Used for numeric comparison operations. - `field` 'accommodates', required — Field to filter on (i.e. "accommodates"). - `type` 'gt' | 'gte' | 'lt' | 'lte', required — Numeric Equality Filter type | enum | operator | description | | ---- | ------ | ----------- | | `"gt"` | `>` | Greater Than | | `"gte"` | `>=` | Greater Than or Equal | | `"lt"` | `<` | Less Than | | `"lte"` | `<=` | Less Than or Equal | - `value` number, required — Filter value. Must be a single `number`. - object — Filter the `field` by numeric data. Used for `==` operations. - `field` 'accommodates', required — Field to filter on (i.e. "accommodates"). - `type` 'select', required — Filter type (i.e. "select"). - `value` number, required — Filter value. Must be a `number`. - object — Filter the `field` by a numeric minimum and maximum range. - `field` 'accommodates', required — Field to filter on (i.e. "accommodates"). - `type` 'range', required — Filter type (i.e. "range"). - `value` number[], required — An `array` of two `number` values representing the minimum and maximum. * e.g. `[minimum, maximum]`. - union - object — Filter the `field` by numerical data. Used for numeric comparison operations. - `field` 'bathrooms', required — Field to filter on (i.e. "bathrooms"). - `type` 'gt' | 'gte' | 'lt' | 'lte', required — Numeric Equality Filter type | enum | operator | description | | ---- | ------ | ----------- | | `"gt"` | `>` | Greater Than | | `"gte"` | `>=` | Greater Than or Equal | | `"lt"` | `<` | Less Than | | `"lte"` | `<=` | Less Than or Equal | - `value` number, required — Filter value. Must be a single `number`. - object — Filter the `field` by numeric data. Used for `==` operations. - `field` 'bathrooms', required — Field to filter on (i.e. "bathrooms"). - `type` 'select', required — Filter type (i.e. "select"). - `value` number, required — Filter value. Must be a `number`. - object — Filter the `field` by a numeric minimum and maximum range. - `field` 'bathrooms', required — Field to filter on (i.e. "bathrooms"). - `type` 'range', required — Filter type (i.e. "range"). - `value` number[], required — An `array` of two `number` values representing the minimum and maximum. * e.g. `[minimum, maximum]`. - union - object — Filter the `field` by numerical data. Used for numeric comparison operations. - `field` 'bedrooms', required — Field to filter on (i.e. "bedrooms"). - `type` 'gt' | 'gte' | 'lt' | 'lte', required — Numeric Equality Filter type | enum | operator | description | | ---- | ------ | ----------- | | `"gt"` | `>` | Greater Than | | `"gte"` | `>=` | Greater Than or Equal | | `"lt"` | `<` | Less Than | | `"lte"` | `<=` | Less Than or Equal | - `value` number, required — Filter value. Must be a single `number`. - object — Filter the `field` by numeric data. Used for `==` operations. - `field` 'bedrooms', required — Field to filter on (i.e. "bedrooms"). - `type` 'select', required — Filter type (i.e. "select"). - `value` number, required — Filter value. Must be a `number`. - object — Filter the `field` by a numeric minimum and maximum range. - `field` 'bedrooms', required — Field to filter on (i.e. "bedrooms"). - `type` 'range', required — Filter type (i.e. "range"). - `value` number[], required — An `array` of two `number` values representing the minimum and maximum. * e.g. `[minimum, maximum]`. - union - object — Listing is hosted on **at least one** of the selected channels (set overlap). The Listing may also be present on channels you did not select. - `field` 'channels', required — Field to filter on (i.e. "channels"). - `type` 'jsonb_array', required — Filter type for the overlap matching mode. - `value` ChannelOption[], required — Non-empty array of channels to match. A Listing matches if it is on at least one of these. - object — Listing's channel set is a **non-empty subset** of the selected channels — it is on at least one selected channel and on none of the unselected ones. - `field` 'channels', required — Field to filter on (i.e. "channels"). - `type` 'jsonb_array_subset', required — Filter type for the non-empty-subset matching mode. - `value` ChannelOption[], required — Non-empty array of channels. A Listing matches if its channel set is a non-empty subset of this list. - object — Listing is hosted on **exactly** the selected channels — no more, no fewer (set-equality). - `field` 'channels', required — Field to filter on (i.e. "channels"). - `type` 'jsonb_array_exact', required — Filter type for the exact set-equality matching mode. - `value` ChannelOption[], required — Non-empty array of channels. A Listing matches if its channel set equals this list exactly. - union - object — Filter the `field` to a specific single value. Used for `==` operations. - `field` 'listing_type', required — Field to filter on (i.e. "listing_type"). - `type` 'select', required — Filter type (i.e. "select"). - `value` 'entire_place' | 'private_room' | 'shared_room', required — The room type of the Listing. - object — Filter the `field` by multiple values. Each option in the `value` array will be treated like an "IN/OR" operation. - `field` 'listing_type', required — Field to filter on (i.e. "listing_type"). - `type` 'multi_select', required — Filter type (i.e. "multi_select"). - `value` ListingType[], required — Filter value. Must be an array of values. - union - object — Filter the `field` by numerical data. Used for numeric comparison operations. - `field` 'percent_active', required — Field to filter on (i.e. "percent_active") - `type` 'gt' | 'gte' | 'lt' | 'lte', required — Numeric Equality Filter type | enum | operator | description | | ---- | ------ | ----------- | | `"gt"` | `>` | Greater Than | | `"gte"` | `>=` | Greater Than or Equal | | `"lt"` | `<` | Less Than | | `"lte"` | `<=` | Less Than or Equal | - `value` number, required — Filter value. Must be a single `number`. - object — Filter the `field` by numeric data. Used for `==` operations. - `field` 'percent_active', required — Field to filter on (i.e. "percent_active") - `type` 'select', required — Filter type (i.e. "select"). - `value` number, required — Filter value. Must be a `number`. - object — Filter the `field` by a numeric minimum and maximum range. - `field` 'percent_active', required — Field to filter on (i.e. "percent_active") - `type` 'range', required — Filter type (i.e. "range"). - `value` number[], required — An `array` of two `number` values representing the minimum and maximum. * e.g. `[minimum, maximum]`. - union - object — Filter the `field` to a specific single value. Used for `==` operations. - `field` 'price_tier', required — Field to filter on (i.e. "price_tier"). - `type` 'select', required — Filter type (i.e. "select"). - `value` 'budget' | 'economy' | 'midscale' | 'upscale' | 'luxury', required — The price category of the Listing. - object — Filter the `field` by multiple values. Each option in the `value` array will be treated like an "IN/OR" operation. - `field` 'price_tier', required — Field to filter on (i.e. "price_tier"). - `type` 'multi_select', required — Filter type (i.e. "multi_select"). - `value` PriceTier[], required — Filter value. Must be an array of values. - object — Filter the `field` by a boolean value. - `field` 'professionally_managed', required — Field to filter on (i.e. "professionally_managed"). - `type` 'select', required — Filter type (i.e. "select"). - `value` boolean, required — Filter value. Must be `true` or `false`. - union - object — Filter the `field` by numerical data. Used for numeric comparison operations. - `field` 'ratings', required — Field to filter on (i.e. "ratings"). - `type` 'gt' | 'gte' | 'lt' | 'lte', required — Numeric Equality Filter type | enum | operator | description | | ---- | ------ | ----------- | | `"gt"` | `>` | Greater Than | | `"gte"` | `>=` | Greater Than or Equal | | `"lt"` | `<` | Less Than | | `"lte"` | `<=` | Less Than or Equal | - `value` number, required — Filter value. Must be a single `number`. - object — Filter the `field` by numeric data. Used for `==` operations. - `field` 'ratings', required — Field to filter on (i.e. "ratings"). - `type` 'select', required — Filter type (i.e. "select"). - `value` number, required — Filter value. Must be a `number`. - object — Filter the `field` by a numeric minimum and maximum range. - `field` 'ratings', required — Field to filter on (i.e. "ratings"). - `type` 'range', required — Filter type (i.e. "range"). - `value` number[], required — An `array` of two `number` values representing the minimum and maximum. * e.g. `[minimum, maximum]`. - union - object — Filter the `field` to a specific single value. Used for `==` operations. - `field` 'real_estate_type', required — Field to filter on (i.e. "real_estate_type"). - `type` 'select', required — Filter type (i.e. "select"). - `value` 'apartment' | 'bed_and_breakfast' | 'house' | 'unique', required — The real estate type of the Listing. - object — Filter the `field` by multiple values. Each option in the `value` array will be treated like an "IN/OR" operation. - `field` 'real_estate_type', required — Field to filter on (i.e. "real_estate_type"). - `type` 'multi_select', required — Filter type (i.e. "multi_select"). - `value` RealEstateType[], required — Filter value. Must be an array of values. - `percentiles` number[] — An optional array of percentiles to request data for. Each percentile must be in decimal form (i.e. 0.25 for 25th percentile) and between 0 and 1. ## Response `200` Successful Market Occupancy Metrics Response. - object - `payload` MarketOccupancyMetricsResponseSchema, required - `metrics` object[], required - `date` string, date, required — Date string representing the month in the `YYYY-MM` format. - `occupancy_rate` number, required — The occupancy rate represented as a percentage. - `available_listings` integer, required — The number of unique active Listings that were not booked this month. - `booked_listings` integer, required — The number of unique active Listings that had a booking this month. - `days_available` integer, required — The total number of days available across all available Listings this month. - `days_booked` integer, required — The total number of days booked across all the booked Listings this month. - `occupancy_rate_percentiles` number[] — A list of occupancy rates for Listings in the Market/Submarket for each percentile in the order they were requested. - `monthly_pct_change` number, nullable, required — The most recent month-to-month percentage change in `occupancy_rate`. - `yearly_pct_change` number, nullable, required — The most recent year-over-year percentage change in `occupancy_rate`. - `status` Status, required — The Status object on the response envelope - `type` 'success' | 'error', required — The type of response provided by the server. - `response_id` string, required — A unique response code that can be used as a reference for support requests. - `message` string, required — A human-readable message that can provide more detail about the status of the request. ## Other responses - `400` — The request was invalid. - `404` — Failed to find data matching your request. - `500` — An internal server error occurred. --- [API](https://skmtc.net/airdna/apis/airdna-enterprise-api.md) · [All operations](https://skmtc.net/airdna/apis/airdna-enterprise-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/airdna/airdna-enterprise-api/revisions/aeed3678926f/schema)