> ## 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.
# Search Geo Boundaries
> Searches for geo boundaries by name and type. Returns matching geographic areas including MSAs, Submarkets, Census Places (Cities, Towns, etc.), Counties, Zip Codes, and Neighborhoods. Result order is weighted by property count and geo type relevance.
Once you've found the geo boundary you're looking for, its Geo Boundary ID can be used to filter properties by market or other geographic location, as well as to find other intersecting geo boundaries.
## OpenAPI
````yaml /openapi/v1/schema.json post /geo_boundaries/search
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_boundaries/search:
post:
tags:
- Markets
summary: Search Geo Boundaries
description: >-
Searches for geo boundaries by name and type. Returns matching
geographic areas including MSAs, Submarkets, Census Places (Cities,
Towns, etc.), Counties, Zip Codes, and Neighborhoods. Result order is
weighted by property count and geo type relevance.
Once you've found the geo boundary you're looking for, its Geo Boundary ID can be used to filter properties by market or other geographic location, as well as to find other intersecting geo boundaries.
operationId: searchGeoBoundaries
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: 1111
query:
type: string
description: >-
The search query for geo boundary names. Supports partial
matching and word start matching. Use '*' or omit to return
all boundaries.
default: '*'
example: raleigh
geo_type:
type: array
description: >-
Filter results by geo boundary type(s). Can be a single
value or an array of values. If not provided, all types are
returned.
items:
type: string
enum:
- MSA
- BespokeSubmarket
- CensusPlace
- ZipCode
- County
- Neighborhood
example:
- MSA
- BespokeSubmarket
limit:
type: integer
description: >-
Maximum number of results to return. Must be between 1 and
1000.
minimum: 1
maximum: 1000
default: 10
example: 10
geo_boundary_id:
type: integer
description: >-
Filter results to boundaries that intersect with this geo
boundary ID.
example: 123
intersecting_geometry:
type: object
description: >-
[GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) Polygon or
MultiPolygon geometry object to filter results by spatial
intersection.
properties:
type:
type: string
enum:
- Polygon
- MultiPolygon
example: Polygon
coordinates:
type: array
description: >-
Coordinate array following GeoJSON specification
(longitude, latitude pairs)
example:
- - - -78.663
- 35.821
- - -78.663
- 35.85
- - -78.623
- 35.85
- - -78.623
- 35.821
- - -78.663
- 35.821
example:
type: Polygon
coordinates:
- - - -78.663
- 35.821
- - -78.663
- 35.85
- - -78.623
- 35.85
- - -78.623
- 35.821
- - -78.663
- 35.821
examples:
Basic Search:
value:
account_id: your_account_id
query: raleigh
geo_type:
- MSA
- BespokeSubmarket
limit: 10
Search All Boundaries:
value:
account_id: your_account_id
query: '*'
limit: 50
Intersecting with Geo Boundary:
value:
account_id: your_account_id
query: downtown
geo_boundary_id: 123
geo_type:
- BespokeSubmarket
Intersecting with Custom Geometry:
value:
account_id: your_account_id
intersecting_geometry:
type: Polygon
coordinates:
- - - -78.663
- 35.821
- - -78.663
- 35.85
- - -78.623
- 35.85
- - -78.623
- 35.821
- - -78.663
- 35.821
geo_type:
- ZipCode
- County
responses:
'200':
description: Successfully retrieved matching geo boundaries.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
description: Array of geo boundary search results
items:
$ref: '#/components/schemas/GeoBoundarySearchResult'
example:
data:
- id: '1'
type: geo_boundary_search_result
attributes:
id: 1
name: Raleigh-Cary, NC Metro Area
description: Raleigh-Cary, NC
geo_type: MSA
centroid:
- 35.7567464
- -78.4604412
property_count: 8053
place_type: null
- id: '2'
type: geo_boundary_search_result
attributes:
id: 2
name: Raleigh, NC
description: Raleigh city, North Carolina
geo_type: CensusPlace
centroid:
- 35.835066941818184
- -78.61623107999999
property_count: 3098
place_type: city
'400':
description: Bad Request - Invalid parameters provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: 'Invalid geo type: InvalidType'
'401':
description: Unauthorized - Invalid or missing authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden - User does not have access to this account or feature
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: The requested resource was not found.
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
description: >-
An unexpected error occurred while processing the request. Our team
is investigating.
components:
schemas:
GeoBoundarySearchResult:
type: object
description: A geo boundary search result in JSON:API format.
required:
- id
- type
- attributes
properties:
id:
type: string
description: The unique identifier of the geo boundary.
example: '1'
type:
type: string
description: The resource type.
enum:
- geo_boundary_search_result
example: geo_boundary_search_result
attributes:
type: object
description: The geo boundary attributes.
required:
- id
- name
- geo_type
- centroid
properties:
id:
type: integer
description: The numeric ID of the geo boundary.
example: 1
name:
type: string
description: The display name of the geo boundary.
example: Raleigh-Cary, NC Metro Area
description:
type: string
description: A brief description of the geo boundary location.
nullable: true
example: Raleigh-Cary, NC
geo_type:
type: string
description: The type of geo boundary.
enum:
- MSA
- BespokeSubmarket
- CensusPlace
- ZipCode
- County
- Neighborhood
example: MSA
centroid:
type: array
description: The geographic center point as [latitude, longitude].
items:
type: number
format: float
minItems: 2
maxItems: 2
example:
- 35.7567464
- -78.4604412
property_count:
type: integer
description: The approximate number of properties within this geo boundary.
nullable: true
example: 8053
place_type:
type: string
description: >-
The specific place type for CensusPlace boundaries (e.g.,
'city', 'town').
nullable: true
example: city
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: {}
````