> ## 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.
# Get Market Narrative
> Retrieve a market narrative for a geographic boundary. Returns a structured analysis covering market overview, rent performance, occupancy and demand, construction pipeline, sales transactions, and demographics.
The response contains the most recent narrative available for the given geo boundary. Narratives are updated periodically as new market data becomes available.
Narratives are only available for MSA and Submarket geo boundary types.
The `sales` section is truncated for accounts without Explore Pro+ access.
## OpenAPI
````yaml /openapi/v1/schema.json get /markets/narratives
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:
/markets/narratives:
get:
tags:
- Markets
summary: Get Market Narrative
description: >-
Retrieve a market narrative for a geographic boundary. Returns a
structured analysis covering market overview, rent performance,
occupancy and demand, construction pipeline, sales transactions, and
demographics.
The response contains the most recent narrative available for the given
geo boundary. Narratives are updated periodically as new market data
becomes available.
Narratives are only available for MSA and Submarket geo boundary
types.
The `sales` section is truncated for accounts without Explore Pro+
access.
operationId: getMarketNarrative
parameters:
- name: account_id
in: query
description: ID of the ApartmentIQ account.
required: true
schema:
type: integer
example: 1111
- name: geo_boundary_id
in: query
description: >-
ID of the geographic boundary to retrieve the narrative for. Find
IDs using the [Search Geo
Boundaries](#tag/markets/post/geo_boundaries/search) endpoint.
required: true
schema:
type: integer
example: 94121
responses:
'200':
description: Successfully retrieved market narrative.
content:
application/json:
schema:
$ref: '#/components/schemas/MarketNarrativeResponse'
example:
data:
- id: '42'
type: narrative
attributes:
id: 42
geo_boundary_id: 94121
analysis_date: '2026-03-15'
overview: >-
The Raleigh-Cary metro area continued to demonstrate
strong fundamentals in Q1 2026, with steady rent growth
and healthy absorption across most submarkets.
rent: >-
Average effective rents rose 3.2% year-over-year,
outpacing the national average. Class A properties led
gains at 4.1%, while Class B and C segments posted more
modest increases of 2.8% and 2.1% respectively.
occupancy: >-
Occupancy rates held firm at 94.8%, supported by
continued in-migration and job growth in the technology
and life sciences sectors. Net absorption totaled
approximately 2,400 units during the quarter.
construction: >-
The construction pipeline remains active with over 8,500
units currently under construction. Deliveries are
expected to peak in mid-2026 before tapering through
year-end.
sales: >-
Investment sales volume reached $420M across 12
transactions during the quarter, with cap rates
averaging 5.2% for institutional-quality assets...
demographics: >-
The metro area added approximately 18,000 new residents
over the past year, driven by strong employment growth
in technology, healthcare, and professional services
sectors.
'401':
description: Unauthorized - Invalid or missing authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden - Insufficient permissions or no Explore 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:
MarketNarrativeResponse:
type: object
required:
- data
properties:
data:
type: array
description: >-
Array of market narrative resources. Contains at most one narrative
(the most recent available for the geo boundary), or an empty array
if no narrative exists.
items:
$ref: '#/components/schemas/MarketNarrative'
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.
MarketNarrative:
type: object
description: A market narrative resource in JSON:API format.
required:
- id
- type
- attributes
properties:
id:
type: string
description: The unique identifier of the narrative.
example: '42'
type:
type: string
description: The resource type.
enum:
- narrative
example: narrative
attributes:
type: object
description: The narrative attributes.
properties:
id:
type: integer
description: The numeric ID of the narrative.
example: 42
geo_boundary_id:
type: integer
description: The ID of the geographic boundary this narrative describes.
example: 94121
analysis_date:
type: string
format: date
description: The date of this narrative (ISO 8601 date format).
example: '2026-03-15'
overview:
type: string
nullable: true
description: Executive summary of the market's current conditions and trends.
rent:
type: string
nullable: true
description: >-
Analysis of rent trends, effective rent changes, and performance
by property class.
occupancy:
type: string
nullable: true
description: >-
Analysis of occupancy rates, absorption trends, and demand
drivers.
construction:
type: string
nullable: true
description: >-
Overview of the construction pipeline, deliveries, and planned
developments.
sales:
type: string
nullable: true
description: >-
Summary of investment sales activity, transaction volume, and
cap rate trends. Truncated for accounts without Explore Pro+
access.
demographics:
type: string
nullable: true
description: >-
Overview of population growth, employment trends, and economic
indicators.
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: {}
````