atlas
DOCS
PAYS & SÉRIES

Séries temporelles, comparaisons, classements

Les routes de cette page couvrent l'identité d'un pays, ses séries annuelles et mensuelles, la comparaison de plusieurs pays sur un même graphe, la prévision et le classement mondial d'un indicateur. Toutes acceptent l'en-tête X-API-Key optionnel décrit dans Démarrage — sans clé, la requête reste anonyme et soumise aux limites qui y sont documentées.

GET /api/countries GET /api/country/{code} GET /api/country/{code}/series GET /api/country/{code}/monthly/{indicator} GET /api/compare GET /api/country/{code}/forecast GET /api/country/{code}/rank/{indicator} GET /api/rank/{indicator} GET /api/rank/{indicator}/current
GET/api/countries

Liste des pays réellement couverts par Atlas, pour peupler un sélecteur. Aucun paramètre : la langue des noms suit l'en-tête Accept-Language.

Erreurs génériques : voir Démarrage. Cette route dégrade silencieusement vers la liste complète si World Bank est injoignable pour le filtre de couverture — jamais d'erreur renvoyée à l'appelant.
CURL
curl -H "X-API-Key: $ATLAS_KEY" \
  "https://atlasfeed.fr/api/countries"
PYTHON
import requests

r = requests.get(
    "https://atlasfeed.fr/api/countries",
    headers={"X-API-Key": ATLAS_KEY},
)
r.raise_for_status()
data = r.json()
JAVASCRIPT
const r = await fetch("https://atlasfeed.fr/api/countries", {
  headers: { "X-API-Key": ATLAS_KEY },
});
const data = await r.json();
RÉPONSE
{
  "count": 216,
  "countries": [
    {
      "code": "AFG", "iso2": "AF", "name": "Afghanistan",
      "names": {"fr": "Afghanistan", "en": "Afghanistan", "es": "Afganistán", "de": "Afghanistan"},
      "region": "Asie", "flagEmoji": "🇦🇫", "flagPng": "/flags/af.png"
    }
  ]
}
GET/api/country/{code}

Identité complète d'un pays (têtes d'État/de gouvernement, forme de gouvernement incluses) et dernière valeur connue de chaque indicateur demandé.

Paramètre
Type
Requis
Défaut
Description
code
string (path)
oui
—
Code pays, ISO3 en pratique.
indicators
string (query)
non
tout le catalogue curaté (117 codes)
Codes d'indicateurs séparés par des virgules.
Code
Erreur
Cas
404
unknown_country
Le pays est inconnu.
400
unknown_indicators
Aucun code de indicators n'est reconnu.
400
too_many_indicators
Plus de 120 codes explicites dédupliqués demandés.
CURL
curl -H "X-API-Key: $ATLAS_KEY" \
  "https://atlasfeed.fr/api/country/FRA?indicators=NY.GDP.MKTP.CD"
PYTHON
import requests

r = requests.get(
    "https://atlasfeed.fr/api/country/FRA",
    params={"indicators": "NY.GDP.MKTP.CD"},
    headers={"X-API-Key": ATLAS_KEY},
)
r.raise_for_status()
data = r.json()
JAVASCRIPT
const url = new URL("https://atlasfeed.fr/api/country/FRA");
url.searchParams.set("indicators", "NY.GDP.MKTP.CD");
const r = await fetch(url, { headers: { "X-API-Key": ATLAS_KEY } });
const data = await r.json();
RÉPONSE
{
  "country": {
    "code": "FRA", "iso2": "FR", "name": "France",
    "names": {"fr": "France", "en": "France", "es": "Francia", "de": "Frankreich"},
    "officialName": "République française", "nameEn": "France", "capital": "Paris",
    "region": "Europe", "subregion": null, "area": 643801.0, "latlng": [47.0, 2.0],
    "landlocked": false, "independent": true, "unMember": true,
    "borders": ["AND", "BEL", "BRA", "CHE", "DEU", "ESP", "ITA", "LUX", "MCO", "NLD", "SUR"],
    "tld": [".fr"], "callingCodes": ["+33"],
    "languages": [{"code": "fr", "name": "français"}],
    "currencies": [{"code": "EUR", "name": null, "symbol": "€"}],
    "flagEmoji": "🇫🇷", "flagPng": "/flags/fr.png",
    "headOfState": null, "headOfGovernment": "Sébastien Lecornu",
    "governmentForm": "régime semi-présidentiel"
  },
  "indicators": [
    {
      "code": "NY.GDP.MKTP.CD", "label": "PIB", "theme": "Économie", "unit": "US$ courants",
      "fmt": "currency", "headline": true,
      "latest": {
        "year": 2025, "value": 3366315927447.33, "previousYear": 2024,
        "previousValue": 3160442622465.08, "changeAbs": 205873304982.25,
        "changePct": 6.514065577994042, "preferredChange": "pct"
      },
      "unavailable": false
    }
  ]
}

