Public API v1

The Futuros public API is versioned static data. Futuros is a frontend-only platform: there is no query server behind /api/v1/. Everything is baked from public/data/ by scripts/bake-api.ts and served as plain files over the CDN. Every endpoint below is a plain HTTP GET of a file — no auth, no API key, no rate limit, fully cacheable.

• Base URL: https://futuros.xyz/api/v1/
• Discovery (DCAT catalog): https://futuros.xyz/data.json (at the site root, not under /api/v1/)
• Human docs page: https://futuros.xyz/datos-abiertos

Because the responses are static files, an endpoint is just its path. Fetch one with curl, a browser, fetch(), pandas.read_csv, R, or any SDMX/DCAT client.

Stability contract

The manifest states it verbatim:

Shapes are additive-only within v1; breaking changes go to /api/v2/.

Practically:

• Fields may be added to any object within v1. Do not assume a fixed key set — read by key, ignore unknowns.
• Existing field names, types and meanings will not change within v1.
• A breaking change (renaming/removing a field, changing units or semantics) ships as a new /api/v2/ tree; /api/v1/ keeps working.
• index.json carries api_version, generated_at, and a stability string — read generated_at to detect a rebuild.

CORS & caching

Set in vercel.json for every /api/* path:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Cache-Control: public, max-age=3600, s-maxage=86400

So the API is cross-origin readable from any browser app (GET/OPTIONS only — it is read-only), edge-cached for a day. There is no write surface here.

License & attribution

From index.json:

• license_url: https://creativecommons.org/licenses/by/4.0/ (CC BY 4.0)
• license (verbatim): "Datos redistribuidos de fuentes abiertas; cada observación conserva su fuente primaria (source_name, source_url, citation_id). Al reutilizar: cite la fuente primaria de cada observación y «Futuros» como agregador."

In English: the data is redistributed from open sources; every observation keeps its primary source (name, deep-link URL, and citation_id). When you reuse it, cite each observation's primary source and credit Futuros as the aggregator. Nothing is imputed or synthesized — the honesty contract of the baker is that every value on the wire carries the source it came from.

Interoperability standards

index.json → standards declares the codes the API speaks so UNSD-SDG, World Bank Data360, OECD.AI and CEPALSTAT can ingest it directly:

Standard	Where
REF_AREA = UN M49 numeric + ISO 3166-1 alpha-3	every geography & observation
SDG global indicator framework (A/RES/71/313)	sdg block per indicator + sdg-crosswalk.json
SDMX-CSV (ISO 17369)	observations.sdmx.csv
DCAT (project-open-data v1.1)	/data.json

---

The manifest — index.json

Start here. It lists every dataset, live counts, the license, the stability statement, and a machine-readable endpoints map (path templates for the rest).

curl -s https://futuros.xyz/api/v1/index.json

{
  "name": "Futuros — API de datos abiertos",
  "api_version": "1",
  "generated_at": "2026-06-17T15:10:20.390Z",
  "docs": "/datos-abiertos",
  "license": "Datos redistribuidos de fuentes abiertas; …",
  "license_url": "https://creativecommons.org/licenses/by/4.0/",
  "delta_basis": "latest value vs mean of the prior 3 years (smooths COVID-era volatility)",
  "stability": "Shapes are additive-only within v1; breaking changes go to /api/v2/.",
  "standards": {
    "ref_area": "UN M49 numeric (REF_AREA) + ISO 3166-1 alpha-3",
    "sdg": "UN SDG global indicator framework (A/RES/71/313); see /api/v1/sdg-crosswalk.json",
    "sdmx": "SDMX-CSV (ISO 17369) at /api/v1/observations.sdmx.csv",
    "catalog": "DCAT (project-open-data v1.1) at /data.json"
  },
  "counts": {
    "parameters": 10, "geographies": 26, "cells": 260,
    "observations": 137044, "sdg_tagged_indicator_instances": 2946,
    "citations": 5091, "signal_files": 250, "contributions": 0
  },
  "endpoints": { "parameters": "/api/v1/parameters.json", "…": "…" }
}

counts.geographies is 26 because the 25 countries include the LATAM regional aggregate (M49 419). A cell is one parameter × one geography; an observation is one indicator-year row.

---

Parameters — parameters.json

The 10 Futuros pillars, in display order, each with its primary/secondary SDG goals.

curl -s https://futuros.xyz/api/v1/parameters.json

[
  { "slug": "salud", "name_es": "Salud", "name_en": "Salud",
    "display_order": 1, "sdg_primary": [3], "sdg_secondary": [2, 6] },
  { "slug": "educacion", "name_es": "Educación", "…": "…" }
]

Use slug (e.g. salud, educacion, cohesion-social-inclusion) as the <param> segment in observation paths.

Geographies — geographies.json

The 25 countries plus the LATAM region, each with ISO3 and M49.

curl -s https://futuros.xyz/api/v1/geographies.json

[
  { "iso3": "LATAM", "m49": "419", "slug": "latam",
    "name_es": "América Latina y el Caribe", "name_en": "Latin America and the Caribbean",
    "level": "region", "sub_region": null, "population_2024": null },
  { "iso3": "ARG", "m49": "032", "slug": "argentina", "level": "country", "…": "…" }
]

Use iso3 (e.g. MEX, ARG, BRA) as the <ISO> segment in observation paths. M49 codes are zero-padded strings ("032", "484").

---

Observations — one cell

The core dataset. One file per parameter × country, addressed as observations/<param>__<ISO3>.json (note the double underscore separator).

JSON

curl -s https://futuros.xyz/api/v1/observations/salud__MEX.json

{
  "api_version": "1",
  "generated_at": "2026-06-17T15:10:20.390Z",
  "parameter": { "slug": "salud", "label_es": "Salud" },
  "geography": { "iso3": "MEX", "m49": "484", "name_es": "México",
                 "name_en": "México", "level": "country" },
  "confidence": "high",
  "last_refreshed": "2026-06-15T16:20:52.364Z",
  "indicators": [
    {
      "indicator_id": "sp_dyn_le00_in",
      "label_es": "Esperanza de vida al nacer",
      "unit": "años",
      "latest": { "year": 2024, "value": 75.264 },
      "delta_pct": 3.199,
      "delta_basis": "latest value vs mean of the prior 3 years (smooths COVID-era volatility)",
      "good_direction": "up",
      "coverage": "primary",
      "benchmark": { "oecd": 80.39, "world": 73.48, "sea_peers": 73.87, "oecd_vintage": 2024 },
      "sdg": { "code": "3", "level": "goal",
               "indicator_name": "Ensure healthy lives and well-being …", "goal": 3 },
      "source": {
        "name": "World Bank Open Data",
        "url": "https://data.worldbank.org/indicator/SP.DYN.LE00.IN?locations=MX",
        "citation_id": "wb-sp-dyn-le00-in-mex-2024"
      },
      "series": [ { "year": 2000, "value": 72.562 }, { "year": 2001, "value": 72.912 }, "…" ]
    }
  ]
}

Every indicator carries latest (year + value), the full series back to ~2000, its source (name + primary-source deep link + citation_id), an official sdg code when one exists (level is indicator, target or goal), and delta_pct (see delta_basis: latest vs. the mean of the prior 3 years). sdg is null when no official SDG code applies — never fabricated.

CSV

The same cell flattened to one row per indicator-year:

curl -s https://futuros.xyz/api/v1/observations/salud__MEX.csv

Header:

parameter,iso3,m49,indicator_id,label_es,unit,year,value,delta_pct_latest,
good_direction,coverage,vintage_year,sdg_code,sdg_level,source_name,source_url,citation_id

Observations — bulk

Every cell concatenated into one CSV — the whole corpus in a single download (~137k rows):

curl -s https://futuros.xyz/api/v1/observations.csv -o futuros-observations.csv

Same header as the per-cell CSV. Load directly:

import pandas as pd
df = pd.read_csv("https://futuros.xyz/api/v1/observations.csv")

Observations — SDMX-CSV

The bulk data as SDMX-CSV (ISO 17369), REF_AREA keyed on UN M49 to match UNSD-SDG / Data360 conventions:

curl -s https://futuros.xyz/api/v1/observations.sdmx.csv

DATAFLOW,FREQ,REF_AREA,INDICATOR,TIME_PERIOD,OBS_VALUE,UNIT_MEASURE,
SDG_INDICATOR,REF_AREA_ISO3,FUTUROS_PARAMETER,SOURCE,SOURCE_URL,CITATION_ID
FUTUROS:DF_OBSERVATIONS(1.0),A,032,si_pov_gini,2000,51,índice,10,ARG,
cohesion-social-inclusion,World Bank Open Data,https://data.worldbank.org/…,wb-si-pov-gini-arg-2024

DATAFLOW is FUTUROS:DF_OBSERVATIONS(1.0), FREQ is A (annual).

Excel workbook — futuros-data.xlsx

One workbook with five sheets — README (license + delta_pct basis), parameters, geographies, observations (all rows), and citations:

curl -s https://futuros.xyz/api/v1/futuros-data.xlsx -o futuros-data.xlsx

---

Citations — citations.json / citations.csv

The full source registry every citation_id resolves against.

curl -s https://futuros.xyz/api/v1/citations.json
curl -s https://futuros.xyz/api/v1/citations.csv

CSV columns: id,source,title,url,year,retrieved_at. Join observations.*'s citation_id to citations.*'s id to attach full source metadata to any value.

Freshness ledger — freshness.json

Per-source refresh cadence — when each indicator was last pulled and when it is next due. A passthrough of the build's refresh-meta.json.

curl -s https://futuros.xyz/api/v1/freshness.json

{
  "generated_at": "2026-06-15T16:20:52.364Z",
  "total_indicators": 48,
  "indicators": {
    "SI.POV.GINI": {
      "source": "World Bank Open Data",
      "source_url": "https://data.worldbank.org/indicator/SI.POV.GINI",
      "cadence_months": 12,
      "last_refreshed": "2026-06-15T16:20:52.364Z",
      "next_refresh_due": "2027-08-15T20:11:16.364Z",
      "countries_with_data": 0, "total_countries": 25
    }
  }
}

SDG crosswalk — sdg-crosswalk.json

The verified map from pillars and indicators to official SDG codes (goals, pillars, indicators). Join on indicator_id.

curl -s https://futuros.xyz/api/v1/sdg-crosswalk.json

Signals — signals/<param>__<ISO3>.json

LLM-extracted, cited "what's moving" signals per cell (present because the multi-source layer is baked). Same <param>__<ISO3> addressing as observations; a cell with no current signals returns an empty array [].

curl -s https://futuros.xyz/api/v1/signals/salud__ARG.json

Contributions — contributions.json

License-gated data contributed through the Data Trust (Pillar 1), published only for postures that permit republishing values. Currently count: 0.

curl -s https://futuros.xyz/api/v1/contributions.json

---

Discovery — DCAT catalog at /data.json

A DCAT / project-open-data v1.1 catalog at the site root (not under /api/v1/) so data portals and crawlers can auto-discover the datasets:

curl -s https://futuros.xyz/data.json

It advertises the bulk CSV, SDMX-CSV, XLSX, citations, SDG crosswalk and freshness datasets, each with downloadURL, mediaType and CC BY 4.0 license.

Endpoint reference

Path	What
/api/v1/index.json	Manifest: datasets, counts, license, standards
/api/v1/parameters.json	10 pillars + primary/secondary SDGs
/api/v1/geographies.json	25 countries + LATAM, ISO3 + M49
/api/v1/observations/<param>__<ISO3>.json	One cell: indicators, series, citations, SDG
/api/v1/observations/<param>__<ISO3>.csv	Same cell, one row per indicator-year
/api/v1/observations.csv	Bulk: every cell concatenated
/api/v1/observations.sdmx.csv	Bulk, SDMX-CSV (ISO 17369), REF_AREA = M49
/api/v1/futuros-data.xlsx	Workbook (README/parameters/geographies/observations/citations)
/api/v1/citations.json · .csv	Full citation registry
/api/v1/freshness.json	Per-source refresh ledger
/api/v1/sdg-crosswalk.json	Pillar → SDG + indicator → official SDG code
/api/v1/signals/<param>__<ISO3>.json	Cited signals per cell
/api/v1/contributions.json	License-gated contributed data
/data.json	DCAT catalog (site root)

For agentic, tool-based access to the same corpus (with deterministic compute and citations), see the MCP server.