Vent, houle et marées
pour développeurs

Authentification & CORS

Chaque requête porte votre clé dans l’en-tête X-API-Key. Le paramètre ?apikey= est accepté aussi, mais il apparaît dans les journaux et l’historique : préférez l’en-tête.

curl --compressed -H "X-API-Key: votre_cle_ici" \
  "https://api.levent.live/api/all-buoys"

Un appel fetch depuis une page web envoie un en-tête Origin. Il n’est accepté que si cette origine (ex. https://www.monclub.fr) est enregistrée sur votre clé (allowedOrigins) : indiquez-nous vos domaines lors de la demande de clé. Les appels sans Origin (serveur, script, application mobile) ne sont pas concernés.

Les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After et ETag sont lisibles depuis JavaScript (Access-Control-Expose-Headers).

Demander une clé gratuite : contact@levent.live (usage prévu, volume estimé, domaines web éventuels).

Quickstart

Votre premier appel en 2 minutes. Les bibliothèques HTTP courantes (fetch, requests, URLSession) gèrent la compression automatiquement ; avec curl, ajoutez --compressed.

curl --compressed -H "X-API-Key: VOTRE_CLE" \
  "https://api.levent.live/api/stations-lite?near=48.38,-4.49&radius=20&online=1&fields=name,wind,gust,direction,ts,distanceKm"

# Bretagne : lat 47.2 → 48.9, lon -5 → -1, stations en ligne de Météo-France
curl --compressed -H "X-API-Key: VOTRE_CLE" \
  "https://api.levent.live/api/all-stations?source=meteofrance&bbox=47.2,-5,48.9,-1&online=true"

curl --compressed -H "X-API-Key: VOTRE_CLE" \
  "https://api.levent.live/api/all-stations?history=meteofrance_29075001&hours=24"

# Liste complète (~13 000 stations, ~0,5 Mo compressé) + ETag
curl --compressed -sD headers.txt -o stations.json -H "X-API-Key: VOTRE_CLE" \
  "https://api.levent.live/api/all-stations"
ETAG=$(grep -i '^etag:' headers.txt | cut -d' ' -f2- | tr -d '\r')

# 2 minutes plus tard : 304 Not Modified (corps vide) si la liste n’a pas changé
curl --compressed -s -o /dev/null -w "%{http_code}\n" -H "X-API-Key: VOTRE_CLE" \
  -H "If-None-Match: $ETAG" "https://api.levent.live/api/all-stations"

Conventions

• Identifiants : utilisez stableId (<source>_<id>, ex. meteofrance_29075001), unique dans toute l’API. Le champ id brut peut exister dans plusieurs sources (ex. 1475 chez Holfuy et chez Pioupiou).
• ts est l’heure de la mesure (UTC), pas l’heure de collecte ; il peut être null pour une station hors ligne. cachedAt est l’heure à laquelle Le Vent a reconstruit la liste.
• isOnline est évalué par chaque source (de 30 min à plusieurs heures pour les réseaux horaires ou tri-horaires) : pour un affichage « temps réel », vérifiez aussi l’âge de ts.
• Valeurs absentes : null pour les grandeurs facultatives (température, humidité, pression, altitude). Quand une source ne mesure pas les rafales (BoM, une partie des METAR / SYNOP), gust vaut wind ou 0.
• Nouvelles sources : la liste des valeurs de source s’allonge régulièrement. Traitez une valeur inconnue comme une source générique, sans erreur.
• Champs additionnels : de nouveaux champs facultatifs peuvent apparaître ; ignorez ceux que vous ne connaissez pas. Un champ existant ne change ni de nom ni d’unité dans la v1.

Stations vent

Toutes les stations vent avec leur dernière mesure, normalisées dans le schéma Station. La liste est reconstruite toutes les 2 minutes à partir de toutes les sources.

{
  "stations": [
    {
      "id": "29075001",
      "stableId": "meteofrance_29075001",
      "name": "Brest",
      "lat": 48.453833,
      "lon": -4.391167,
      "wind": 8.4,
      "gust": 11.9,
      "direction": 240,
      "source": "meteofrance",
      "ts": "2026-10-15T12:42:00.000Z",
      "isOnline": true,
      "temperature": 18.6,
      "humidity": 81,
      "pressure": 1021.9,
      "altitude": null
    },
    {
      "id": "10045",
      "stableId": "meteogalicia_10045",
      "name": "Mabegondo",
      "…": "…",
      "attribution": "Fonte: MeteoGalicia – Xunta de Galicia"
    }
  ],
  "count": 13189,
  "sources": { "meteofrance": 179, "holfuy": 1162, "netatmo": 2665, "kv-stations": 5582, "…": 0 },
  "cachedAt": "2026-10-15T12:51:07.636Z",
  "refreshInterval": 120
}

L’objet sources compte les stations par flux amont : kv-stations regroupe les services météo nationaux (MET Norway, AEMET, DWD, SYNOP…) et windguru / gowind-native restent à 0 (flux arrêtés). Pour un décompte par source, comptez le champ source des stations.

Sélection légère de stationsnouveau

Les mêmes stations que /api/all-stations, mais seulement celles qui vous intéressent, avec seulement les champs utiles. Idéal pour un tableau de bord, un écran TV, un widget ou un site de club. Les filtres se combinent ; au moins un des filtres ids, bbox, near, source ou since est requis.

curl --compressed -H "X-API-Key: VOTRE_CLE" \
  "https://api.levent.live/api/stations-lite?ids=meteofrance_29075001,holfuy_1062,pioupiou_110&fields=name,wind,gust,direction,ts,isOnline"

{
  "stations": [
    { "stableId": "meteofrance_29075001", "name": "Brest", "wind": 8.4, "gust": 11.9,
      "direction": 240, "ts": "2026-10-15T12:42:00.000Z", "isOnline": true },
    { "stableId": "holfuy_1062", "name": "Pilotage BREST", "wind": 7.6, "gust": 9.1,
      "direction": 235, "ts": "2026-10-15T12:45:00.000Z", "isOnline": true }
  ],
  "count": 2,
  "cachedAt": "2026-10-15T13:04:30.112Z",
  "refreshInterval": 120,
  "missing": ["pioupiou_110"]
}

Historique station

Les mesures récentes d’une station. La source est déduite du préfixe de l’identifiant. Le pas de temps dépend de la source (1 à 10 min pour la plupart des balises et services nationaux, 30 min à 3 h pour METAR / SYNOP).

{
  "stationId": "meteofrance_29075001",
  "name": "Brest",
  "source": "meteofrance",
  "hours": 24,
  "count": 240,
  "observations": [
    { "ts": "2026-10-15T10:54:00.000Z", "wind": 10.5, "gust": 14.8, "direction": 200, "temperature": null }
  ],
  "attribution": "…"
}

attribution n’est présent que pour les sources qui l’exigent. observations peut être vide (station sans historique, ou station ajoutée sans mesure, source custom). 502 si la source ne répond pas : réessayez plus tard.

Bouées houlographes

~470 bouées de 15 réseaux : CANDHIS (France), NOAA NDBC, Cefas, Rijkswaterstaat, Irish Lights, Marine Institute, ISPRA, Arpae, SMHI, FMI, Vegagerðin, MET Norway, IMOS / AODN, Queensland, South Island Waves. Rafraîchi toutes les 5 minutes.

{
  "buoys": [
    {
      "id": "01101",
      "name": "Leucate",
      "lat": 42.9167,
      "lon": 3.125,
      "region": "mediterranee",
      "depth": 40,
      "hm0": 0.2,
      "hmax": 0.3,
      "tp": 3.1,
      "direction": 18,
      "spread": 26,
      "seaTemp": 21.4,
      "status": "TOTALE",
      "lastUpdate": "2026-10-15T12:30:00.000Z",
      "source": "candhis",
      "attribution": null
    }
  ],
  "count": 470,
  "sources": { "candhis": 22, "ndbc": 190, "aodn": 61, "rws": 48, "…": 0 },
  "cachedAt": "2026-10-15T12:50:49.443Z",
  "refreshInterval": 300
}

Historique bouée

Environ 7 jours de mesures brutes (pas de 10 à 60 min selon le réseau). Les identifiants CANDHIS sont numériques (02911), les autres réseaux sont préfixés (ndbc_41002, rws_a12…).

{
  "buoyId": "rws_a12",
  "name": "A12",
  "source": "rws",
  "region": "Pays-Bas",
  "count": 1005,
  "observations": [
    { "timestamp": "2026-10-15T12:40:00.000Z", "hm0": 2.5, "hmax": null, "tp": 7.7, "direction": null, "seaTemp": null }
  ],
  "attribution": "Rijkswaterstaat — Waterinfo / WaterWebservices (CC0)"
}

Attention : l’horodatage des observations de bouées s’appelle timestamp (et non ts). Les grandeurs non mesurées par un réseau valent null.

Marées

Pleines et basses mers avec coefficients. Hors des ports français du SHOM, Le Vent calcule les marées de ~2 000 ports à partir de constantes harmoniques publiées (TICON-4, NOAA, Kartverket, modèle EOT20), ainsi qu’un coefficient « équivalent SHOM ».

# Port le plus proche de Plymouth (Royaume-Uni), 2 jours
curl --compressed -H "X-API-Key: VOTRE_CLE" \
  "https://api.levent.live/api/tide?lat=50.36&lon=-4.14&maxKm=50&scope=world&duration=2"

{
  "port": { "cst": "TC_DEVONPORT_DEV_GBR_BODC", "name": "Devonport", "lat": 50.3684, "lon": -4.1852,
            "region": "royaume-uni", "country": "GB", "countryName": "Royaume-Uni", "source": "TICON-4" },
  "distanceKm": 3.3,
  "tides": [
    { "type": "high", "date": "2026-10-15", "time": "08:48", "datetime": "2026-10-15T07:48:00.000Z",
      "height": 5.1, "coefficient": 73 },
    { "type": "low", "date": "2026-10-15", "time": "15:09", "datetime": "2026-10-15T14:09:00.000Z",
      "height": 1.44, "coefficient": null }
  ],
  "nextHighTide": { "time": "2026-10-15T20:03:00.000Z", "height": 4.85, "coefficient": 68 },
  "nextLowTide": { "time": "2026-10-15T14:09:00.000Z", "height": 1.44 },
  "todayCoefficient": 73,
  "coefficientSource": "computed",
  "coefficientReason": null,
  "coefficientNote": "Coefficient calculé par Le Vent (équivalent SHOM), non officiel",
  "source": "TICON-4",
  "sourceLabel": "Marées : TICON-4 (DGFI-TUM, CC BY 4.0) via Neaps — calcul Le Vent, ne pas utiliser pour la navigation",
  "model": false,
  "fallback": false,
  "datum": "LAT",
  "timezone": "Europe/London",
  "attribution": "Neaps tide database (…). Source: Hart-Davis, M., Dettmering, D., Seitz, F. (2025), TICON-4 (…). Licensed CC BY 4.0 (…)",
  "fetchedAt": "2026-10-15T12:53:34.846Z"
}

Prévisions

Prévisions horaires et quotidiennes (vent, météo, vagues) au format Open-Meteo, servies depuis le cache partagé de Le Vent. Les coordonnées sont arrondies à 0,01° (~1 km).

# Vent prévu à Brest (ECMWF), en nœuds, heures UTC, 2 jours
curl --compressed -H "X-API-Key: VOTRE_CLE" \
  "https://api.levent.live/api/forecast?model=ecmwf&latitude=48.38&longitude=-4.49&hourly=wind_speed_10m,wind_gusts_10m,wind_direction_10m&wind_speed_unit=kn&timezone=GMT&forecast_days=2"

Vent animé mondial (grilles)

Vent à 10 m prévu sur une grille mondiale, toutes les 3 h jusqu’à +120 h, pour animer une carte. Modèles : ecmwf (défaut, 0,25°), gfs (0,5°), icon_eu (0,125°, Europe). Endpoint public : pas de clé nécessaire.

Format binaire WWND v1 (little-endian, servi en gzip) : en-tête de 40 octets — "WWND", u16 version, u16 flags (bit 0 : 360°, bit 1 : canal vitesse), u16 nx, u16 ny, f32 lon0, f32 lat0, f32 dLon, f32 dLat, f32 scale (m/s par unité), u32 validTime, u32 runTime — puis Int16 u[nx·ny], Int16 v[nx·ny] (lignes du sud au nord, colonnes d’ouest en est, −32768 = manquant).

Les tuiles d’un run ne changent jamais (cache 7 jours) ; relisez l’index toutes les 10–30 min. Crédits : ECMWF (CC BY 4.0), NOAA GFS (domaine public), DWD ICON-EU.

Webcams

~700 webcams de spots (côtes et lacs) en ligne : tableau JSON d’objets id, name, location, region, latitude, longitude (attention : pas lat/lon), imageUrl, streamUrl (HLS ou lecteur YouTube, sinon null), source (exploitant), refreshInterval (s), lastCapture, et pour certaines provider, country, linkUrl, attribution.

Sources & fréquences

Valeur du champ source, nombre de stations (production, 15 octobre 2026) et fréquence à laquelle Le Vent relit la source. Le pas des mesures elles-mêmes va de 1 min (balises) à 3 h (SYNOP).

• windguru, gowind-native : sources désactivées (flux gowind.fr supprimé le 23 juin 2026), plus aucune station.
• custom : station ajoutée par Le Vent sans mesure (nom et position seulement, toujours hors ligne).
• En cours d’intégration, peuvent apparaître : metoffice (Royaume-Uni), italia (réseaux publics italiens), asia (Japon, Hong Kong, Singapour, Taïwan), eccc (Canada), ccomet (côtes anglaises), inmet (Brésil).

Licences & crédits

Les mesures appartiennent à leurs producteurs. Le Vent les collecte, convertit (unités, arrondis, UTC) et regroupe ; ce ne sont pas des produits officiels de ces organismes. En utilisant l’API, vous vous engagez à :

• Afficher le champ attribution quand il est présent (stations, historiques, bouées, marées) : c’est la mention exigée par la licence de la source (CC BY 4.0, NLOD, etc.).
• Citer la source et Le Vent partout où les données sont affichées, par ex. « Données : MET Norway via Le Vent (levent.live) ».
• Respecter les réseaux privés et communautaires (Netatmo, Weathercloud, Holfuy, Pioupiou / OpenWindMap, kwind, Wind France, Diabox, Weameter, Fildair, Infoclimat, APRS) : sauf licence ouverte publiée par le réseau lui-même (vérifiez ses conditions), leurs données ne sont pas en libre réutilisation. Usage personnel, associatif ou d’affichage uniquement ; pas de revente, d’archivage massif ni de redistribution en flux sans accord du réseau.
• Ne pas présenter ces mesures, marées ou prévisions comme des données de sécurité ou de navigation.

Crédits complets des bouées et des marées (TICON-4, NOAA, Kartverket, EOT20, Neaps) : page Sources.

Schéma des objets

Codes de réponse

Les erreurs sont du JSON : { "error": "…" }, parfois avec hint.

Limites, cache & bonnes pratiques

Chaque clé a une limite par minute (120 par défaut), comptée sur des fenêtres fixes d’une minute. Chaque réponse indique X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes avant la remise à zéro). Au-delà : 429 avec Retry-After. Les réponses 304 comptent comme des requêtes, mais ne coûtent presque rien.

