4ème année

API pour la 4ème

Module 12 — Recherche d'information

4ème annéeCours

Première API · Open-Meteo

Demander la météo à un serveur, et comprendre sa réponse

Une API permet à deux programmes de se parler. Dans ce cours, tu interroges un vrai service météo gratuit, Open-Meteo, et tu apprends à lire ce qu'il te renvoie : du JSON.

  • Expliquer ce qu'est une API avec tes propres mots
  • Lire et construire l'adresse d'une requête (endpoint + paramètres)
  • Lire un document JSON et aller chercher une valeur précise
  • Écrire un petit programme qui affiche la météo de Dinant

Matériel : un navigateur (Firefox ou Chrome) et un éditeur de code. Pas d'inscription, pas de clé API.

Requête → ton programme envoie
GET https://api.open-meteo.com/v1/forecast
    ?latitude=50.26&longitude=4.91
    &current=temperature_2m
← Réponse 200 OK · application/json
{
  "latitude": 50.26,
  "longitude": 4.92,
  "current_units": { "temperature_2m": "°C" },
  "current": {
    "time": "2026-10-16T10:00",
    "temperature_2m": 11.8
  }
}

1C'est quoi une API ?

API veut dire Application Programming Interface, en français « interface de programmation ». C'est une porte d'entrée qu'un programme ouvre pour que d'autres programmes puissent lui demander des choses, en respectant des règles précises.

Quand l'appli météo de ton téléphone affiche 12 °C, ton téléphone n'a pas de thermomètre ni de station météo. L'appli a envoyé une question à une API, sur un serveur quelque part, et elle a reçu la réponse en quelques millisecondes. Ton programme, c'est le client. Celui qui répond, c'est le serveur.

L'API expliquée avec une friterie

Tu ne rentres pas dans la cuisine de la friterie pour te servir. Tu commandes au comptoir, avec les mots du menu, et on te rend un cornet. Une API fonctionne exactement comme ça.

À la friterieAvec une API
Le menu affiché au-dessus du comptoirLa documentation : la liste de ce qu'on peut demander et comment
Le comptoir où tu passes commandeL'endpoint : l'adresse précise où envoyer ta demande
« Une moyenne frite, sauce andalouse »La requête avec ses paramètres
La cuisine, que tu ne vois pasLe serveur et ses données
Le cornet, toujours emballé de la même façonLa réponse, toujours au même format : le JSON
« Désolé, la sauce pistache, ça n'existe pas »Une erreur : la requête demande quelque chose d'inconnu (code 400)

À retenir

Une API, c'est un contrat : « si tu me demandes ça, de cette façon, je te réponds ça, dans ce format ». Le client n'a pas besoin de savoir comment le serveur fonctionne à l'intérieur.

2Le vocabulaire

Ces mots reviennent dans toutes les documentations d'API. Apprends-les, tu les retrouveras partout.

