---
title: "Get one value"
method: GET
path: "/api/v1/value"
---

# Get one value

`GET /api/v1/value`

## Request

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

Get one official figure for an indicator and place: the latest by default, or a given period.
Use it for questions like "population of Mataró", "inflation in Spain in 2024-09", "unemployment rate in Cataluña", "unemployment rate in Texas".
Example: {"indicator": "population", "place": "Mataró"}.
Returns {indicator: {id, name, unit}, place: {id, name, level}, period, value, status?, source: {name, title, url, retrieved, published?, citation, inputs?}, note?}. note is a caveat about the source series served.
Pass citation_style ("apa", "mla", "chicago", "harvard", "bibtex", "ris" or "all") when the user wants a formatted reference: the source block then carries citations {style: text}.
Always cite source.citation or source.url when you answer. When source.via is present (Data Commons), the publisher is still the original agency; the citation already names both. status "provisional" or "estimated" means the figure may be revised; say so. status "low_reliability" means the publisher flags the figure as of low reliability (usually a small survey sample); say so and treat it as a rough indication.
If the indicator is not published for that place you get an error that names the levels where it exists and related indicators that do have data.
Calculated figures: pass transform instead of doing the arithmetic yourself. Examples: {"indicator": "gdp", "place": "Spain", "transform": "per_capita"}, {"indicator": "median_household_income", "place": "Texas", "period": "2019", "transform": "real", "base": "2024"}, {"indicator": "registered_unemployment", "place": "Mataró", "transform": "yoy"}. The result adds transform {id, name, description, unit, from_unit, base?, notes?} and inputs [{role, indicator, place, period, value, unit, source}]; indicator.unit is the unit of the result. Cite the inputs' sources as well. A value that cannot be computed (no earlier period, no population for that year) is a NO_DATA error with the reason, never an estimate. Without period, when the latest period cannot be computed yet (this year's population not published), the latest period that can, at most two years earlier, is returned and transform.notes says so: quote the period returned. status is set when the value or any input is provisional or estimated.
Point in time: pass as_of for "what was reported for September as of October 3". The answer adds as_of, version, known_since (when Invokely first held that version), revised_later and, when the figure changed since, current {value, status?, version, known_since}; say that it was revised. Source choice follows the same rules applied to the data held then. Before Invokely first stored the figure you get NO_DATA with vintage_coverage_starts, never today's value. With a transform, every input (earlier value, population, parent place, price index) is read as held at as_of, and each input carries version and known_since.

## Query parameters

- `indicator` string, required
- `place` string, required
- `period` string
- `frequency` 'year' | 'half' | 'quarter' | 'month'
- `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)