---
title: "TerriData Ranking"
method: POST
path: "/co/terridata/ranking/v1"
tags: ["Colombia", "DNP TerriData"]
---

# TerriData Ranking

`POST /co/terridata/ranking/v1`

## Request

- Base URL: `https://api.croma.run`
- URL: `https://api.croma.run/co/terridata/ranking/v1`
- Auth: HTTP bearer

Rank Colombia's municipalities (or departments) on one indicator of the DNP's territorial statistics (TerriData) for a year, or on each territory's latest value: highest or lowest first, optionally within one department. Returns rank, territory, year and value, plus the indicator's unit and producing agency. Served by Croma (`as_of` says how current the data is).

**Dataset endpoint**: answers from the whole source in milliseconds and carries `as_of`.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `indicator_code` string, required: Nine-digit indicator code, as the indicator search returns it.
  - `year` integer: Optional year to compare, e.g. `2024`. `0` compares each territory's latest value.
  - `level` 'municipality' | 'department': Optional level to compare: `municipality` (default) or `department`.
  - `department_code` string: Optional two-digit DANE code of a department, e.g. `05` for Antioquia: only its municipalities are compared.
  - `order` 'desc' | 'asc': Optional order: `desc` (highest value first, the default) or `asc`.
  - `page` integer: 1-based page number for paginated results.
  - `per_page` integer: Results per page (1-100).

## Response `200`

Successful response

- TerridataRankingResponse
  - `data` TerridataRankingData, required
    - `as_of` string, nullable, required
    - `found` boolean, required: False when no territory at that level has a numeric value for the indicator (and year).
    - `indicator_code` string, required
    - `indicator` string, nullable, required
    - `dimension` string, nullable, required
    - `unit` string, nullable, required
    - `data_source` string, nullable, required
    - `year` integer, nullable, required: The year compared; null when each territory's latest value is compared.
    - `level` 'municipality' | 'department', required
    - `department_code` string, nullable, required
    - `order` 'desc' | 'asc', required
    - `total` integer, required
    - `page` integer, required
    - `per_page` integer, required
    - `total_pages` integer, required
    - `count` integer, required
    - `results` object[], required
      - `rank` integer, required
      - `territory_code` string, required
      - `territory_name` string, required
      - `department_code` string, required
      - `department_name` string, required
      - `year` integer, required
      - `month` integer, nullable, required
      - `value` number, required

## Other responses

- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream source returned an error

---

[API](https://skmtc.dev/usecroma/apis/croma-marketplace-api.md) · [All operations](https://skmtc.dev/usecroma/apis/croma-marketplace-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usecroma/apis/croma-marketplace-api/revisions/df016cdb29d7?raw)