> ## 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 Markets
> Retrieve bulk market rows for geographic boundaries using optional geography filters, property filters, requested fields, and pagination.
Requires Explore Pro access.
## OpenAPI
````yaml /openapi/v2/schema.json post /markets/bulk
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:
post:
tags:
- Bulk
summary: Bulk Markets
description: >-
Retrieve bulk market rows for geographic boundaries using optional
geography filters, property filters, requested fields, and pagination.
Requires Explore Pro access.
operationId: createV2MarketsBulk
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkMarketsRequest'
example:
account_id: '{account_id}'
interval: month
geo_filters:
geo_types:
- MSA
inside_geo_boundary_ids:
- 1
- 2
property_filters:
collected_at_gte: '2026-05-01'
total_units_gte: 100
fields:
- rent
- days_on_market
page: 2
per_page: 50
responses:
'200':
description: Bulk market rows and pagination metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkMarketsResponse'
example:
rows:
- name: Madison, WI Metro Area
geo_boundary_id: 4127
geo_type: MSA
msa_name: null
submarket_name: null
period: 2026-05
rent: 1784.22
rent_0_bed: 1328.15
rent_1_bed: 1626.4
rent_2_bed: 2038.72
rent_3_bed: 2544.18
ner: 1738.66
ner_0_bed: 1284.3
ner_1_bed: 1588.94
ner_2_bed: 1984.62
ner_3_bed: 2481.35
rent_psf: 2.36
rent_0_bed_psf: 3.04
rent_1_bed_psf: 2.61
rent_2_bed_psf: 2.1
rent_3_bed_psf: 1.83
ner_psf: 2.3
ner_0_bed_psf: 2.94
ner_1_bed_psf: 2.55
ner_2_bed_psf: 2.04
ner_3_bed_psf: 1.78
rent_growth_rate_yoy: 0.0284
ner_growth_rate_yoy: 0.0269
concession_value: 410.25
concession_percent: 0.0196
days_on_market: 27.46
occupancy_percent: 0.9411
leased_percent: 0.9534
exposure_percent: 0.0892
absorbed_unit_count: 612
delivered_unit_count: 544
- name: Downtown Madison
geo_boundary_id: 90114
geo_type: Submarket
msa_name: Madison, WI Metro Area
submarket_name: null
period: 2026-05
rent: 1922.41
rent_0_bed: 1442.88
rent_1_bed: 1776.5
rent_2_bed: 2264.72
rent_3_bed: null
ner: 1858.03
ner_0_bed: 1379.18
ner_1_bed: 1718.06
ner_2_bed: 2202.44
ner_3_bed: null
rent_psf: 2.58
rent_0_bed_psf: 3.23
rent_1_bed_psf: 2.81
rent_2_bed_psf: 2.22
rent_3_bed_psf: null
ner_psf: 2.49
ner_0_bed_psf: 3.09
ner_1_bed_psf: 2.72
ner_2_bed_psf: 2.16
ner_3_bed_psf: null
rent_growth_rate_yoy: 0.0376
ner_growth_rate_yoy: 0.0344
concession_value: 520
concession_percent: 0.0238
days_on_market: 22.08
occupancy_percent: 0.9488
leased_percent: 0.9615
exposure_percent: 0.0754
absorbed_unit_count: 118
delivered_unit_count: 96
pagination:
current_page: 2
total_pages: 4
total_count: 175
per_page: 50
'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:
BulkMarketsRequest:
type: object
description: Request contract for the API V2 markets bulk export endpoint.
properties:
account_id:
$ref: '#/components/schemas/AccountId'
interval:
type: string
enum:
- month
- quarter
- year
description: >-
Optional period bucket for requested metrics. Omit for one summary
row per market.
fields:
type: array
items:
type: string
enum:
- rent
- rent_0_bed
- rent_1_bed
- rent_2_bed
- rent_3_bed
- ner
- ner_0_bed
- ner_1_bed
- ner_2_bed
- ner_3_bed
- rent_psf
- rent_0_bed_psf
- rent_1_bed_psf
- rent_2_bed_psf
- rent_3_bed_psf
- ner_psf
- ner_0_bed_psf
- ner_1_bed_psf
- ner_2_bed_psf
- ner_3_bed_psf
- rent_growth_rate_yoy
- ner_growth_rate_yoy
- concession_value
- concession_percent
- days_on_market
- occupancy_percent
- leased_percent
- exposure_percent
- absorbed_unit_count
- delivered_unit_count
description: >-
Metric field to include. Absorption and delivery fields require
interval quarter.
uniqueItems: true
description: >-
Optional metric field names. Omit or pass an empty array for
identity-only rows.
geo_filters:
$ref: '#/components/schemas/GeoFilters'
property_filters:
$ref: '#/components/schemas/MarketPropertyFilters'
page:
type: integer
minimum: 1
default: 1
description: One-based page number for the export result set.
per_page:
type: integer
minimum: 1
maximum: 100
default: 25
description: Number of rows per page. Values above the maximum are clamped.
required:
- account_id
additionalProperties: false
BulkMarketsResponse:
type: object
description: Paginated market bulk export results.
properties:
rows:
type: array
items:
type: object
description: Market identity fields plus requested metric fields.
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:
type:
- number
- 'null'
description: >-
Average asking rent. Returned when requested; null when metric
data is unavailable.
rent_0_bed:
type:
- number
- 'null'
description: >-
Average studio asking rent. Returned when requested; null when
metric data is unavailable.
rent_1_bed:
type:
- number
- 'null'
description: >-
Average one-bedroom asking rent. Returned when requested; null
when metric data is unavailable.
rent_2_bed:
type:
- number
- 'null'
description: >-
Average two-bedroom asking rent. Returned when requested; null
when metric data is unavailable.
rent_3_bed:
type:
- number
- 'null'
description: >-
Average three-bedroom asking rent. Returned when requested;
null when metric data is unavailable.
ner:
type:
- number
- 'null'
description: >-
Average net effective rent after concessions. Returned when
requested; null when metric data is unavailable.
ner_0_bed:
type:
- number
- 'null'
description: >-
Average studio net effective rent. Returned when requested;
null when metric data is unavailable.
ner_1_bed:
type:
- number
- 'null'
description: >-
Average one-bedroom net effective rent. Returned when
requested; null when metric data is unavailable.
ner_2_bed:
type:
- number
- 'null'
description: >-
Average two-bedroom net effective rent. Returned when
requested; null when metric data is unavailable.
ner_3_bed:
type:
- number
- 'null'
description: >-
Average three-bedroom net effective rent. Returned when
requested; null when metric data is unavailable.
rent_psf:
type:
- number
- 'null'
description: >-
Average null asking rent per square foot. Returned when
requested; null when metric data is unavailable.
rent_0_bed_psf:
type:
- number
- 'null'
description: >-
Average studio asking rent per square foot. Returned when
requested; null when metric data is unavailable.
rent_1_bed_psf:
type:
- number
- 'null'
description: >-
Average one-bedroom asking rent per square foot. Returned when
requested; null when metric data is unavailable.
rent_2_bed_psf:
type:
- number
- 'null'
description: >-
Average two-bedroom asking rent per square foot. Returned when
requested; null when metric data is unavailable.
rent_3_bed_psf:
type:
- number
- 'null'
description: >-
Average three-bedroom asking rent per square foot. Returned
when requested; null when metric data is unavailable.
ner_psf:
type:
- number
- 'null'
description: >-
Average null net effective rent per square foot. Returned when
requested; null when metric data is unavailable.
ner_0_bed_psf:
type:
- number
- 'null'
description: >-
Average studio net effective rent per square foot. Returned
when requested; null when metric data is unavailable.
ner_1_bed_psf:
type:
- number
- 'null'
description: >-
Average one-bedroom net effective rent per square foot.
Returned when requested; null when metric data is unavailable.
ner_2_bed_psf:
type:
- number
- 'null'
description: >-
Average two-bedroom net effective rent per square foot.
Returned when requested; null when metric data is unavailable.
ner_3_bed_psf:
type:
- number
- 'null'
description: >-
Average three-bedroom net effective rent per square foot.
Returned when requested; null when metric data is unavailable.
rent_growth_rate_yoy:
type:
- number
- 'null'
description: >-
Year-over-year asking rent growth rate. Returned when
requested; null when metric data is unavailable.
ner_growth_rate_yoy:
type:
- number
- 'null'
description: >-
Year-over-year net effective rent growth rate. Returned when
requested; null when metric data is unavailable.
concession_value:
type:
- number
- 'null'
description: >-
Average concession value. Returned when requested; null when
metric data is unavailable.
concession_percent:
type:
- number
- 'null'
description: >-
Average concession as a percentage of rent. Returned when
requested; null when metric data is unavailable.
days_on_market:
type:
- number
- 'null'
description: >-
Average days on market for available units. Returned when
requested; null when metric data is unavailable.
occupancy_percent:
type:
- number
- 'null'
description: >-
Average modeled occupancy percentage. Returned when requested;
null when metric data is unavailable.
leased_percent:
type:
- number
- 'null'
description: >-
Average leased percentage. Returned when requested; null when
metric data is unavailable.
exposure_percent:
type:
- number
- 'null'
description: >-
Average percentage of units exposed for lease. Returned when
requested; null when metric data is unavailable.
absorbed_unit_count:
type:
- number
- 'null'
description: >-
Units absorbed during the selected period. Returned when
requested; null when metric data is unavailable.
delivered_unit_count:
type:
- number
- 'null'
description: >-
Units delivered during the selected period. Returned when
requested; null when metric data is unavailable.
required:
- name
- geo_boundary_id
- geo_type
additionalProperties: false
description: >-
Market rows for the current page. Each row includes market identity
fields and any requested metric fields.
pagination:
$ref: '#/components/schemas/Pagination'
description: Pagination details for the market bulk export 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
MarketPropertyFilters:
type: object
description: Property filters used when calculating market-level metric values.
properties:
amenity_ids:
anyOf:
- type: array
items:
anyOf:
- type: integer
- type: string
- type: string
description: Amenity IDs that matching properties must include.
bathroom_count:
anyOf:
- type: array
items:
type: number
- type: string
description: Bathroom counts that matching properties must offer.
bedroom_count:
anyOf:
- type: array
items:
type: integer
- type: string
description: Bedroom counts that matching properties must offer.
collected_at_gte:
type: string
format: date
description: >-
Inclusive start date for metric data. Must be on or after
2022-01-01.
collected_at_lte:
type: string
format: date
description: Inclusive end date for metric data. Must be on or after 2022-01-01.
concession_percent_gte:
type: number
description: Minimum concession percentage, expressed as a decimal value.
concession_percent_lte:
type: number
description: Maximum concession percentage, expressed as a decimal value.
concession_value_gte:
type: number
description: Minimum advertised concession value in dollars.
concession_value_lte:
type: number
description: Maximum advertised concession value in dollars.
construction_state:
anyOf:
- type: array
items:
type: string
- type: string
description: Construction state filters such as existing or new_supply.
exposure_gte:
type: number
description: Minimum exposure percentage, expressed as a decimal value.
exposure_lte:
type: number
description: Maximum exposure percentage, expressed as a decimal value.
leased_percent_gte:
type: number
description: Minimum leased percentage, expressed as a decimal value.
leased_percent_lte:
type: number
description: Maximum leased percentage, expressed as a decimal value.
ner_gte:
type: number
description: Minimum net effective rent.
ner_lte:
type: number
description: Maximum net effective rent.
ner_per_sq_ft_gte:
type: number
description: Minimum net effective rent per square foot.
ner_per_sq_ft_lte:
type: number
description: Maximum net effective rent per square foot.
number_of_stories_gte:
type: number
description: Minimum property story count.
number_of_stories_lte:
type: number
description: Maximum property story count.
occupancy_gte:
type: number
description: Minimum occupancy percentage, expressed as a decimal value.
occupancy_lte:
type: number
description: Maximum occupancy percentage, expressed as a decimal value.
property_class:
anyOf:
- type: array
items:
type: string
enum:
- A
- B
- C
- D
- type: string
description: 'Property class values to include. Valid values: `A`, `B`, `C`, `D`.'
property_type:
anyOf:
- type: array
items:
type: string
enum:
- conventional
- student
- student_housing
- senior
- senior_living
- build_to_rent
- affordable
- type: string
description: >-
Property type filters to include. Valid values: `conventional`,
`student`, `student_housing`, `senior`, `senior_living`,
`build_to_rent`, `affordable`.
renovated_units:
type: boolean
description: Whether matching properties must have renovated unit inventory.
rent_gte:
type: number
description: Minimum advertised rent.
rent_lte:
type: number
description: Maximum advertised rent.
rent_per_sq_ft_gte:
type: number
description: Minimum advertised rent per square foot.
rent_per_sq_ft_lte:
type: number
description: Maximum advertised rent per square foot.
size_gte:
type: number
description: Minimum unit size in square feet.
size_lte:
type: number
description: Maximum unit size in square feet.
stakeholder_entity_ids:
anyOf:
- type: array
items:
anyOf:
- type: integer
- type: string
- type: string
description: Stakeholder entity IDs associated with matching properties.
total_units_gte:
type: number
description: Minimum total property unit count.
total_units_lte:
type: number
description: Maximum total property unit count.
unified_status:
anyOf:
- type: array
items:
type: string
enum:
- stabilized
- planning
- scheduled_construction
- under_construction
- lease_up
- type: string
description: Unified property status values to include.
year_built_gte:
type: number
description: Minimum year built.
year_built_lte:
type: number
description: Maximum year built.
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
````