---
title: "Rank places"
method: GET
path: "/api/v1/rank"
---

# Rank places

`GET /api/v1/rank`

## Request

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

Rank every place of one level inside an area by an indicator: all countries of the world, EU countries, US states, the counties or cities of a state, US cities, the regions of a country, the municipalities of a Spanish province.
Use it for "which state has the highest unemployment", "top 10 countries by GDP per capita", "poorest counties in Texas", "EU countries with the lowest inflation".
level is the level of the ranked places (country, region, province, municipality); within is the area they belong to. US states are regions of "United States"; US counties are provinces of a state; US cities are municipalities of "United States" or of a state; EU NUTS 2 regions are regions of "EU" or of a country.
Example: {"indicator": "unemployment_rate", "level": "region", "within": "United States", "limit": 5}. Countries of the world: {"indicator": "population", "level": "country"}.
Returns {indicator, level, within, period, comparable, order, total, values: [{rank, place, value, status?}], source, notes?}. Every value comes from one source and one period. order "asc" lists the lowest first. Cite source.citation.
For rates across municipalities pass min_population (for example 5000) so very small places, where a few people move the rate, do not top the list.
transform ranks a calculated figure: per_capita, per_1000 or per_100k for totals (population from one series for every place), yoy or yoy_diff for change from a year earlier. Example: {"indicator": "gdp_usd", "level": "region", "within": "United States", "transform": "per_capita"}. Each value lists its inputs; places without an input are left out and counted in notes.

## Query parameters

- `indicator` string, required
- `level` 'country' | 'region' | 'province' | 'municipality', required
- `within` string
- `period` string
- `order` 'desc' | 'asc'
- `limit` integer
- `min_population` integer
- `country` string
- `locale` 'en' | 'es'
- `transform` 'per_capita' | 'per_1000' | 'per_100k' | 'yoy' | 'yoy_diff'
- `citation_style` 'apa' | 'mla' | 'chicago' | 'harvard' | 'bibtex' | 'ris' | 'all'

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