> ## 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

> Compare aggregated metrics across MSAs and submarkets.

Evaluate and compare markets at a glance by retrieving aggregated metrics for MSAs and submarkets. This endpoint returns market-level summaries including rent performance, inventory levels, demographics, and transaction data.

This workflow is designed for investors, asset managers, and analysts who need to:

* Screen markets for acquisition or expansion opportunities
* Compare rent growth, occupancy, and supply trends across metros
* Analyze demographic drivers like population growth and income levels
* Benchmark sales activity and cap rates across markets
* Build market rankings based on custom criteria

### Prerequisites

* A Bearer token (see [Authentication](/v1/authentication))
* Account ID
* Geo boundary IDs for the markets you want to compare (find these using Search Geo Boundaries)

<Tip>If you need an API token, see [Getting started](/v1) → "Get an API token".</Tip>

### 1) Find markets to compare

First, search for the markets you want to analyze. Use the geo boundaries search to find MSAs or submarkets by name.

```bash theme={null}
curl -s -X POST \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": <account_id>,
    "query": "*",
    "geo_type": ["MSA"],
    "limit": 50
  }' \
  "https://data.apartmentiq.io/apartmentiq/api/v1/geo_boundaries/search"
```

Save the `id` values from the results—these are the geo boundary IDs you'll use in the next step.

<Tip>Use `query: "*"` with `geo_type: ["MSA"]` to retrieve all available metros, or search by name (e.g., "Austin") for specific markets.</Tip>

### 2) Compare market metrics

Pass the geo boundary IDs to retrieve aggregated metrics for each market.

```bash theme={null}
curl -s -X POST \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": <account_id>,
    "filters": {
      "geo_boundary_id": ["94121", "94012", "94216"],
      "geo_type": "MSA"
    },
    "sort_by": "population_total",
    "sort_order": "desc",
    "limit": 50
  }' \
  "https://data.apartmentiq.io/apartmentiq/api/v1/explore_markets"
```

The response includes comprehensive metrics for each market:

* **Performance**: Average rent, NER, rent PSF, concessions, occupancy, exposure, days on market
* **Rent by bedroom**: Rent and NER broken down by studio, 1-bed, 2-bed, and 3-bed
* **Growth**: Year-over-year and 90-day rent/NER growth rates, plus forecasted growth
* **Inventory**: Total units, property count, new supply, under construction, delivered units
* **Demographics**: Population by age group, growth rates, median income, employment
* **Sales**: Transaction count, volume, price per unit, cap rates

### 3) Filter by property characteristics

Use `property_filters` to control which properties contribute to the market aggregations. This lets you compare markets for a specific property profile.

```bash theme={null}
curl -s -X POST \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": <account_id>,
    "filters": {
      "geo_type": "MSA",
      "geo_states": ["TX", "FL", "AZ"]
    },
    "property_filters": {
      "year_built_gte": 2015,
      "total_units_gte": 200,
      "property_class": ["A"]
    },
    "sort_by": "rent_growth_rate_yoy_avg",
    "sort_order": "desc",
    "limit": 25
  }' \
  "https://data.apartmentiq.io/apartmentiq/api/v1/explore_markets"
```

<Note>Property filters narrow the properties included in each market's calculations. For example, filtering to Class A properties built since 2015 shows metrics based only on that subset.</Note>

### 4) Screen markets by performance

Use market-level filters to find markets that meet specific criteria.

```bash theme={null}
curl -s -X POST \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": <account_id>,
    "filters": {
      "geo_type": "MSA",
      "rent_growth_rate_yoy_avg_gte": 0.02,
      "population_total_gte": 1000000,
      "advertised_occupancy_percent_avg_t30_gte": 0.92
    },
    "sort_by": "forecasted_rent_growth_rate_yoy",
    "sort_order": "desc",
    "limit": 20
  }' \
  "https://data.apartmentiq.io/apartmentiq/api/v1/explore_markets"
```

This example finds large metros with positive rent growth and strong occupancy, sorted by forecasted growth.

### Filter options

**Market-level filters** (`filters`):

* Geography: `geo_boundary_id[]`, `geo_type`, `geo_states[]`
* Performance: `rent_avg_t30_gte|lte`, `ner_avg_t30_gte|lte`, `advertised_occupancy_percent_avg_t30_gte|lte`
* Growth: `rent_growth_rate_yoy_avg_gte|lte`
* Scale: `population_total_gte|lte`, `property_count_total_gte|lte`

**Property-level filters** (`property_filters`):

* Physical: `year_built_gte|lte`, `total_units_gte|lte`, `number_of_stories_gte|lte`
* Classification: `property_class[]`, `property_type[]`, `unified_status[]`
* Data recency: `collected_at_gte|lte`

### Example analyses to try

* Market screening: "Find Sun Belt MSAs with 2%+ rent growth, 1M+ population, and 93%+ occupancy."
* New supply impact: "Compare markets by `new_supply_unit_count_total` relative to `existing_unit_count_total` to assess supply pressure."
* Demographic targeting: "Rank markets by `population_growth_last_5_years_20_29` to find metros attracting young renters."
* Investment benchmarking: "Sort by `sale_cap_rate_avg_t365` to compare transaction yields across markets."
* Submarket deep-dive: "Switch `geo_type` to `BespokeSubmarket` and filter to a single MSA to compare submarkets within a metro."

### Errors and rate limits

* 400 for invalid or missing parameters
* 401 if authorization is missing or invalid
* 403 if you lack permissions
* 429 if you exceed the rate limit
* See [Errors](/v1/errors) and [Rate limits](/v1/rate-limits)