> ## 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.
# Geo Boundary Forecasts
> Retrieve modeled future time-series forecast data for a geographic boundary. Returns aggregated forecast metrics at configurable time intervals.
The forecast window spans from the beginning of the current month up to 5 years in the future. Any date filters outside this window are automatically clamped.
Requires Explore Pro access.
Forecasts are only available for MSAs, Submarkets, and Zip Codes.
Set `use_rent_value` to `true` to transform rent-growth aggregation values into seasonally adjusted forecasted rent values in dollars. The response keeps the aggregation names you provide. Non-rent-growth aggregations are unchanged. If the current base rent is unavailable, rent-growth-derived values are returned as `null`.
## Valid Aggregation Fields
All fields have `_downside` and `_upside` variants for confidence bounds (e.g., `rent_growth_yoy_downside`, `rent_growth_yoy_upside`).
### Rent Growth
| Field | Description |
|---|---|
| `rent_growth_yoy` | Year-over-year rent growth rate |
| `rent_growth_yoy_bed_0` | Rent growth for studios |
| `rent_growth_yoy_bed_1` | Rent growth for 1-bedrooms |
| `rent_growth_yoy_bed_2` | Rent growth for 2-bedrooms |
| `rent_growth_yoy_bed_3` | Rent growth for 3-bedrooms |
| `rent_growth_yoy_class_a` | Rent growth for Class A properties |
| `rent_growth_yoy_class_b` | Rent growth for Class B properties |
| `rent_growth_yoy_class_c` | Rent growth for Class C properties |
### Occupancy, Absorption & Deliveries
| Field | Description |
|---|---|
| `occupancy` | Forecast occupancy rate |
| `absorption` | Forecast net absorption (units) |
| `deliveries` | Forecast new unit deliveries |
## OpenAPI
````yaml /openapi/v1/schema.json post /geo_boundary/{geo_boundary_id}/forecasts
openapi: 3.0.3
info:
title: ApartmentIQ API
version: 1.14.0
termsOfService: https://www.getapartmentiq.com/terms
x-logo:
url: https://developers.apartmentiq.io/logo.svg
altText: ApartmentIQ
description: >-
ApartmentIQ API providing Accounts, Market Surveys, Markets, Market
Narratives, and Forecasts endpoints to access accounts, comp sets, market
survey tables, units, floorplans, and market-based property data. See
documentation pages for authentication, errors, and rate limits.
servers:
- url: https://data.apartmentiq.io/apartmentiq/api/v1
security:
- oauth2: []
tags:
- name: Accounts
description: >-
Endpoints for listing the ApartmentIQ accounts accessible to the
authenticated user.
- name: Market Surveys
description: >-
Market Survey endpoints can be used to access data related to your market
surveys within ApartmentIQ. The ApartmentIQ API refers to the list of
properties within your market surveys as a comp set, or competitive set.
In the rest of this document, comp set and competitive set will be used
interchangeably.
- name: Markets
description: Endpoints used to access market data.
- name: Bulk Data Export
description: >-
Endpoints for requesting and downloading historical property data through
asynchronous batch jobs. Submit a job request, monitor its status, and
download results when ready.
- name: Forecasts
description: >-
Endpoints for retrieving modeled future time-series forecast data for
geographic boundaries and properties. Forecast data spans from the
beginning of the current month up to 5 years in the future. Requires
Explore Pro access.
paths:
/geo_boundary/{geo_boundary_id}/forecasts:
post:
tags:
- Forecasts
summary: Geo Boundary Forecasts
description: >-
Retrieve modeled future time-series forecast data for a geographic
boundary. Returns aggregated forecast metrics at configurable time
intervals.
The forecast window spans from the beginning of the current month up to
5 years in the future. Any date filters outside this window are
automatically clamped.
Requires Explore Pro access.
Forecasts are only available for MSAs, Submarkets, and Zip
Codes.
Set `use_rent_value` to `true` to transform rent-growth aggregation
values into seasonally adjusted forecasted rent values in dollars. The
response keeps the aggregation names you provide. Non-rent-growth
aggregations are unchanged. If the current base rent is unavailable,
rent-growth-derived values are returned as `null`.
## Valid Aggregation Fields
All fields have `_downside` and `_upside` variants for confidence bounds
(e.g., `rent_growth_yoy_downside`, `rent_growth_yoy_upside`).
### Rent Growth
| Field | Description |
|---|---|
| `rent_growth_yoy` | Year-over-year rent growth rate |
| `rent_growth_yoy_bed_0` | Rent growth for studios |
| `rent_growth_yoy_bed_1` | Rent growth for 1-bedrooms |
| `rent_growth_yoy_bed_2` | Rent growth for 2-bedrooms |
| `rent_growth_yoy_bed_3` | Rent growth for 3-bedrooms |
| `rent_growth_yoy_class_a` | Rent growth for Class A properties |
| `rent_growth_yoy_class_b` | Rent growth for Class B properties |
| `rent_growth_yoy_class_c` | Rent growth for Class C properties |
### Occupancy, Absorption & Deliveries
| Field | Description |
|---|---|
| `occupancy` | Forecast occupancy rate |
| `absorption` | Forecast net absorption (units) |
| `deliveries` | Forecast new unit deliveries |
operationId: getGeoBoundaryForecasts
parameters:
- name: geo_boundary_id
in: path
description: >-
ID of the geographic boundary. Find IDs using the [Search Geo
Boundaries](#tag/markets/post/geo_boundaries/search) endpoint.
required: true
schema:
type: integer
example: 94121
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- account_id
- aggregations
properties:
account_id:
type: integer
description: ID of the ApartmentIQ account.
example: 1111
aggregations:
type: array
description: >-
One or more aggregations to compute over the forecast
time-series. Each aggregation defines a metric that appears
in the response `values` object, keyed by the `name` you
provide.
items:
$ref: '#/components/schemas/ForecastAggregation'
interval:
type: string
description: Time bucket size for the forecast data.
enum:
- month
- quarter
- year
default: month
example: month
offset:
type: string
description: Offset for time bucket alignment.
default: 0d
example: 0d
use_rent_value:
type: boolean
description: >-
When `true`, transforms rent-growth aggregation values into
seasonally adjusted forecasted rent values in dollars.
Aggregation keys in the response remain the names you
provide in `aggregations`.
default: false
example: true
filters:
$ref: '#/components/schemas/ForecastFilters'
examples:
Monthly Rent Growth:
value:
account_id: 1111
aggregations:
- name: avg_rent_growth
field: rent_growth_yoy
aggregation_type: avg
interval: month
Seasonally Adjusted Rent Values:
value:
account_id: 1111
aggregations:
- name: forecasted_rent
field: rent_growth_yoy
aggregation_type: avg
- name: avg_occupancy
field: occupancy
aggregation_type: avg
interval: month
use_rent_value: true
Quarterly with Confidence Bounds:
value:
account_id: 1111
aggregations:
- name: rent_growth
field: rent_growth_yoy
aggregation_type: avg
- name: rent_growth_low
field: rent_growth_yoy_downside
aggregation_type: avg
- name: rent_growth_high
field: rent_growth_yoy_upside
aggregation_type: avg
interval: quarter
Multiple Metrics:
value:
account_id: 1111
aggregations:
- name: avg_rent_growth
field: rent_growth_yoy
aggregation_type: avg
- name: avg_occupancy
field: occupancy
aggregation_type: avg
- name: total_absorption
field: absorption
aggregation_type: sum
- name: total_deliveries
field: deliveries
aggregation_type: sum
interval: year
filters:
collected_at_gte: '2026-01-01'
collected_at_lte: '2028-12-31'
responses:
'200':
description: Successfully retrieved forecast time-series data.
content:
application/json:
schema:
$ref: '#/components/schemas/ForecastResponse'
example:
data:
type: forecasts
id: 550e8400-e29b-41d4-a716-446655440000
attributes:
time_series:
- date: '2026-03-01'
values:
avg_rent_growth: 0.0234
- date: '2026-04-01'
values:
avg_rent_growth: 0.0241
- date: '2026-05-01'
values:
avg_rent_growth: 0.0255
'400':
description: Bad Request - Invalid or missing parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Missing Aggregations:
value:
error: aggregations must contain at least one aggregation
Invalid Date:
value:
error: >-
filters[collected_at_gte] must be a valid ISO 8601 date
(e.g. 2026-03-01)
'401':
description: Unauthorized - Invalid or missing authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden - Insufficient permissions or no Explore Pro access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: The geo boundary was not found.
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
description: >-
An unexpected error occurred while processing the request. Our team
is investigating.
components:
schemas:
ForecastAggregation:
type: object
description: >-
Defines a single aggregation to compute over the forecast time-series.
The `name` you provide becomes the key in the response `values` object.
required:
- name
- field
- aggregation_type
properties:
name:
type: string
description: >-
Display name for the aggregation result. This becomes the key in
each time-series entry's `values` object.
example: avg_rent_growth
field:
type: string
description: >-
The data field to aggregate. Valid fields are listed in each
endpoint's **Valid Aggregation Fields** table. Geo boundary fields
include `rent_growth_yoy`, `occupancy`, `absorption`, and
`deliveries`. Property fields include `rent_growth_rate_yoy` and
`occupancy_percent`. All fields also have `_downside` and `_upside`
variants for confidence bounds.
example: rent_growth_yoy
aggregation_type:
type: string
description: >-
The type of aggregation to perform on the field values within each
time bucket.
enum:
- avg
- median
- sum
- max
- min
example: avg
ForecastFilters:
type: object
description: >-
Optional date range filters for forecast data. If omitted, defaults to
the full forecast window (current month through 5 years out). Dates
outside the forecast window are automatically clamped.
properties:
collected_at_gte:
type: string
format: date
description: >-
Start date for forecast data (ISO 8601 date format, e.g.
`2026-03-01`). Automatically clamped to the beginning of the current
month if earlier.
example: '2026-03-01'
collected_at_lte:
type: string
format: date
description: >-
End date for forecast data (ISO 8601 date format, e.g.
`2031-03-01`). Automatically clamped to 5 years from the beginning
of the current month if later.
example: '2031-03-01'
ForecastResponse:
type: object
required:
- data
properties:
data:
type: object
required:
- type
- id
- attributes
properties:
type:
type: string
description: Resource type.
enum:
- forecasts
example: forecasts
id:
type: string
format: uuid
description: Unique identifier for this forecast result.
example: 550e8400-e29b-41d4-a716-446655440000
attributes:
type: object
properties:
time_series:
type: array
description: Array of time-series data points, one per time bucket.
items:
$ref: '#/components/schemas/ForecastTimeSeriesEntry'
Error:
type: object
description: >-
Error response payload. Most errors include error and optional message;
some validation responses include errors; quota responses include quota
fields.
properties:
error:
type: string
description: Short error message
example: Invalid parameter
message:
type: string
description: Optional detailed message
example: account_id is required
errors:
type: array
description: Optional list of validation errors.
items:
type: string
quota_limit:
type: integer
description: >-
Quota limit that applied to the request when an account quota was
exceeded.
quota_usage:
type: integer
description: Current quota usage when an account quota was exceeded.
ForecastTimeSeriesEntry:
type: object
description: A single time bucket in the forecast time-series.
properties:
date:
type: string
format: date
description: Start date of this time bucket (ISO 8601 date format).
example: '2026-03-01'
values:
type: object
description: >-
Aggregation results for this time bucket. Each key corresponds to
the `name` specified in the request's `aggregations` array, and the
value is the computed result. When `use_rent_value` is `true`,
rent-growth aggregation values are seasonally adjusted forecasted
rent values in dollars, while non-rent-growth aggregation values are
unchanged.
additionalProperties:
type: number
nullable: true
description: Aggregated value, rounded to 4 decimal places.
example:
avg_rent_growth: 0.0234
avg_occupancy: 0.9412
responses:
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.
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Trial API quota limit exceeded
quota_limit: 5000
quota_usage: 5001
securitySchemes:
oauth2:
type: oauth2
description: >-
Enter a Bearer token obtained via the OAuth client credentials flow or
from the Access Tokens tab in your account settings.
flows:
clientCredentials:
tokenUrl: https://data.apartmentiq.io/oauth/token
scopes: {}
````