unavailable: true signale un échec réseau de la source, distinct d'une absence réelle de donnée — ne jamais confondre les deux.

GET/api/country/{code}/series

Superset de /api/country/{code} : mêmes champs country, plus les séries temporelles complètes (points) et latest par indicateur, pour tracer des graphes.

Paramètre
Type
Requis
Défaut
Description
code
string (path)
oui
—
Code pays.
indicators
string (query)
non
tout le catalogue curaté
Codes séparés par des virgules.
start
int (query)
non
—
Année de début, ≥ 1960.
end
int (query)
non
—
Année de fin, ≤ 2100.
Code
Erreur
Cas
404
unknown_country
Pays inconnu.
400
unknown_indicators / too_many_indicators
Mêmes règles que /api/country/{code}.
CURL
curl -H "X-API-Key: $ATLAS_KEY" \
  "https://atlasfeed.fr/api/country/FRA/series\
?indicators=NY.GDP.MKTP.CD&start=2018&end=2022"
PYTHON
import requests

r = requests.get(
    "https://atlasfeed.fr/api/country/FRA/series",
    params={"indicators": "NY.GDP.MKTP.CD", "start": 2018, "end": 2022},
    headers={"X-API-Key": ATLAS_KEY},
)
data = r.json()
JAVASCRIPT
const url = new URL("https://atlasfeed.fr/api/country/FRA/series");
url.search = new URLSearchParams({
  indicators: "NY.GDP.MKTP.CD", start: "2018", end: "2022",
});
const data = await (await fetch(url, { headers: { "X-API-Key": ATLAS_KEY } })).json();
RÉPONSE
{
  "country": { "...": "identique à /api/country/{code}" },
  "range": {"start": 2018, "end": 2022},
  "series": [
    {
      "code": "NY.GDP.MKTP.CD", "label": "PIB", "theme": "Économie", "unit": "US$ courants",
      "fmt": "currency", "headline": true,
      "points": [
        {"year": 2018, "value": 2781576320884.39},
        {"year": 2019, "value": 2722793515171.76},
        {"year": 2020, "value": 2647926055110.05},
        {"year": 2021, "value": 2966433692008.09},
        {"year": 2022, "value": 2794788137066.94}
      ],
      "latest": {"year": 2025, "value": 3366315927447.33, "previousYear": 2024, "previousValue": 3160442622465.08, "changeAbs": 205873304982.25, "changePct": 6.514065577994042, "preferredChange": "pct"},
      "unavailable": false
    }
  ]
}

latest porte toujours la dernière valeur réelle, toutes années confondues — start/end ne fenêtrent que points.

GET/api/country/{code}/monthly/{indicator}

Série mensuelle si un fournisseur du registre monthly (Eurostat, Bank of Canada, BCE, BNR, NBG) couvre ce couple pays/indicateur. Sinon available: false en 200 — le cas courant, pas une erreur.

