Formato de consulta

Lo usan la herramienta MCP query_data y POST /api/v1/query. Esquema legible por máquinas: /schema/query.json.

El cubo

Cada valor es una observación de un indicador, para un lugar, en un período (2024, 2024-03, 2026-10-05). Una consulta elige indicadores, lugares y períodos; la respuesta llega como filas, como una matriz anidada y, opcionalmente, como GeoJSON.

Campos

campo	significado
indicators	De 1 a 10 identificadores de indicador obtenidos con find_indicators, p. ej. FIN.BRANCHES_PER_100K_ADULTS.
geo.in	Países (GT SV HN NI CR PA BZ DO), grupos (CA7 istmo, SICA8, NTCA Triángulo Norte) o códigos de departamento / municipio (GT13, GT1301) obtenidos con resolve_place o list_places.
geo.rollup	true: cada grupo se convierte en un solo valor regional. false (predeterminado): los grupos se expanden a sus países.
geo.drill	department, municipality o district: expande cada lugar a sus unidades de ese nivel.
time	{from, to} en años, o {last: N} para los N períodos más recientes con datos. Omítelo para obtener el más reciente.
by	Ejes de la matriz, del más externo al más interno (indicator, geo, time). Por defecto, toda dimensión con más de un valor.
format	["rows","matrix"] por defecto; agrega "geojson" para obtener límites con valores.

Los valores regionales son honestos

Cada indicador declara cómo puede combinarse entre lugares:

• sum — montos y conteos (US$, personas).
• weighted_mean — tasas y proporciones, ponderadas por aquello de lo que son tasa (adultos, población, PIB). Un valor regional en % del PIB es exactamente la suma de los numeradores entre la suma de los PIB.
• none — no comparable entre países (líneas nacionales de pobreza, tasas de interés, Gini). Se rechaza la agregación y se lista en refused; nunca se aproxima.

Un valor regional construido con menos miembros que el total lleva complete: false y coverage.missing. Una suma regional a la que le falta un miembro devuelve value: null más partial_value. Los valores que una fuente nunca publicó se listan en gaps.

Ejemplos

Banca en Centroamérica, un solo valor regional

{ "indicators": ["FIN.BRANCHES_PER_100K_ADULTS"], "geo": { "in": ["CA7"], "rollup": true } }

Guatemala, últimos tres años

{ "indicators": ["FIN.BRANCHES_PER_100K_ADULTS"], "geo": { "in": ["GT"] }, "time": { "last": 3 } }

Tres países × tres años

{ "indicators": ["FIN.BRANCHES_PER_100K_ADULTS"], "geo": { "in": ["GT","SV","HN"] }, "time": { "from": 2021, "to": 2023 } }

Todos los municipios de Huehuetenango, con límites

{ "indicators": ["POP.TOTAL"], "geo": { "in": ["GT13"], "drill": "municipality" }, "format": ["rows","geojson"] }

Respuesta

{
  "query":      { "...": "the resolved query, including the periods used" },
  "places":     { "GT": { "name": "Guatemala", "level": "country", "lat": 15.7, "lon": -90.3 } },
  "indicators": [{ "id": "...", "unit": "...", "rollup": "weighted_mean", "weighted_by": "POP.ADULTS" }],
  "dimensions": [{ "id": "geo", "values": ["GT","SV","HN"] }, { "id": "time", "values": ["2021","2022","2023"] }],
  "rows":       [{ "indicator": "...", "geo": "GT", "time": "2021", "value": 23.4, "source": "wb-wdi" }],
  "matrix":     { "GT": { "2021": 23.4 } },
  "gaps":       [{ "indicator": "...", "geo": "HN", "time": "2023", "reason": "..." }],
  "map_layers": ["/geo/shapes/GT-municipality.geojson"],
  "sources":    [{ "id": "wb-wdi", "publisher": "World Bank", "license": "CC BY 4.0", "retrieved": "..." }]
}

Como máximo 2,000 valores por consulta; las preguntas más acotadas reciben respuestas más rápidas y baratas. Los errores explican qué cambiar y sugieren identificadores válidos.

Query format

Used by the query_data MCP tool and POST /api/v1/query. Machine-readable schema: /schema/query.json.

The cube

Every value is one observation of an indicator, for a place, in a period (2024, 2024-03, 2026-10-05). A query picks indicators, places and periods; the answer comes back as rows, as a nested matrix, and optionally as GeoJSON.

Fields

field	meaning
indicators	1–10 indicator ids from find_indicators, e.g. FIN.BRANCHES_PER_100K_ADULTS.
geo.in	Countries (GT SV HN NI CR PA BZ DO), groups (CA7 isthmus, SICA8, NTCA Northern Triangle), or department / municipality codes (GT13, GT1301) from resolve_place or list_places.
geo.rollup	true: each group becomes one regional value. false (default): groups expand to their countries.
geo.drill	department, municipality or district: expand each place to its units at that level.
time	{from, to} in years, or {last: N} for the N most recent periods with data. Omit for the latest.
by	Matrix axes, outermost first (indicator, geo, time). Defaults to every dimension with more than one value.
format	["rows","matrix"] by default; add "geojson" for boundaries with values.

Regional values are honest

Each indicator declares how it may be combined across places:

• sum — amounts and counts (US$, people).
• weighted_mean — rates and shares, weighted by what they are a rate of (adults, population, GDP). A %-of-GDP regional value is exactly the sum of numerators over the sum of GDP.
• none — not comparable across countries (national poverty lines, interest rates, Gini). A rollup is refused and listed under refused, never approximated.

A regional value built from fewer than all members carries complete: false and coverage.missing. A regional sum with a missing member returns value: null plus partial_value. Values a source never published are listed in gaps.

Examples

Banking across Central America, one regional value

{ "indicators": ["FIN.BRANCHES_PER_100K_ADULTS"], "geo": { "in": ["CA7"], "rollup": true } }

Guatemala, last three years

{ "indicators": ["FIN.BRANCHES_PER_100K_ADULTS"], "geo": { "in": ["GT"] }, "time": { "last": 3 } }

Three countries × three years

{ "indicators": ["FIN.BRANCHES_PER_100K_ADULTS"], "geo": { "in": ["GT","SV","HN"] }, "time": { "from": 2021, "to": 2023 } }

Every municipality of Huehuetenango, with boundaries

{ "indicators": ["POP.TOTAL"], "geo": { "in": ["GT13"], "drill": "municipality" }, "format": ["rows","geojson"] }

Response

{
  "query":      { "...": "the resolved query, including the periods used" },
  "places":     { "GT": { "name": "Guatemala", "level": "country", "lat": 15.7, "lon": -90.3 } },
  "indicators": [{ "id": "...", "unit": "...", "rollup": "weighted_mean", "weighted_by": "POP.ADULTS" }],
  "dimensions": [{ "id": "geo", "values": ["GT","SV","HN"] }, { "id": "time", "values": ["2021","2022","2023"] }],
  "rows":       [{ "indicator": "...", "geo": "GT", "time": "2021", "value": 23.4, "source": "wb-wdi" }],
  "matrix":     { "GT": { "2021": 23.4 } },
  "gaps":       [{ "indicator": "...", "geo": "HN", "time": "2023", "reason": "..." }],
  "map_layers": ["/geo/shapes/GT-municipality.geojson"],
  "sources":    [{ "id": "wb-wdi", "publisher": "World Bank", "license": "CC BY 4.0", "retrieved": "..." }]
}

At most 2,000 values per query; narrower questions get faster, cheaper answers. Errors explain what to change and suggest valid ids.