Client
Le programme qui pose la question (ta page web, ton script).
Serveur
L'ordinateur, sur Internet, qui reçoit la question et répond.
Requête (request)
Le message envoyé par le client : une adresse, une méthode, des paramètres.
Réponse (response)
Le message renvoyé par le serveur : un code de statut et des données.
Endpoint
Une adresse précise de l'API, qui correspond à un service. Ici : /v1/forecast pour les prévisions.
Paramètre
Une précision ajoutée à la requête, sous la forme nom=valeur. Exemple : latitude=50.26.
Méthode HTTP
GET pour demander des données (ce qu'on fait dans ce cours). POST pour en envoyer, par exemple un formulaire.
Code de statut
Un nombre qui dit si tout s'est bien passé. 200 = OK. Voir le tableau ci-dessous.
Documentation
Le mode d'emploi de l'API. On la lit avant d'écrire du code.
Clé API
Un code secret qui identifie ton programme. Beaucoup d'API en exigent une. Open-Meteo n'en demande pas pour un usage non commercial : c'est pour ça qu'on l'utilise en classe.
CodeSignificationExemple avec l'API météo
200OK, voici les donnéesTout s'est bien passé, le JSON arrive.
400Requête mal forméeTu as écrit temperature_2 au lieu de temperature_2m.
404Adresse introuvableFaute dans l'endpoint, par exemple /v1/forcast.
429Trop de requêtesTon programme interroge le serveur beaucoup trop souvent.
500Erreur du serveurLe problème vient du serveur, pas de toi. On réessaie plus tard.

3Anatomie d'une requête

Avec Open-Meteo, toute la requête tient dans une adresse web. Chaque morceau a un rôle. Les couleurs sont les mêmes partout dans ce cours.

https://api.open-meteo.com/v1/forecast?latitude=50.26&longitude=4.91&current=temperature_2m,wind_speed_10m
  • https://Le protocole. Le s veut dire que la connexion est chiffrée (sécurisée).
  • api.open-meteo.comLe nom du serveur (le domaine). C'est « l'adresse de la friterie ».
  • /v1/forecastL'endpoint. forecast = prévisions. v1 = version 1 de l'API : si l'API change un jour, ton programme continue de marcher sur la v1.
  • ?Le point d'interrogation annonce le début des paramètres.
  • latitude=50.26Un paramètre : un nom, le signe =, une valeur. La latitude donne la position nord-sud. Attention : un point décimal, jamais une virgule.
  • &Le « et commercial » sépare deux paramètres.
  • longitude=4.91La position est-ouest. Dinant se trouve à 50,26° nord et 4,91° est.
  • current=temperature_2m,wind_speed_10mLes mesures « en ce moment » qu'on veut recevoir, séparées par des virgules. temperature_2m = la température de l'air à 2 mètres du sol.
Labo 1

4Construis ta requête et envoie-la

Choisis un lieu et les informations voulues. L'adresse se construit toute seule. Ouvre-la : ton navigateur devient le client, et tu vois la réponse brute du serveur.

① Le lieu
② La météo « maintenant » (paramètre current)
③ Les prévisions par jour (paramètre daily)

Ton URL de requête

Ouvrir la réponse ↗

Le lien s'ouvre dans un nouvel onglet. Firefox affiche le JSON dans un explorateur (avec un onglet pour voir les données brutes). Chrome l'affiche en texte, parfois avec une case pour le mettre en forme.

Ce que dit chaque paramètre

Ensuite : rapporte la réponse ici

  1. Dans l'onglet de la réponse, sélectionne tout le texte (Ctrl + A, ou l'onglet « données brutes » dans Firefox).
  2. Copie-le (Ctrl + C).
  3. Colle-le dans le Labo 2, plus bas (Ctrl + V). Il sera analysé tout de suite.

Bonus : une autre API te donne les coordonnées

Tu ne connais pas la latitude de ton village ? Open-Meteo propose une deuxième API, de géocodage : tu envoies un nom de lieu, elle renvoie ses coordonnées… en JSON. Colle ensuite la réponse dans le Labo 2 : un bouton te permettra de reprendre les coordonnées ici.

Chercher ↗

5Le JSON, la langue commune des API

JSON veut dire JavaScript Object Notation. C'est du texte tout simple, organisé avec quelques symboles. Un humain peut le lire, et surtout n'importe quel langage (JavaScript, Python, PHP, Java…) sait le transformer en données utilisables.

C'est pour ça que les API répondent en JSON plutôt qu'avec une page web : pas de couleurs, pas de mise en page, seulement les données, rangées de façon prévisible.

"clé" le nom d'une donnée "texte" string 11.8 nombre true / false booléen null vide { } objet [ ] tableau 
{
Objet : il commence par une accolade…
  "ville": "Dinant",
Clé : valeur. Ici la valeur est un texte, entre guillemets.
  "temperature": 11.8,
Nombre : sans guillemets, avec un point décimal.
  "jour": true,
Booléen : true (vrai) ou false (faux), sans guillemets.
  "maximums": [14.6, 13.1, 15.2],
Tableau : une liste entre crochets. Le premier élément porte le numéro 0.
  "vent": {
Un objet dans un objet : on peut imbriquer autant qu'on veut.
    "vitesse": 9.4,
    "direction": "SO"
Dernière paire : pas de virgule après.
  }
}
…et se termine par l'accolade fermante.

Les 5 règles d'or

  1. Les clés sont toujours entre guillemets doubles : "ville", jamais ville ni 'ville'.
  2. Les paires sont séparées par des virgules, mais pas de virgule après la dernière.
  3. Le texte est entre guillemets doubles. Les nombres et true/false/null n'en ont pas.
  4. { } pour un objet (des clés et des valeurs), [ ] pour un tableau (une liste).
  5. Chaque accolade ou crochet ouvert doit être refermé.

Aller chercher une valeur : le chemin

