Compare places

Compare one indicator across 2 to 10 places for the same period, using one shared source and definition whenever possible. Use it for "how does X compare with Y and Z". Places can mix levels, for example a city, a larger city and its region. Example: {"indicator": "registered_unemployment_rate", "places": ["Mataró", "Barcelona", "Cataluña"]}. Returns {indicator, period, comparable, values: [{place, value, period?, status?}], source or sources, notes?}. When comparable is false the values come from different sources (and sometimes periods) and notes explain why; mention it in your answer. For unemployment in municipalities use registered_unemployment_rate: the survey unemployment_rate is not published below province level. transform applies the same rule to every place, for example {"indicator": "gdp", "places": ["Spain", "Germany", "France"], "transform": "per_capita"}. Population and price index series shared by every place are preferred; each value lists its inputs, and comparable is false when places needed different ones or a place could not be computed (notes say why). With as_of every value is the one Invokely held then, with version, known_since, revised_later and current; comparable reflects the sources available then.

get/api/v1/compare

Request

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

Query parameters

indicatorstring required

Indicator id, for example population or registered_unemployment_rate. List them with /api/v1/catalog.

placestring[] required

Repeat for each place (2 to 10). A places parameter separated by | or ; is also accepted.

periodstring

2024 (year), 2024-Q3 (quarter), 2024-S1 (half year) or 2024-09 (month). Omit for the latest value.

countrystring

ISO 3166-1 alpha-2 code that disambiguates the place, for example ES or US.

locale'en' | 'es'

Language of names and definitions. Default en.

transform'pct_change' | 'yoy' | 'diff' | 'yoy_diff' | 'index' | 'rolling_mean' | 'per_capita' | 'per_1000' | 'per_100k' | 'real' | 'share_of_parent'

Calculation done by the server, with every input cited: pct_change, yoy, diff, yoy_diff, index (needs base), rolling_mean (window), per_capita, per_1000, per_100k, real (inflation adjusted, base is the price year) or share_of_parent. See the get_value tool description and /docs#transforms.

basestring

index: the period equal to 100, for example 2015 or 2020-01. real: the year whose prices values are in, for example 2024.

windowinteger

rolling_mean: number of periods averaged.

citation_style'apa' | 'mla' | 'chicago' | 'harvard' | 'bibtex' | 'ris' | 'all'

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. Omit to keep the response short.

as_ofstring
Example:2026-10-03

Point in time, UTC: a date (the end of that day) or a date and time with a zone. Returns the figures as Invokely held them then, with version, known_since, revised_later and the current value when it changed since. Not in the future.

Response

Success. The body is {"data": ...}; the remaining allowance is in the x-invokely-remaining header.

dataunknown required

Changes

No recorded changes to this operation across all 1 revision of this API.