• Acceptez la compression (Accept-Encoding: br, gzip, automatique sauf avec curl sans --compressed) : 8 fois moins de données.
• Ne téléchargez pas les 13 000 stations pour en afficher quelques-unes : /api/stations-lite avec ids, near ou bbox, et fields.
• Pour un site public, interrogez l’API depuis votre serveur et servez vos visiteurs depuis votre cache : une requête toutes les 2 minutes suffit, quel que soit votre trafic.
• Gérez 429 (attendre Retry-After) et 5xx (réessayer avec un délai croissant) ; gardez la dernière réponse valide en cas d’erreur.

Exemples complets

// Tableau de bord : quelques stations rafraîchies toutes les 2 minutes, avec ETag
const API = "https://api.levent.live/api";
const KEY = "VOTRE_CLE"; // côté serveur, ou clé limitée à vos origines
const ids = ["meteofrance_29075001", "holfuy_1062", "pioupiou_1475"];
let etag = null;
let stations = [];

async function refresh() {
  const res = await fetch(`${API}/stations-lite?ids=${ids.join(",")}&fields=name,wind,gust,direction,ts,isOnline`, {
    headers: { "X-API-Key": KEY, ...(etag ? { "If-None-Match": etag } : {}) },
  });
  if (res.status === 304) return;                 // rien de nouveau
  if (res.status === 429) {                       // limite atteinte : attendre
    const wait = Number(res.headers.get("Retry-After") || 60);
    return new Promise(r => setTimeout(r, wait * 1000));
  }
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  etag = res.headers.get("ETag");
  const data = await res.json();
  stations = data.stations;
  if (data.missing?.length) console.warn("Stations introuvables :", data.missing);
  for (const s of stations) {
    const age = Math.round((Date.now() - Date.parse(s.ts)) / 60000);
    console.log(`${s.name} : ${s.wind} nds (${s.gust}) ${s.direction}° — il y a ${age} min`);
  }
}

await refresh();
setInterval(() => refresh().catch(console.error), 120_000);

import csv
import requests

API = "https://api.levent.live/api"
r = requests.get(
    f"{API}/all-stations",
    headers={"X-API-Key": "VOTRE_CLE"},
    params={"history": "meteofrance_29075001", "hours": 24},
    timeout=30,
)
r.raise_for_status()
data = r.json()

with open("historique.csv", "w", newline="") as f:
    w = csv.writer(f)
    w.writerow(["ts_utc", "vent_nds", "rafales_nds", "direction_deg", "temperature_c"])
    for o in data["observations"]:
        w.writerow([o["ts"], o["wind"], o["gust"], o["direction"], o["temperature"]])

print(f"{data['name']} : {data['count']} relevés sur {data['hours']} h → historique.csv")

curl --compressed -H "X-API-Key: VOTRE_CLE" \
  "https://api.levent.live/api/all-buoys?region=mediterranee"

Changelog