Get one value
get_valueGet 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | index: the period equal to 100, for example "2015" or "2020-01" (a year of a monthly series is the average of its months). real: the year whose prices values are expressed in, for example "2024". | |
| as_of | No | Optional point in time, UTC: a date ("2026-10-03", meaning the end of that day) or a date and time with a zone ("2026-10-03T14:30:00Z"). Returns the figures as Invokely held them at that instant, for backtests, audits and reproducible runs. Must not be in the future. | |
| place | Yes | Place name or id. Examples: "Mataró", "Barcelona", "provincia de Barcelona", "Cataluña", "España", "Germany", "EU", "es-mun-08121", "08121" (INE code), "ES51" (NUTS), "Texas", "Travis County, Texas", "us-county-48453", "fips:48453" (US county FIPS), "Austin, TX", "us-place-4805000", "fips:4805000" (US city GEOID). | |
| period | No | Optional. "2024" (year), "2024-Q3" (quarter), "2024-S1" (half year) or "2024-09" (month). Omit for the latest value. | |
| window | No | rolling_mean only: number of periods averaged, 2 to 12. Default 3. | |
| country | No | Optional ISO 3166-1 alpha-2 code to disambiguate the place, for example "ES" or "US". | |
| frequency | No | Optional. Force a frequency when the indicator exists in several (for example monthly and annual unemployment). | |
| indicator | Yes | Indicator id from search_indicators, for example "population", "registered_unemployment_rate", "unemployment_rate", "cpi_annual_change", "net_income_per_person". | |
| transform | No | Optional calculation done by the server, with every input cited. pct_change: % change from the previous period. yoy: % change from the same period a year earlier (12 months, 4 quarters or 1 year back). diff, yoy_diff: the same changes as differences, in the indicator unit (percentage points for rates). index: value / value in base x 100 (needs base). rolling_mean: average of the last window periods. per_capita, per_1000, per_100k: a total (population, births, GDP, emissions) divided by the population of the same place and year. real: a money amount at current prices adjusted for inflation with the consumer price index of the place's country in the same currency (base: price year, default the latest complete year). share_of_parent: a total as % of the parent place (county of its state, state of the nation, region of its country). Per person and share transforms refuse rates, shares, indices, medians and per person values, and share_of_parent also refuses net balances such as net migration; pct_change, yoy and index refuse percentages. | |
| citation_style | No | Optional. Adds source.citations with the citation in this style (APA 7, MLA 9, Chicago author-date, Harvard, BibTeX or RIS), or in all six with "all". The publisher is the author. Leave it out to keep the response short. |