Paramètre
Type
Requis
Défaut
Description
code
string (path)
oui
—
Code pays.
indicator
string (path)
oui
—
Code d'indicateur unique.
Code
Erreur
Cas
404
unknown_country
Pays inconnu.
404
unknown_indicator
Indicateur absent du catalogue.
CURL
curl -H "X-API-Key: $ATLAS_KEY" \
  "https://atlasfeed.fr/api/country/FRA/monthly/FP.CPI.TOTL.ZG"
PYTHON
import requests

r = requests.get(
    "https://atlasfeed.fr/api/country/FRA/monthly/FP.CPI.TOTL.ZG",
    headers={"X-API-Key": ATLAS_KEY},
)
data = r.json()
JAVASCRIPT
const data = await (await fetch(
  "https://atlasfeed.fr/api/country/FRA/monthly/FP.CPI.TOTL.ZG",
  { headers: { "X-API-Key": ATLAS_KEY } },
)).json();
RÉPONSE
{
  "code": "FP.CPI.TOTL.ZG", "label": "Inflation", "theme": "Économie", "unit": "% annuel",
  "fmt": "percent", "headline": true, "available": true,
  "points": [
    {"year": 1997, "month": 1, "value": 1.8},
    {"year": 1997, "month": 2, "value": 1.7}
  ],
  "source": "Eurostat"
}

// Aucun fournisseur pour ce couple :
{"code": "...", "label": "...", "theme": "...", "unit": "...", "fmt": "...", "headline": true, "available": false, "points": []}
GET/api/compare

Mêmes séries pour jusqu'à 5 pays, superposables sur un même graphe.

Paramètre
Type
Requis
Défaut
Description
countries
string (query)
oui
—
Codes pays séparés par des virgules, tronqué aux 5 premiers.
indicators
string (query)
non
tout le catalogue curaté
Codes séparés par des virgules.
start
int (query)
non
—
≥ 1960.
end
int (query)
non
—
≤ 2100.
Code
Erreur
Cas
400
empty_countries_param
countries ne contient aucun code exploitable.
404
unknown_countries
Un ou plusieurs codes sont inconnus.
400
unknown_indicators / too_many_indicators
Mêmes règles que sur les autres routes pays.
429
too_many_requests_minute
Anonyme uniquement — 30 requêtes/minute par IP sur cette route.
CURL
curl -H "X-API-Key: $ATLAS_KEY" \
  "https://atlasfeed.fr/api/compare?countries=FRA,DEU\
&indicators=NY.GDP.MKTP.CD"
PYTHON
import requests

r = requests.get(
    "https://atlasfeed.fr/api/compare",
    params={"countries": "FRA,DEU", "indicators": "NY.GDP.MKTP.CD"},
    headers={"X-API-Key": ATLAS_KEY},
)
data = r.json()
JAVASCRIPT
const url = new URL("https://atlasfeed.fr/api/compare");
url.search = new URLSearchParams({
  countries: "FRA,DEU", indicators: "NY.GDP.MKTP.CD",
});
const data = await (await fetch(url, { headers: { "X-API-Key": ATLAS_KEY } })).json();
RÉPONSE
{
  "countries": [
    {
      "country": {"code": "FRA", "name": "France", "flagEmoji": "🇫🇷"},
      "series": [
        {
          "code": "NY.GDP.MKTP.CD", "label": "PIB", "theme": "Économie", "unit": "US$ courants",
          "fmt": "currency", "headline": true,
          "points": [{"year": 1960, "value": 61959085885.3427}],
          "unavailable": false
        }
      ]
    }
  ]
}
GET/api/country/{code}/forecast

Prévisions TimesFM prolongeant chaque série demandée. Le modèle se charge/compile au premier appel (plusieurs dizaines de secondes), puis reste rapide. Cette route n'est jamais soumise à un rate-limiting spécifique — même régime d'authentification que le reste de l'API.