Une fois le JSON chargé dans une variable (on l'appelle souvent data), on descend dans la structure clé par clé, avec un point. Pour un tableau, on donne le numéro entre crochets.

data.ville→"Dinant"
data.vent.vitesse→9.4
data.maximums[0]→14.6le premier élément
data.maximums[2]→15.2le troisième
Labo 2

6Lis la réponse de l'API

Colle ici le JSON reçu au Labo 1. La page vérifie qu'il est valide, le déplie en arbre, et en fait une carte météo. Clique sur une valeur dans l'arbre pour voir le chemin qui y mène.

Exemple fictif pour Dinant, remplace-le par ta vraie réponse

Essaie de casser le JSON : enlève une virgule ou un guillemet, et regarde le message d'erreur.

L'arbre du JSON

    Chemin de la valeur sélectionnée

    Clique sur une valeur dans l'arbre.

    Labo 3

    7Fais l'appel avec du code

    Jusqu'ici, c'est toi qui copiais-collais. Un programme fait la même chose tout seul : il envoie la requête, reçoit le texte JSON, le transforme en objet et va chercher les valeurs avec leur chemin. Trois façons de le faire, de la plus rapide à la plus complète.

    1. Ouvre ta requête du Labo 1 dans un onglet (bouton « Ouvrir la réponse »).
    2. Dans cet onglet, ouvre les outils de développement avec F12, puis l'onglet Console.
    3. Tape les lignes ci-dessous. location.href contient l'adresse de l'onglet, donc ta requête.

    Chrome peut bloquer le collage dans la console la première fois : lis son message et tape la phrase demandée. Ou tape le code à la main, c'est encore mieux pour apprendre.

    8Défis

    Du plus simple au plus costaud. Note dans ton cahier l'URL que tu as utilisée pour chaque défi.

    ★☆☆

    La météo chez toi

    1. Avec le bonus du Labo 1 (géocodage), trouve la latitude et la longitude de ton village.
    2. Construis la requête météo pour ce lieu et ouvre-la.
    3. Dans le JSON, trouve la température et son unité. Où se trouve l'unité ?
    ★☆☆

    Provoque une erreur

    Dans ton URL, remplace temperature_2m par temperature_2 et ouvre-la. Quel code de statut reçois-tu ? Le serveur répond quand même en JSON : que contient la clé reason ? Colle cette réponse dans le Labo 2 pour voir.

    ★★☆

    Plus d'infos sur ta page

    Dans meteo.html, ajoute relative_humidity_2m et weather_code au paramètre current. Affiche l'humidité. Pour le code météo, l'API ne renvoie qu'un nombre (par exemple 3) : crée un objet JavaScript qui traduit les codes en français (0 = ciel dégagé, 3 = couvert, 61 = pluie faible…). La table complète est dans la documentation.

    ★★☆

    Les 3 prochains jours

    Demande daily=temperature_2m_max,temperature_2m_min. Les valeurs arrivent dans des tableaux : data.daily.time[0] est aujourd'hui, [1] demain… Utilise une boucle for pour afficher une ligne par jour.

    ★★★

    La météo sur l'écran de l'école

    Pour un écran de digital signage (Raspberry Pi), la page doit se mettre à jour toute seule. Appelle chargerMeteo() toutes les 15 minutes avec setInterval(chargerMeteo, 15 * 60 * 1000). Pourquoi pas toutes les secondes ? Regarde la valeur de current.interval dans le JSON (900 secondes), et pense au code 429.

    9Vérifie tes acquis

    Réponds dans ta tête ou sur papier, puis ouvre la réponse.

    Avec tes mots : à quoi sert une API ?

    À permettre à un programme (le client) de demander des données ou un service à un autre programme (le serveur), en suivant des règles décrites dans la documentation, sans avoir besoin de savoir comment le serveur fonctionne à l'intérieur.

    Dans https://api.open-meteo.com/v1/forecast?latitude=50.26&longitude=4.91, quel est l'endpoint ? Combien y a-t-il de paramètres ?

    L'endpoint est /v1/forecast. Il y a 2 paramètres, latitude et longitude. Le ? ouvre la liste des paramètres et le & les sépare.

    Dans l'exemple du Labo 2, quel chemin donne la température maximale de demain ?

    data.daily.temperature_2m_max[1]. L'index [0] correspond à aujourd'hui, donc demain est [1].

    Pourquoi l'API renvoie "weather_code": 3 et pas « Couvert » ?

    Un code numérique est le même dans toutes les langues et facile à traiter par un programme. C'est le client qui le traduit pour l'afficher, en français, en anglais ou avec une icône.

    Ce JSON est-il valide ? { "ville": "Dinant", "temp": 11.8, }

    Non : il y a une virgule après la dernière paire. Colle-le dans le Labo 2 pour voir le message d'erreur.

    Pourquoi les API répondent-elles en JSON plutôt qu'avec une page HTML ?

    Parce que le JSON ne contient que les données, rangées de façon structurée et prévisible. Il est léger, lisible par un humain, et tous les langages de programmation savent le lire. Une page HTML mélange les données avec la mise en page.

    À lire aussi