> ## 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.
# Compare Markets
> Retrieve aggregated market-level metrics for geographic areas such as MSAs and Submarkets. This endpoint returns comprehensive market data including rent averages, occupancy rates, inventory counts, population demographics, and sales transaction data. Use market-level filters to narrow results by geography or performance metrics, and property-level filters to control which properties contribute to the aggregations.
Accounts without Explore Pro or Explore Pro+ access receive limited data from this endpoint.
## OpenAPI
````yaml /openapi/v1/schema.json post /explore_markets
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:
/explore_markets:
post:
tags:
- Markets
summary: Compare Markets
description: >-
Retrieve aggregated market-level metrics for geographic areas such as
MSAs and Submarkets. This endpoint returns comprehensive market data
including rent averages, occupancy rates, inventory counts, population
demographics, and sales transaction data. Use market-level filters to
narrow results by geography or performance metrics, and property-level
filters to control which properties contribute to the aggregations.
Accounts without Explore Pro or Explore Pro+ access receive
limited data from this endpoint.
operationId: compareMarkets
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- account_id
properties:
account_id:
type: integer
description: The ID of the account you're requesting data for.
example: 2222
filters:
type: object
description: >-
Market-level filters to narrow results by geography or
market performance metrics.
properties:
geo_boundary_id:
type: array
description: >-
Array of geo boundary IDs to retrieve market data for.
Find these IDs using the [Search Geo
Boundaries](#tag/markets/post/geo_boundaries/search)
endpoint.
items:
type: string
example:
- '94121'
- '94012'
geo_type:
type: string
description: >-
Filter results by geo boundary type. Use in combination
with geo_states to retrieve all markets of a given type.
enum:
- MSA
- BespokeSubmarket
example: MSA
geo_states:
type: array
description: >-
Filter by US state(s). Use two-letter state
abbreviations.
items:
type: string
example:
- CA
- NY
rent_avg_t30_gte:
type: number
description: Minimum 30-day average rent.
example: 2000
rent_avg_t30_lte:
type: number
description: Maximum 30-day average rent.
example: 5000
ner_avg_t30_gte:
type: number
description: Minimum 30-day average net effective rent.
example: 1800
ner_avg_t30_lte:
type: number
description: Maximum 30-day average net effective rent.
example: 4500
rent_growth_rate_yoy_avg_gte:
type: number
description: >-
Minimum year-over-year rent growth rate (decimal, e.g.,
0.05 for 5%).
example: -0.05
rent_growth_rate_yoy_avg_lte:
type: number
description: >-
Maximum year-over-year rent growth rate (decimal, e.g.,
0.10 for 10%).
example: 0.1
population_total_gte:
type: number
description: Minimum total population in the market.
example: 1000000
population_total_lte:
type: number
description: Maximum total population in the market.
example: 20000000
property_count_total_gte:
type: number
description: Minimum number of properties in the market.
example: 100
property_count_total_lte:
type: number
description: Maximum number of properties in the market.
example: 1000
advertised_occupancy_percent_avg_t30_gte:
type: number
description: >-
Minimum 30-day average advertised occupancy percentage
(decimal, e.g., 0.90 for 90%).
example: 0.85
advertised_occupancy_percent_avg_t30_lte:
type: number
description: >-
Maximum 30-day average advertised occupancy percentage
(decimal, e.g., 0.99 for 99%).
example: 0.99
property_filters:
type: object
description: >-
Filters applied to properties before aggregating market
metrics. Only properties matching these filters will
contribute to the market-level calculations.
properties:
year_built_gte:
type: number
description: Minimum year the property was built.
example: 2015
year_built_lte:
type: number
description: Maximum year the property was built.
example: 2024
total_units_gte:
type: number
description: Minimum total number of units in the property.
example: 200
total_units_lte:
type: number
description: Maximum total number of units in the property.
example: 1000
collected_at_gte:
type: string
format: date-time
description: >-
Only include data collected on or after this date. ISO
8601 format.
example: '2025-11-01T00:00:00.000Z'
collected_at_lte:
type: string
format: date-time
description: >-
Only include data collected on or before this date. ISO
8601 format.
example: '2025-11-25T00:00:00.000Z'
number_of_stories_gte:
type: number
description: >-
Minimum number of stories/floors in the property
buildings.
example: 3
number_of_stories_lte:
type: number
description: >-
Maximum number of stories/floors in the property
buildings.
example: 50
property_class:
type: array
description: Filter by property classification grade.
items:
type: string
enum:
- A
- B
- C
example:
- A
- B
property_type:
type: array
description: Filter by property type/category.
items:
type: string
enum:
- conventional
- income_restricted
- section8
- senior_living
- student_housing
- build_to_rent
example:
- conventional
unified_status:
type: array
description: >-
Filter by unified property status. Consolidates
construction stage, implementation status, and lease-up
into a single lifecycle indicator.
items:
type: string
enum:
- stabilized
- planning
- scheduled_construction
- under_construction
- lease_up
example:
- stabilized
sort_by:
type: string
description: >-
Field to sort results by. Can be any numeric response
attribute.
example: population_total
sort_order:
type: string
description: Sort direction.
enum:
- asc
- desc
default: desc
example: desc
limit:
type: integer
description: Maximum number of markets to return.
minimum: 1
maximum: 100
default: 50
example: 50
examples:
By Specific Markets:
value:
account_id: 2222
filters:
geo_boundary_id:
- '94121'
- '94012'
geo_type: MSA
property_filters:
year_built_gte: 2015
total_units_gte: 200
sort_by: population_total
sort_order: desc
limit: 50
By State:
value:
account_id: 2222
filters:
geo_type: MSA
geo_states:
- CA
- TX
sort_by: rent_avg_t30
sort_order: desc
limit: 25
High Growth Markets:
value:
account_id: 2222
filters:
geo_type: MSA
rent_growth_rate_yoy_avg_gte: 0.03
population_total_gte: 500000
property_filters:
property_class:
- A
sort_by: rent_growth_rate_yoy_avg
sort_order: desc
limit: 20
responses:
'200':
description: >-
Successfully retrieved market data. Returns markets in JSON:API
format with comprehensive market-level metrics.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
description: Array of market data in JSON:API format.
items:
$ref: '#/components/schemas/CompareMarket'
'400':
description: Bad Request - Missing or invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Invalid Filter:
value:
error: 'Invalid filter parameter: invalid_field'
'401':
description: Unauthorized - Invalid or missing authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden - Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/RateLimitExceeded'
components:
schemas:
CompareMarket:
type: object
description: Market-level aggregated metrics in JSON:API format
required:
- id
- type
- attributes
properties:
id:
type: string
description: The geo boundary ID as a string
example: '94012'
type:
type: string
description: Resource type, always 'compare_market'
enum:
- compare_market
example: compare_market
attributes:
type: object
description: >-
Market attributes including geographic info, performance metrics,
inventory, demographics, and sales data
properties:
id:
type: integer
description: Unique geo boundary identifier
example: 94012
name:
type: string
description: Full name of the market
example: Los Angeles-Long Beach-Anaheim, CA Metro Area
short_name:
type: string
description: Shortened name of the market
example: Los Angeles-Long Beach-Anaheim, CA Metro Area
description:
type: string
description: Description of the market geography
example: Los Angeles-Long Beach-Anaheim, CA
geo_type:
type: string
description: Type of geographic boundary
enum:
- MSA
- BespokeSubmarket
example: MSA
geo_states:
type: array
description: US states that the market spans
items:
type: string
example:
- CA
place_type:
type: string
nullable: true
description: Type of place (if applicable)
centroid:
type: array
description: Geographic center of the market as [latitude, longitude]
items:
type: number
example:
- 34.1087033
- -118.1827533
property_count_total:
type: integer
description: Total number of properties in the market matching filters
example: 392
rent_avg_t30:
type: number
description: Average asking rent across all unit types (last 30 days)
example: 3261.04
rent_0_bed_avg_t30:
type: number
description: Average asking rent for studio units (last 30 days)
example: 2514.37
rent_1_bed_avg_t30:
type: number
description: Average asking rent for 1-bedroom units (last 30 days)
example: 2937.87
rent_2_bed_avg_t30:
type: number
description: Average asking rent for 2-bedroom units (last 30 days)
example: 3891.46
rent_3_bed_avg_t30:
type: number
description: Average asking rent for 3-bedroom units (last 30 days)
example: 5318.09
ner_avg_t30:
type: number
description: Average net effective rent across all unit types (last 30 days)
example: 3038.13
ner_0_bed_avg_t30:
type: number
description: Average net effective rent for studio units (last 30 days)
example: 2330.1
ner_1_bed_avg_t30:
type: number
description: Average net effective rent for 1-bedroom units (last 30 days)
example: 2738.23
ner_2_bed_avg_t30:
type: number
description: Average net effective rent for 2-bedroom units (last 30 days)
example: 3623.31
ner_3_bed_avg_t30:
type: number
description: Average net effective rent for 3-bedroom units (last 30 days)
example: 4891.74
rent_psf_avg_t30:
type: number
description: >-
Average asking rent per square foot across all unit types (last
30 days)
example: 3.85
rent_0_bed_psf_avg_t30:
type: number
description: >-
Average asking rent per square foot for studio units (last 30
days)
example: 4.48
rent_1_bed_psf_avg_t30:
type: number
description: >-
Average asking rent per square foot for 1-bedroom units (last 30
days)
example: 3.95
rent_2_bed_psf_avg_t30:
type: number
description: >-
Average asking rent per square foot for 2-bedroom units (last 30
days)
example: 3.51
rent_3_bed_psf_avg_t30:
type: number
description: >-
Average asking rent per square foot for 3-bedroom units (last 30
days)
example: 3.54
ner_psf_avg_t30:
type: number
description: >-
Average net effective rent per square foot across all unit types
(last 30 days)
example: 3.59
ner_0_bed_psf_avg_t30:
type: number
description: >-
Average net effective rent per square foot for studio units
(last 30 days)
example: 4.14
ner_1_bed_psf_avg_t30:
type: number
description: >-
Average net effective rent per square foot for 1-bedroom units
(last 30 days)
example: 3.68
ner_2_bed_psf_avg_t30:
type: number
description: >-
Average net effective rent per square foot for 2-bedroom units
(last 30 days)
example: 3.28
ner_3_bed_psf_avg_t30:
type: number
description: >-
Average net effective rent per square foot for 3-bedroom units
(last 30 days)
example: 3.26
ner_psf_p88_t30:
type: number
description: >-
88th percentile net effective rent per square foot (last 30
days)
example: 4.31
ner_psf_p68_t30:
type: number
description: >-
68th percentile net effective rent per square foot (last 30
days)
example: 3.76
ner_psf_p18_t30:
type: number
description: >-
18th percentile net effective rent per square foot (last 30
days)
example: 3.02
rent_growth_rate_yoy_avg:
type: number
description: Average year-over-year rent growth rate (decimal)
example: -0.0073
ner_growth_rate_yoy_avg:
type: number
description: Average year-over-year net effective rent growth rate (decimal)
example: -0.0101
forecasted_rent_growth_rate_yoy:
type: number
description: Forecasted year-over-year rent growth rate (decimal)
example: 0.0257
rent_growth_rate_yoy_by_quarter_avg:
type: number
description: Average year-over-year rent growth rate by quarter (decimal)
example: -0.0064
ner_growth_rate_yoy_by_quarter_avg:
type: number
description: >-
Average year-over-year net effective rent growth rate by quarter
(decimal)
example: -0.0061
rent_growth_rate_t90_avg:
type: number
description: Average rent growth rate over the last 90 days (decimal)
example: -0.0185
ner_growth_rate_t90_avg:
type: number
description: >-
Average net effective rent growth rate over the last 90 days
(decimal)
example: -0.0277
concession_value_avg_t30:
type: number
description: Average concession value in dollars (last 30 days)
example: 4175.48
concession_percent_avg_t30:
type: number
description: Average concession as percentage of rent (last 30 days, decimal)
example: 0.1036
exposure_percent_avg_t30:
type: number
description: >-
Average exposure percentage - units available for lease (last 30
days, decimal)
example: 0.0749
leased_percent_avg_t30:
type: number
description: Average percentage of units leased (last 30 days, decimal)
example: 0.9325
advertised_occupancy_percent_avg_t30:
type: number
description: Average advertised occupancy percentage (last 30 days, decimal)
example: 0.9274
days_on_market_avg_t30:
type: number
description: Average days on market (last 30 days)
example: 50.64
total_unit_count:
type: integer
description: Total number of units across all properties in the market
example: 142374
existing_unit_count_total:
type: integer
description: Total units in existing (non-new supply) properties
example: 125696
new_supply_unit_count_total:
type: integer
description: Total units in new supply properties
example: 16678
under_construction_unit_count_total:
type: integer
description: Total units currently under construction
example: 7308
planned_unit_count_total:
type: integer
description: Total units in planned developments
example: 2403
delivered_unit_count_total_mtd:
type: integer
description: Units delivered month-to-date
example: 0
delivered_unit_count_total_t365:
type: integer
description: Units delivered in the last 365 days
example: 8777
available_unit_count_new_to_market_total_mtd:
type: integer
description: New-to-market available units month-to-date
example: 3066
leased_unit_count_total_mtd:
type: integer
description: Units leased month-to-date
example: 2707
available_unit_count_total_t30:
type: integer
description: Total available units (last 30 days)
example: 14176
leased_unit_count_total_t30:
type: integer
description: Total units leased (last 30 days)
example: 3308
unit_sq_ft_avg:
type: integer
description: Average unit square footage
example: 879
amenity_count_p50:
type: integer
description: Median amenity count across properties
example: 30
year_built_p50:
type: integer
description: Median year built across properties
example: 2021
year_renovated_p50:
type: integer
description: Median year renovated across properties
example: 2020
building_square_feet_avg:
type: number
nullable: true
description: Average building square footage
rentable_building_area_sq_ft_avg:
type: number
description: Average rentable building area in square feet
example: 333893
rentable_building_area_sq_ft_per_floor_avg:
type: number
description: Average rentable area per floor in square feet
example: 55864
land_area_sq_ft_avg:
type: number
description: Average land area in square feet
example: 213385
land_area_acres_avg:
type: number
description: Average land area in acres
example: 4.9
units_per_acre_avg:
type: number
description: Average units per acre
example: 157.78
units_per_building_avg:
type: number
description: Average units per building
example: 291.74
units_per_floor_avg:
type: number
description: Average units per floor
example: 66.5
number_of_stories_avg:
type: number
description: Average number of stories
example: 8.71
building_count_avg:
type: number
description: Average number of buildings per property
example: 1.77
walk_score_avg:
type: integer
description: Average Walk Score across properties
example: 74
transit_score_avg:
type: integer
description: Average Transit Score across properties
example: 61
bike_score_avg:
type: integer
description: Average Bike Score across properties
example: 64
population_growth_last_5_years_total:
type: number
description: Total population growth rate over the last 5 years (decimal)
example: -0.0353
population_growth_last_5_years_20_29:
type: number
description: >-
Population growth rate for ages 20-29 over the last 5 years
(decimal)
example: -0.1159
population_growth_last_5_years_30_39:
type: number
description: >-
Population growth rate for ages 30-39 over the last 5 years
(decimal)
example: -0.0074
population_growth_last_5_years_40_54:
type: number
description: >-
Population growth rate for ages 40-54 over the last 5 years
(decimal)
example: -0.0319
population_growth_last_5_years_55_up:
type: number
description: >-
Population growth rate for ages 55+ over the last 5 years
(decimal)
example: 0.039
population_total:
type: integer
description: Total population in the market
example: 12866598
population_20_29:
type: integer
description: Population aged 20-29
example: 1741263
population_30_39:
type: integer
description: Population aged 30-39
example: 1950682
population_40_54:
type: integer
description: Population aged 40-54
example: 2553323
population_55_up:
type: integer
description: Population aged 55 and older
example: 3689869
median_income:
type: integer
description: Median household income in dollars
example: 94295
median_income_growth_yoy:
type: number
description: Year-over-year median income growth rate (decimal)
example: -0.0125
employed_labor_force_percent:
type: number
description: Percentage of labor force that is employed (decimal)
example: 0.9392
employed_labor_force_growth_rate_yoy:
type: number
description: Year-over-year employment growth rate (decimal)
example: 0.006
sold_property_count_total_t365:
type: integer
description: Number of properties sold in the last 365 days
example: 12
sold_unit_count_total_t365:
type: integer
description: Total units in properties sold in the last 365 days
example: 4101
sold_unit_count_avg_t365:
type: integer
description: Average units per property sold in the last 365 days
example: 341
sale_price_avg_t365:
type: number
description: Average sale price in the last 365 days
example: 135230561.33
sale_price_total_t365:
type: number
description: Total sales volume in the last 365 days
example: 1622766736
sale_price_avg_t365_per_unit:
type: number
description: Average sale price per unit in the last 365 days
example: 396925.04
sale_cap_rate_avg_t365:
type: number
description: Average cap rate for sales in the last 365 days (decimal)
example: 0.0476
sale_price_per_unit_growth_yoy:
type: number
description: Year-over-year sale price per unit growth rate (decimal)
example: -0.0141
cap_rate_avg:
type: number
nullable: true
description: Average cap rate
asset_value_total:
type: number
description: Total estimated asset value in the market
example: 45284183238
asset_value_per_unit_avg:
type: number
nullable: true
description: Average asset value per unit
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.
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: {}
````