Le forecast reste gratuit, hors de tout palier payant. TimesFM peut être indisponible sur ce déploiement (503, voir tableau des erreurs) : dans ce cas la fonctionnalité est absente, pas dégradée. Une réponse de succès porte toujours un disclaimer et, par série, un tableau warnings — à afficher systématiquement, jamais à masquer.
Paramètre
Type
Requis
Défaut
Description
code
string (path)
oui
—
Code pays.
indicators
string (query)
oui
—
Contrairement aux autres routes pays, obligatoire ici — absent ou vide, c'est une erreur.
horizon
int (query)
non
5
Nombre d'années à prévoir, entre 1 et 30.
Code
Erreur
Cas
400
forecast_indicators_required
indicators absent ou vide.
400
forecast_indicators_unknown
Aucun code fourni n'est reconnu — jamais remplacé par tout le catalogue.
400
forecast_too_many_indicators
Plus de 10 indicateurs valides demandés.
404
unknown_country
Pays inconnu (vérifié après la validation des paramètres).
503
forecast_unavailable
L'extra forecast (TimesFM) n'est pas installé sur ce déploiement.
429
too_many_requests_minute
Anonyme uniquement — 30/minute par IP.
CURL
curl -H "X-API-Key: $ATLAS_KEY" \
  "https://atlasfeed.fr/api/country/FRA/forecast\
?indicators=NY.GDP.MKTP.CD&horizon=5"
PYTHON
import requests

r = requests.get(
    "https://atlasfeed.fr/api/country/FRA/forecast",
    params={"indicators": "NY.GDP.MKTP.CD", "horizon": 5},
    headers={"X-API-Key": ATLAS_KEY},
)
data = r.json()
JAVASCRIPT
const url = new URL("https://atlasfeed.fr/api/country/FRA/forecast");
url.search = new URLSearchParams({ indicators: "NY.GDP.MKTP.CD", horizon: "5" });
const data = await (await fetch(url, { headers: { "X-API-Key": ATLAS_KEY } })).json();
RÉPONSE
{
  "country": {"code": "FRA", "name": "France", "flagEmoji": "🇫🇷"},
  "horizon": 5,
  "model": "timesfm-2.5-200m",
  "disclaimer": "Extrapolation zero-shot d'une série annuelle courte. Les valeurs World Bank sont révisées après publication et ont pu être vues au pré-entraînement : à lire comme une illustration, pas comme une prévision sur laquelle décider.",
  "series": [
    {
      "code": "NY.GDP.MKTP.CD", "label": "PIB", "theme": "Économie", "unit": "US$ courants",
      "fmt": "currency", "headline": true,
      "history": [{"year": 2020, "value": 2647926055110.05}],
      "forecast": [{"year": 2026, "value": 0}],
      "contextYears": 10,
      "unavailable": false,
      "warnings": []
    }
  ]
}

Une série non prévisible (par exemple un régime politique) renvoie "forecast": [] avec l'avertissement forecast_not_applicable dans son tableau warnings, au lieu d'une prévision. Une série dont la source a échoué porte en plus un avertissement données indisponibles : … et unavailable: true.

GET/api/country/{code}/rank/{indicator}

Rang mondial d'un pays sur un indicateur, à sa dernière année connue.

Paramètre
Type
Requis
Défaut
Description
code
string (path)
oui
—
Code pays.
indicator
string (path)
oui
—
Code d'indicateur unique.
Code
Erreur
Cas
404
unknown_country
Pays inconnu.
404
unknown_indicator
Indicateur inconnu.
501
ranking_unavailable
L'indicateur n'est pas de source World Bank — le classement n'existe que pour cette source.
CURL
curl -H "X-API-Key: $ATLAS_KEY" \
  "https://atlasfeed.fr/api/country/FRA/rank/NY.GDP.MKTP.CD"
PYTHON
import requests

