---
title: "Compare places"
method: GET
path: "/api/v1/compare"
---

# Compare places

`GET /api/v1/compare`

## Request

- Base URL: `https://invokely.ai`
- URL: `https://invokely.ai/api/v1/compare`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`
  - none

Compare one indicator across 2 to 10 places for the same period, using one shared source and definition whenever possible.
Use it for "how does X compare with Y and Z". Places can mix levels, for example a city, a larger city and its region.
Example: {"indicator": "registered_unemployment_rate", "places": ["Mataró", "Barcelona", "Cataluña"]}.
Returns {indicator, period, comparable, values: [{place, value, period?, status?}], source or sources, notes?}. When comparable is false the values come from different sources (and sometimes periods) and notes explain why; mention it in your answer.
For unemployment in municipalities use registered_unemployment_rate: the survey unemployment_rate is not published below province level.
transform applies the same rule to every place, for example {"indicator": "gdp", "places": ["Spain", "Germany", "France"], "transform": "per_capita"}. Population and price index series shared by every place are preferred; each value lists its inputs, and comparable is false when places needed different ones or a place could not be computed (notes say why).
With as_of every value is the one Invokely held then, with version, known_since, revised_later and current; comparable reflects the sources available then.

## Query parameters

- `indicator` string, required
- `place` string[], required
- `period` string
- `country` string
- `locale` 'en' | 'es'
- `transform` 'pct_change' | 'yoy' | 'diff' | 'yoy_diff' | 'index' | 'rolling_mean' | 'per_capita' | 'per_1000' | 'per_100k' | 'real' | 'share_of_parent'
- `base` string
- `window` integer
- `citation_style` 'apa' | 'mla' | 'chicago' | 'harvard' | 'bibtex' | 'ris' | 'all'
- `as_of` string

## Response `200`

Success. The body is {"data": ...}; the remaining allowance is in the x-invokely-remaining header.

- Data
  - `data` unknown, required

## Other responses

- `400`: Invalid argument (INVALID_ARGUMENT).
- `401`: The API key or token is invalid or revoked (UNAUTHORIZED).
- `402`: Allowance used up (QUOTA_EXHAUSTED), or the plan does not include the REST API (PLAN_REQUIRED: Free keys; use the MCP server or upgrade to Builder).
- `404`: Unknown indicator or place, or no data (INDICATOR_NOT_FOUND, PLACE_NOT_FOUND, AMBIGUOUS_PLACE, NO_DATA). hint and suggestions say what to try next.
- `429`: Rate limited (RATE_LIMITED). Retry after retry_after_seconds.

---

[API](https://skmtc.dev/invokely/apis/invokely-statistics-api.md) · [All operations](https://skmtc.dev/invokely/apis/invokely-statistics-api/llms.txt) · [OpenAPI document](https://skmtc.dev/invokely/apis/invokely-statistics-api/revisions/3b0f775bccb6?raw)