> ## Documentation Index
> Fetch the complete documentation index at: https://developers.apartmentiq.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Bulk Market Forecasts
> Retrieve bulk market forecast rows for geographic boundaries using optional geography filters, requested forecast fields, and pagination.
Requires Explore Pro access.
`property_filters` and `filters` are not supported.
## OpenAPI
````yaml /openapi/v2/schema.json post /markets/bulk_forecasts
openapi: 3.1.0
info:
title: ApartmentIQ API V2
version: 2.0.0
termsOfService: https://www.getapartmentiq.com/terms
x-logo:
url: https://developers.apartmentiq.io/logo.svg
altText: ApartmentIQ
description: >-
ApartmentIQ API V2 endpoints for account discovery, search, and bulk Explore
data.
servers:
- url: https://data.apartmentiq.io/apartmentiq/api/v2
security:
- bearerAuth: []
tags:
- name: Accounts
description: Account discovery endpoints.
- name: Amenities
description: Amenity discovery endpoints.
- name: Properties
description: Property search endpoints.
- name: Markets
description: Market and geo-boundary search endpoints.
- name: Organizations
description: Organization search endpoints.
- name: Bulk
description: Bulk property, market, quota, and forecast exports.
paths:
/markets/bulk_forecasts:
post:
tags:
- Bulk
summary: Bulk Market Forecasts
description: >-
Retrieve bulk market forecast rows for geographic boundaries using
optional geography filters, requested forecast fields, and pagination.
Requires Explore Pro access.
`property_filters` and `filters` are not supported.
operationId: createV2MarketsBulkForecasts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkMarketForecastsRequest'
example:
account_id: '{account_id}'
time_period: next_12_months
interval: quarter
geo_filters:
geo_types:
- MSA
fields:
- rent_growth_yoy
- occupancy
page: 1
per_page: 25
responses:
'200':
description: Bulk market forecast rows and pagination metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkMarketForecastsResponse'
example:
rows:
- name: Madison, WI Metro Area
geo_boundary_id: 4127
geo_type: MSA
msa_name: null
submarket_name: null
period: 2026-Q3
rent_growth_yoy: 0.0211
rent_growth_yoy_downside: 0.0098
rent_growth_yoy_upside: 0.0342
rent_growth_yoy_bed_0: 0.0184
rent_growth_yoy_bed_0_downside: 0.0065
rent_growth_yoy_bed_0_upside: 0.031
rent_growth_yoy_bed_1: 0.0202
rent_growth_yoy_bed_1_downside: 0.0089
rent_growth_yoy_bed_1_upside: 0.0331
rent_growth_yoy_bed_2: 0.0237
rent_growth_yoy_bed_2_downside: 0.0114
rent_growth_yoy_bed_2_upside: 0.0376
rent_growth_yoy_bed_3: 0.0196
rent_growth_yoy_bed_3_downside: 0.0071
rent_growth_yoy_bed_3_upside: 0.0324
rent_growth_yoy_class_a: 0.0252
rent_growth_yoy_class_a_downside: 0.0128
rent_growth_yoy_class_a_upside: 0.0394
rent_growth_yoy_class_b: 0.0201
rent_growth_yoy_class_b_downside: 0.0087
rent_growth_yoy_class_b_upside: 0.0322
rent_growth_yoy_class_c: 0.0157
rent_growth_yoy_class_c_downside: 0.0038
rent_growth_yoy_class_c_upside: 0.0289
occupancy: 0.9433
occupancy_downside: 0.9275
occupancy_upside: 0.9581
absorption: 148
absorption_downside: 96
absorption_upside: 201
deliveries: 132
deliveries_downside: 74
deliveries_upside: 186
- name: Downtown Madison
geo_boundary_id: 90114
geo_type: Submarket
msa_name: Madison, WI Metro Area
submarket_name: null
period: 2026-Q3
rent_growth_yoy: 0.0289
rent_growth_yoy_downside: 0.0142
rent_growth_yoy_upside: 0.0441
rent_growth_yoy_bed_0: 0.0251
rent_growth_yoy_bed_0_downside: 0.0107
rent_growth_yoy_bed_0_upside: 0.0402
rent_growth_yoy_bed_1: 0.0278
rent_growth_yoy_bed_1_downside: 0.0131
rent_growth_yoy_bed_1_upside: 0.0435
rent_growth_yoy_bed_2: 0.0314
rent_growth_yoy_bed_2_downside: 0.0168
rent_growth_yoy_bed_2_upside: 0.0479
rent_growth_yoy_bed_3: null
rent_growth_yoy_bed_3_downside: null
rent_growth_yoy_bed_3_upside: null
rent_growth_yoy_class_a: 0.0335
rent_growth_yoy_class_a_downside: 0.0188
rent_growth_yoy_class_a_upside: 0.0502
rent_growth_yoy_class_b: 0.0246
rent_growth_yoy_class_b_downside: 0.0104
rent_growth_yoy_class_b_upside: 0.0395
rent_growth_yoy_class_c: null
rent_growth_yoy_class_c_downside: null
rent_growth_yoy_class_c_upside: null
occupancy: 0.9504
occupancy_downside: 0.9312
occupancy_upside: 0.9648
absorption: 32
absorption_downside: 18
absorption_upside: 47
deliveries: 24
deliveries_downside: 0
deliveries_upside: 42
pagination:
current_page: 1
total_pages: 4
total_count: 100
per_page: 25
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ExploreAccessForbidden'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
BulkMarketForecastsRequest:
type: object
properties:
account_id:
$ref: '#/components/schemas/AccountId'
time_period:
type: string
enum:
- next_12_months
- next_3_years
- next_5_years
description: Forecast horizon.
interval:
type: string
enum:
- month
- quarter
- year
description: Forecast period bucket.
fields:
type: array
items:
type: string
enum:
- rent_growth_yoy
- rent_growth_yoy_downside
- rent_growth_yoy_upside
- rent_growth_yoy_bed_0
- rent_growth_yoy_bed_0_downside
- rent_growth_yoy_bed_0_upside
- rent_growth_yoy_bed_1
- rent_growth_yoy_bed_1_downside
- rent_growth_yoy_bed_1_upside
- rent_growth_yoy_bed_2
- rent_growth_yoy_bed_2_downside
- rent_growth_yoy_bed_2_upside
- rent_growth_yoy_bed_3
- rent_growth_yoy_bed_3_downside
- rent_growth_yoy_bed_3_upside
- rent_growth_yoy_class_a
- rent_growth_yoy_class_a_downside
- rent_growth_yoy_class_a_upside
- rent_growth_yoy_class_b
- rent_growth_yoy_class_b_downside
- rent_growth_yoy_class_b_upside
- rent_growth_yoy_class_c
- rent_growth_yoy_class_c_downside
- rent_growth_yoy_class_c_upside
- occupancy
- occupancy_downside
- occupancy_upside
- absorption
- absorption_downside
- absorption_upside
- deliveries
- deliveries_downside
- deliveries_upside
uniqueItems: true
description: Forecast metric field names to include in each market row.
geo_filters:
$ref: '#/components/schemas/GeoFilters'
page:
type: integer
minimum: 1
default: 1
description: Page number. Values less than 1 are treated as 1.
per_page:
type: integer
minimum: 1
maximum: 100
default: 25
description: >-
Matched markets per page. Values above 100 are capped at 100.
Interval-based rows expand each matched market into one row per
period, so the number of rows returned can be greater than per_page.
required:
- account_id
- time_period
- interval
additionalProperties: false
BulkMarketForecastsResponse:
type: object
description: Paginated market forecast export results.
properties:
rows:
type: array
items:
type: object
description: >-
Market identity fields plus requested forecast fields for an
output period.
properties:
name:
type: string
description: Display name for the market or geography.
geo_boundary_id:
type: integer
description: ApartmentIQ geo-boundary ID for the market row.
geo_type:
type: string
description: >-
ApartmentIQ geography type, such as MSA, Submarket, Zip, or
Custom.
msa_name:
type:
- string
- 'null'
description: >-
Parent MSA name. Returned for non-MSA market rows when
available.
submarket_name:
type:
- string
- 'null'
description: >-
Parent submarket name. Returned for zip code market rows when
available.
period:
type:
- string
- 'null'
description: >-
Output period for the row. Format is YYYY-MM, YYYY-QN, or
YYYY, depending on the requested interval.
rent_growth_yoy:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate. Returned
when requested; null when forecast data is unavailable.
rent_growth_yoy_downside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate downside
scenario. Returned when requested; null when forecast data is
unavailable.
rent_growth_yoy_upside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate upside
scenario. Returned when requested; null when forecast data is
unavailable.
rent_growth_yoy_bed_0:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for studio
units. Returned when requested; null when forecast data is
unavailable.
rent_growth_yoy_bed_0_downside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for studio
units downside scenario. Returned when requested; null when
forecast data is unavailable.
rent_growth_yoy_bed_0_upside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for studio
units upside scenario. Returned when requested; null when
forecast data is unavailable.
rent_growth_yoy_bed_1:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for
one-bedroom units. Returned when requested; null when forecast
data is unavailable.
rent_growth_yoy_bed_1_downside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for
one-bedroom units downside scenario. Returned when requested;
null when forecast data is unavailable.
rent_growth_yoy_bed_1_upside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for
one-bedroom units upside scenario. Returned when requested;
null when forecast data is unavailable.
rent_growth_yoy_bed_2:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for
two-bedroom units. Returned when requested; null when forecast
data is unavailable.
rent_growth_yoy_bed_2_downside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for
two-bedroom units downside scenario. Returned when requested;
null when forecast data is unavailable.
rent_growth_yoy_bed_2_upside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for
two-bedroom units upside scenario. Returned when requested;
null when forecast data is unavailable.
rent_growth_yoy_bed_3:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for
three-bedroom units. Returned when requested; null when
forecast data is unavailable.
rent_growth_yoy_bed_3_downside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for
three-bedroom units downside scenario. Returned when
requested; null when forecast data is unavailable.
rent_growth_yoy_bed_3_upside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for
three-bedroom units upside scenario. Returned when requested;
null when forecast data is unavailable.
rent_growth_yoy_class_a:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for Class A
properties. Returned when requested; null when forecast data
is unavailable.
rent_growth_yoy_class_a_downside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for Class A
properties downside scenario. Returned when requested; null
when forecast data is unavailable.
rent_growth_yoy_class_a_upside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for Class A
properties upside scenario. Returned when requested; null when
forecast data is unavailable.
rent_growth_yoy_class_b:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for Class B
properties. Returned when requested; null when forecast data
is unavailable.
rent_growth_yoy_class_b_downside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for Class B
properties downside scenario. Returned when requested; null
when forecast data is unavailable.
rent_growth_yoy_class_b_upside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for Class B
properties upside scenario. Returned when requested; null when
forecast data is unavailable.
rent_growth_yoy_class_c:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for Class C
properties. Returned when requested; null when forecast data
is unavailable.
rent_growth_yoy_class_c_downside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for Class C
properties downside scenario. Returned when requested; null
when forecast data is unavailable.
rent_growth_yoy_class_c_upside:
type:
- number
- 'null'
description: >-
Forecasted year-over-year asking rent growth rate for Class C
properties upside scenario. Returned when requested; null when
forecast data is unavailable.
occupancy:
type:
- number
- 'null'
description: >-
Forecasted occupancy percentage. Returned when requested; null
when forecast data is unavailable.
occupancy_downside:
type:
- number
- 'null'
description: >-
Forecasted occupancy percentage downside scenario. Returned
when requested; null when forecast data is unavailable.
occupancy_upside:
type:
- number
- 'null'
description: >-
Forecasted occupancy percentage upside scenario. Returned when
requested; null when forecast data is unavailable.
absorption:
type:
- number
- 'null'
description: >-
Forecasted absorbed unit count. Returned when requested; null
when forecast data is unavailable.
absorption_downside:
type:
- number
- 'null'
description: >-
Forecasted absorbed unit count downside scenario. Returned
when requested; null when forecast data is unavailable.
absorption_upside:
type:
- number
- 'null'
description: >-
Forecasted absorbed unit count upside scenario. Returned when
requested; null when forecast data is unavailable.
deliveries:
type:
- number
- 'null'
description: >-
Forecasted delivered unit count. Returned when requested; null
when forecast data is unavailable.
deliveries_downside:
type:
- number
- 'null'
description: >-
Forecasted delivered unit count downside scenario. Returned
when requested; null when forecast data is unavailable.
deliveries_upside:
type:
- number
- 'null'
description: >-
Forecasted delivered unit count upside scenario. Returned when
requested; null when forecast data is unavailable.
required:
- name
- geo_boundary_id
- geo_type
- period
additionalProperties: false
description: >-
Market forecast rows for the matched markets on the current page.
Each matched market is expanded into one row per interval period, so
the number of rows returned can be greater than the per_page value.
Each row includes market identity fields, an output period, and any
requested forecast fields.
pagination:
$ref: '#/components/schemas/Pagination'
description: >-
Pagination details for matched markets, not the expanded
interval-period rows.
required:
- rows
- pagination
additionalProperties: false
AccountId:
anyOf:
- type: integer
- type: string
description: ApartmentIQ account ID used to set the request account context.
GeoFilters:
type: object
description: >-
Market selection filters. Omit to page through all supported market
boundaries.
properties:
geo_boundary_ids:
type: array
items:
anyOf:
- type: integer
- type: string
description: Specific geo boundary IDs to include.
inside_geo_boundary_ids:
type: array
items:
anyOf:
- type: integer
- type: string
description: Parent geo boundaries whose children should be included.
geo_types:
type: array
items:
type: string
enum:
- Custom
- MSA
- BespokeSubmarket
- CensusPlace
- Neighborhood
- County
- ZipCode
- State
description: >-
Frontend geo types to include. Valid values: `Custom`, `MSA`,
`BespokeSubmarket`, `CensusPlace`, `Neighborhood`, `County`,
`ZipCode`, `State`.
additionalProperties: false
Pagination:
type: object
properties:
current_page:
type: integer
description: Current page number in the result set.
total_pages:
type: integer
description: Total number of pages available for the request.
total_count:
type: integer
description: Total number of matching records across all pages.
per_page:
type: integer
description: Maximum number of records returned per page.
required:
- current_page
- total_pages
- total_count
- per_page
additionalProperties: false
description: Pagination details for list-style responses.
Error:
type: object
description: Error response payload.
properties:
error:
type: string
description: Short error message.
message:
type: string
description: Additional error details, when available.
quota_limit:
type: integer
description: Quota limit that applied to the request, when relevant.
quota_usage:
type: integer
description: Quota already used, when relevant.
required:
- error
additionalProperties: true
responses:
BadRequest:
description: The request was invalid or malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized - Invalid or missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ExploreAccessForbidden:
description: Forbidden - The user lacks account access or Explore Pro access.
RateLimitExceeded:
description: >-
Rate limit exceeded. Inspect the rate limit headers and wait before
retrying.
headers:
X-RateLimit-Limit:
description: The limit that applied to the request.
schema:
type: string
X-RateLimit-Reset-After:
description: The rate limit window length, in seconds.
schema:
type: string
X-RateLimit-Reset:
description: Unix timestamp when the current window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
text/plain:
schema:
type: string
example: |
You have exceeded the rate limit for this API.
InternalServerError:
description: An unexpected error occurred while processing the request.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````