r = requests.get(
    "https://atlasfeed.fr/api/country/FRA/rank/NY.GDP.MKTP.CD",
    headers={"X-API-Key": ATLAS_KEY},
)
data = r.json()
JAVASCRIPT
const data = await (await fetch(
  "https://atlasfeed.fr/api/country/FRA/rank/NY.GDP.MKTP.CD",
  { headers: { "X-API-Key": ATLAS_KEY } },
)).json();
RÉPONSE
{
  "code": "NY.GDP.MKTP.CD", "label": "PIB", "theme": "Économie", "unit": "US$ courants",
  "fmt": "currency", "headline": true,
  "rank": {
    "year": 2025, "position": 7, "total": 186,
    "top5": [
      {"code": "USA", "name": "États-Unis", "value": 30769700000000},
      {"code": "CHN", "name": "république populaire de Chine", "value": 19498039388042.6},
      {"code": "DEU", "name": "Allemagne", "value": 5050922925047.05},
      {"code": "JPN", "name": "Japon", "value": 4435162999976.94},
      {"code": "GBR", "name": "Royaume-Uni", "value": 4002587541846.01}
    ]
  }
}

Si le pays n'a aucune valeur pour cet indicateur : "rank": null en 200 — état normal, pas une erreur.

GET/api/rank/{indicator}

Classement mondial complet à une année donnée, explicite — jamais devinée par l'API.

Paramètre
Type
Requis
Défaut
Description
indicator
string (path)
oui
—
Code d'indicateur unique.
year
int (query)
oui
—
Année, entre 1960 et 2100.
Code
Erreur
Cas
422
validation
year absent ou hors bornes.
404
unknown_indicator
Indicateur inconnu.
501
ranking_unavailable
Source différente de World Bank.
CURL
curl -H "X-API-Key: $ATLAS_KEY" \
  "https://atlasfeed.fr/api/rank/NY.GDP.MKTP.CD?year=2022"
PYTHON
import requests

r = requests.get(
    "https://atlasfeed.fr/api/rank/NY.GDP.MKTP.CD",
    params={"year": 2022},
    headers={"X-API-Key": ATLAS_KEY},
)
data = r.json()
JAVASCRIPT
const url = new URL("https://atlasfeed.fr/api/rank/NY.GDP.MKTP.CD");
url.searchParams.set("year", "2022");
const data = await (await fetch(url, { headers: { "X-API-Key": ATLAS_KEY } })).json();
RÉPONSE
{
  "code": "NY.GDP.MKTP.CD", "label": "PIB", "theme": "Économie", "unit": "US$ courants",
  "fmt": "currency", "headline": true, "year": 2022,
  "ranking": [
    {"rank": 1, "code": "USA", "name": "États-Unis", "value": 26054614000000},
    {"rank": 2, "code": "CHN", "name": "république populaire de Chine", "value": 18316765021690.2},
    {"rank": 3, "code": "JPN", "name": "Japon", "value": 4447976207314.78}
  ]
}
GET/api/rank/{indicator}/current

Classement mondial « actuel » : chaque pays affiche sa propre dernière année connue, sans année commune imposée — utile pour ouvrir un classement directement depuis la recherche d'un indicateur.

Paramètre
Type
Requis
Défaut
Description
indicator
string (path)
oui
—
Code d'indicateur unique.
Code
Erreur
Cas
404
unknown_indicator
Indicateur inconnu.
501
ranking_unavailable
Source différente de World Bank.
CURL
curl -H "X-API-Key: $ATLAS_KEY" \
  "https://atlasfeed.fr/api/rank/NY.GDP.MKTP.CD/current"
PYTHON
import requests

r = requests.get(
    "https://atlasfeed.fr/api/rank/NY.GDP.MKTP.CD/current",
    headers={"X-API-Key": ATLAS_KEY},
)
data = r.json()
JAVASCRIPT
const data = await (await fetch(
  "https://atlasfeed.fr/api/rank/NY.GDP.MKTP.CD/current",
  { headers: { "X-API-Key": ATLAS_KEY } },
)).json();
RÉPONSE
{
  "code": "NY.GDP.MKTP.CD", "label": "PIB", "theme": "Économie", "unit": "US$ courants",
  "fmt": "currency", "headline": true,
  "ranking": [
    {
      "rank": 1, "code": "USA", "name": "États-Unis", "value": 30769700000000, "year": 2025,
      "points": [[2016, 18804913000000], [2017, 19612102000000]]
    }
  ]
}
Codes d'erreur communs (401/429) : voir Démarrage. Retour au sommaire