# Citations and provenance

> Every number carries its source, licence, retrieval date and dataset version.

Every tool response carries three things next to the data: `citations`, `caveats` and
`dataset_version`. Show the citations and caveats whenever you quote a number.

## The citation object

| Field | Meaning |
|---|---|
| `source_id` | Stable id of the source, the same one used on the [coverage](/coverage) page |
| `name` | Dataset name |
| `publisher` | Who publishes the data |
| `url` | Where the publisher describes it (can be null) |
| `licence` | The licence as recorded, even when it is unclear |
| `commercial_use` | Whether the licence allows commercial use: `yes`, `no` or `unclear` |
| `attribution` | The text to print when you publish the number |
| `retrieved_at` | The date we retrieved the data |
| `dataset_version` | The version of the dataset behind the number |

## A real response

This is a citation exactly as the `query_metrics` tool returned it for the population of one
municipality. It was produced against the synthetic test dataset, so the name says `[FIXTURE]` and
the value is not a real statistic; production responses name the real source.

```json
{
  "source_id": "worldpop_population",
  "name": "[FIXTURE] WorldPop Constrained Population 100 m (R2025A)",
  "publisher": "WorldPop, University of Southampton",
  "url": "https://www.worldpop.org/",
  "licence": "CC-BY-4.0",
  "commercial_use": "yes",
  "attribution": "WorldPop (www.worldpop.org), University of Southampton. CC BY 4.0.",
  "retrieved_at": "2026-11-05",
  "dataset_version": "fixture-2026.11.05"
}
```

Each row of a result lists the `source_ids` behind it, so you can tell which citation belongs to
which value. When a value was converted between geographies, `is_estimate` is `true` and `method`
says how. See [Tool reference](/docs/tools) for full responses and `get_provenance` for a metric's
publisher, licence, method and lineage.