KANO

Le service KANO permet d'accéder aux données (sites, réseaux de mesures et prévisions météorolgoiques) stockées dans le système de base de données MongoDB de façon unifiée en JSON via l'API de l'application Kano.

Cette API est notamment utilisée par le client de l'application Kano pour la visualisation temps-réel de l'ensemble des données.

Jeux de données exposés

SitesEURDEPZones sous influenceVigicruesTelérayOpenRadiationICOSRTEHydrométrie Hub'EauRadomeSemenceZones sous le ventArpègeAromeGFS

Utilisation

Attention

Les volumes de données manipulés via le service pouvant être volumineux il est fortement recommandé de filtrer ces données de façon temporelle et spatiale dans des plages de temps et des zones de taille limitée.

Le service propose en général une limite dans le nombre de résultats par défaut pour éviter une surcharge trop importante.

L'URL de base pour accéder au service est https://api.planet._DOMAIN_/kano, la méthode d'accès présentée ici se limite au protocole HTTP standard. Il existe également un accès via Websocket pour des performances optimales qui est explicité dans la documentation du kit de développement KDK.

Note

Pour plus de lisibilité dans les exemples présentées ici les URL ne sont pas encodées mais il peut être nécessaire de le faire suivant le type de client utilisé.

Les capacités de requêtage et la structure des données transitant via l'API étant détaillées dans la documentation du kit de développement KDK, nous présentons ici des exemples de requêtes types.

Sites nucléaires

Les sites sur lesquels sont archivés les prévisions météorologiques sont stockés dans la collection/service nuclear-sites.

Ci-après quelques exemples de requêtes :

• lister tous les sites

HTTP - GET

https://api.planet._DOMAIN_/kano/nuclear-sites?jwt=_TOKEN_

• lister les sites en France :

HTTP - GET

https://api.planet._DOMAIN_/kano/nuclear-sites?properties.id_country=14&jwt=_TOKEN_

Zones sous influence

Les zones sous influence sont stockés dans la collection/service zi.

Ci-après quelques exemples de requêtes :

• lister toutes les zones à 5 Kms (possible aussi pour 10 Kms)

HTTP - GET

https://api.planet._DOMAIN_/kano/zi?properties.BUFF_DIST=5000&jwt=_TOKEN_

• lister les zones contenant une localisation (peut se combiner avec le filtrage par distance) :

HTTP - GET

https://api.planet._DOMAIN_/kano/zi?longitude=2.96082&latitude=47.54108&jwt=_TOKEN_

Réseaux de mesures

En général, pour chaque réseau de mesures deux points d'entrées sont exposés par le service et permettent de récupérer:

• la liste des stations de mesure sur le réseau,
• les observations (i.e. mesures) réalisées par les stations au cours du temps sur le réseau.

Par exemple, les données hydrométriques Hub'eau disposent de ces deux points d'entrée:

• hubeau-hydro-stations pour les stations,
• hubeau-hydro-observations pour les observations.

Ces deux points d'entrée donnent accès aux deux collections stockant in-fine les données.

Stations avec filtrage spatial

Récupération de la liste des stations dans une zone donnée (i.e. boîte englobante):

HTTP - GET

https://api.planet._DOMAIN_/kano/hubeau-hydro-stations?south=44.96479793033104&north=45.02695045318546&west=-0.17578125&east=-0.087890625&jwt=_TOKEN_

Mesures avec filtrage spatial/temporel

Récupération des mesures brutes dans une plage de temps et une zone donnée (i.e. boîte englobante) avec les plus récentes en premier:

HTTP - GET

https://api.planet._DOMAIN_/kano/hubeau-hydro-observations?south=44.96479793033104&north=45.02695045318546&west=-0.17578125&east=-0.087890625&time[$gte]=start_time&time[$lte]=end_time&$sort[time]=-1&jwt=_TOKEN_

Voir un exemple de résultat

{
  "type": "FeatureCollection",
  "features": [
    {
      "_id": "5f23ce6071b0b00008dff53f",
      "type": "Feature",
      "time": "2020-07-31T07:30:00.000Z",
      "geometry": {
          "type": "Point",
          "coordinates": [
              -0.12606156299146137,
              45.02191991211479
          ]
      },
      "properties": {
          "name": "L'Isle à Abzac",
          "code_station": "#P726151001",
          "H": 0.397
      }
    },
    {
      "_id": "5f23caea71b0b00008dfe457",
      "type": "Feature",
      "time": "2020-07-31T07:25:00.000Z",
      "geometry": {
          "type": "Point",
          "coordinates": [
              -0.12606156299146137,
              45.02191991211479
          ]
      },
      "properties": {
          "name": "L'Isle à Abzac",
          "code_station": "#P726151001",
          "H": 0.398
      }
    },
    ...
  ]
}

Série temporelle sur une station

Récupération des mesures agrégées sur une station et une plage de temps données:

HTTP - GET

https://api.planet._DOMAIN_/kano/hubeau-hydro-observations?$groupBy=code_station&$aggregate[0]=H&$aggregate[1]=Q&properties.code_station=#X331001001&time[$gte]=start_time&time[$lte]=end_time&jwt=_TOKEN_

Voir un exemple de résultat

{
  "type": "FeatureCollection",
  "features": [
    {
      "_id": {
        "code_station": "#X331001001"
      },
      "time": {
        "H": [
          "2020-07-29T13:40:00.000Z",
          "2020-07-29T13:45:00.000Z",
          "2020-07-29T13:50:00.000Z",
          ...
        ],
        "Q": [
          "2020-07-29T13:40:00.000Z",
          "2020-07-29T13:45:00.000Z",
          "2020-07-29T13:50:00.000Z",
          ...
        ]
      },
      "type": "Feature",
      "properties": {
        "name": "La Durance à Cavaillon",
        "code_station": "#X331001001",
        "H": [
          0.815,
          0.815,
          0.821,
          ...
        ],
        "Q": [
          36.87,
          36.87,
          37.458,
          ...
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          5.032432216493836,
          43.82748690979179
        ]
      }
    }
  ]
}

Dernières mesures sur une station

Récupération des mesures les plus récentes sur une station par rapport à une horodate donnée:

HTTP - GET

https://api.planet._DOMAIN_/kano/hubeau-hydro-observations?$groupBy=code_station&$aggregate[0]=H&$aggregate[1]=Q&properties.code_station=%23K447001001&time[$lte]=end_time&$limit=1&$sort[time]=-1&jwt=_TOKEN_

Voir un exemple de résultat

{
  "type": "FeatureCollection",
  "features": [
    {
      "_id": "64917e8ec06fb0000887fd3a",
      "geometry": {
        "coordinates": [
          1.3351479476905552,
          47.584957074484784
        ],
        "type": "Point"
      },
      "properties": {
        "H": -0.84,
        "Q": 127,
        "code_station": "#K447001001",
        "name": "La Loire à Blois"
      },
      "time": {
        "H": "2023-06-20T09:20:00.000Z",
        "Q": "2023-06-20T09:20:00.000Z"
      },
      "type": "Feature"
    }
  ]
}

Le fonctionnement est similaire pour tous les points d'entrée:

• Téléray
  • https://api.planet._DOMAIN_/kano/teleray-sensors: accès à la localisation des sondes
  • https://api.planet._DOMAIN_/kano/teleray-measures: accès au débit de dose gamma ambiant
• ICOS
  • https://api.planet._DOMAIN_/kano/icos-stations: accès à la localisation des stations
  • https://api.planet._DOMAIN_/kano/icos-observations: accès à la concentration atmosphérique
• RTE
  • https://api.planet._DOMAIN_/kano/rte-units: accès à la localisation des unités de production
  • https://api.planet._DOMAIN_/kano/rte-generation: accès à la puissance injectée
• Hub'eau
  • https://api.planet._DOMAIN_/kano/hubeau-hydro-stations: accès à la localisation des sondes
  • https://api.planet._DOMAIN_/kano/hubeau-hydro-observations: accès au niveau et débit d'eau
• Observations Radome
  • https://api.planet._DOMAIN_/kano/radome-stations: accès à la localisation des stations
  • https://api.planet._DOMAIN_/kano/radome-observations: accès au paramètres météorologiques mesurés (vent, précipitations, température, ...)
• Observations Semence
  • https://api.planet._DOMAIN_/kano/semence-stations: accès à la localisation des stations
  • https://api.planet._DOMAIN_/kano/semence-observations: accès au paramètres météorologiques mesurés (vent, précipitations, température, ...)
• Vigicrues
  • https://api.planet._DOMAIN_/kano/vigicrues-sections: accès aux tronçons (considérés comme des "stations")
  • https://api.planet._DOMAIN_/kano/vigicrues-forecasts: accès au niveau de vigilance (considéré comme une "mesure" sur les tronçons)

Les réseaux suivants ne disposent que d'un seul point d'entrée (soit parce qu'il n'existe pas de stations fixes, soit parce que la géométrie associée aux stations varie au fil du temps), il convient donc de le traiter comme celui fournissant des mesures dans le fonctionnement présenté précedemment:

• OpenRadiation
  • https://api.planet._DOMAIN_/kano/openradiation: accès aux mesures
• Zones sous le vent
  • https://api.planet._DOMAIN_/kano/zsv: accès à la géométrie des zones

Prévisions météorologiques

Les capacités de requêtage et la structure des données transitant via l'API étant détaillés dans la documentation de Weacast, nous présentons ici des exemples de requêtes types.

Pour chaque modèle un point d'entrée différent est exposé par le service pour chaque élément météorologique selon la nomenclature suivante: https://api.planet._DOMAIN_/kano/modele/element.

Les modèles disponibles sont les suivants :

• gfs-world modèle GFS (couverture mondiale),
• arpege-world modèle ARPEGE (couverture mondiale),
• arpege-europe modèle ARPEGE (couverture europe),
• arome-france modèle AROME (couverture france),

Les éléments disponibles sont les suivants :

• u-wind composante horizontale du vent à 10m en m/s,
• u-wind composante verticale du vent à 10m en m/s,
• gust rafales à 2m en m/s,
• temperature température à 2m en °C,
• precipitations: précipitations cumulées au sol sur 3h en mm/h.

Récupération des prévisions disponibles sur un élément météorologique:

HTTP - GET

https://api.planet._DOMAIN_/kano/gfs-world/temperature?$paginate=false&jwt=_TOKEN_

Récupération des données brutes de la prévision la plus proche d'un temps donné sur un élément météorologique :

HTTP - GET

https://api.planet._DOMAIN_/kano/gfs-world/temperature?time=requested_time&$select[0]=forecastTime&$select[1]=data&$paginate=false&jwt=_TOKEN_

Voir un exemple de résultat

[
  {
    "_id": "5f244266503264000760e8cc",
    "data": [
      0.75,
      0.76,
      0.75,
      ...
    ]
  }
]

Rééchantillonnage des données de prévisions la plus proche d'un temps donné sur un élément météorologique et selon une grille donnée:

HTTP - GET

https://api.planet._DOMAIN_/kano/gfs-world/temperature?time=requested_time&$select[0]=forecastTime&$select[1]=data&oLon=0&oLat=90&sLon=360&sLat=180&dLon=1&dLat=1&$paginate=false&jwt=_TOKEN_

Voir un exemple de résultat

Résultat similaire à la récupération des données brutes (voir ci-dessus).

Sonde virtuelle pour obtenir la valeur des différents éléments météorologique d'un modèle à un endroit précis pour un temps de prévision donné:

HTTP - POST

https://api.planet._DOMAIN_/kano/probes?forecastTime=requested_time&jwt=_TOKEN_

Corps de requête:

{
  "type": "FeatureCollection",
  "forecast": "gfs-world",
  "elements": [
    "u-wind",
    "v-wind",
    "gust",
    "precipitations",
    "temperature"
  ],
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          144, // longitude
          -5 // latitude
        ]
      }
    }
  ]
}

Exemple de requête complète via curl:

curl --location --request POST 'https://api.planet._DOMAIN_/kano/probes?forecastTime=2020-08-25T15:00:00.000Z&jwt=_TOKEN_' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "FeatureCollection",
  "forecast": "gfs-world",
  "elements": ["u-wind", "v-wind", "gust", "precipitations", "temperature"],
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          144,
          -5
        ]
      }
    }
  ]
}'

Voir un exemple de résultat

{
  "forecast": "gfs-world",
  "elements": [
    "u-wind",
    "v-wind",
    "gust",
    "precipitations",
    "temperature"
  ],
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "u-wind": 0.09015593469751969,
        "v-wind": 0.3240957476654408,
        "windSpeed": 0.33640176309883474,
        "windDirection": 195.54533614476094,
        "gust": 1.2910775125678953,
        "precipitations": 0,
        "temperature": 12.1190555304198
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          144,
          -5
        ]
      },
      "forecastTime": "2020-08-25T15:00:00.000Z",
      "runTime": "2020-08-25T06:00:00.000Z"
    }
  ]
}

La requête peut également cibler une plage de temps, dans ce cas il est nécessaire de requêter les données en mode tuilé et de spécifier un opérateur géospatial pour ne cibler que les tuiles utiles à la position donnée.

Sonde virtuelle pour obtenir une série temporelle des différents éléments météorologique d'un modèle de prévision à un endroit précis:

HTTP - POST

https://api.planet._DOMAIN_/kano/probes?forecastTime[$gte]=start_time&forecastTime[$lte]=end_time&geometry[$geoIntersects][$geometry][type]=Point&geometry[$geoIntersects][$geometry][coordinates][]=longitude&geometry[$geoIntersects][$geometry][coordinates][]=latitude&jwt=_TOKEN_

Exemple de requête complète via curl:

curl --location --request POST "https://api.planet._DOMAIN_/kano/probes?forecastTime[%24gte]=2020-08-25T15:00:00.000Z&forecastTime[%24lte]=2020-08-26T15:00:00.000Z&geometry[%24geoIntersects][%24geometry][type]=Point&geometry[%24geoIntersects][%24geometry][coordinates][]=144&geometry[%24geoIntersects][%24geometry][coordinates][]=-5&jwt=_TOKEN_" \
--header 'Content-Type: application/json' \
--data-raw '{
  "forecast": "gfs-world",
  "elements": ["u-wind", "v-wind", "gust", "precipitations", "temperature"]
}'

Voir un exemple de résultat

{
  "forecast": "gfs-world",
  "elements": [
    "u-wind",
    "v-wind",
    "gust",
    "precipitations",
    "temperature"
  ],
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "u-wind": [
          -1.8405222188626973,
          0.898255421022245,
          2.522106150100827,
          ...
        ],
        "v-wind": [
          -0.21596040469943223,
          -0.23335731045001024,
          0.5032832630028146,
          ...
        ],
        "windSpeed": [
          1.8531489240007692,
          0.928072430221,
          2.5718307633270068,
          ...
        ],
        "windDirection": [
          83.30771555723719,
          284.562917569009,
          258.71492707605455,
          ...
        ],
        "gust": [
          5.140581665028293,
          1.8914130131458202,
          3.5863549574491955,
          ...
        ],
        "precipitations": [
          0.006506147071023607,
          0.0032530735355118033,
          0,
          ...
        ],
        "temperature": [
          29.3663427263156,
          29.445523744579937,
          28.389477190184678,
          ...
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          15.952148437500002,
          41.73852846935917
        ]
      },
      "forecastTime": {
        "u-wind": [
          "2020-07-31T15:00:00.000Z",
          "2020-07-31T18:00:00.000Z",
          "2020-07-31T21:00:00.000Z",
          ...
        ],
        "v-wind": [
          "2020-07-31T15:00:00.000Z",
          "2020-07-31T18:00:00.000Z",
          "2020-07-31T21:00:00.000Z",
          ...
        ],
        "windSpeed": [
          "2020-07-31T15:00:00.000Z",
          "2020-07-31T18:00:00.000Z",
          "2020-07-31T21:00:00.000Z",
          ...
        ],
        "windDirection": [
          "2020-07-31T15:00:00.000Z",
          "2020-07-31T18:00:00.000Z",
          "2020-07-31T21:00:00.000Z",
          ...
        ],
        "gust": [
          "2020-07-31T15:00:00.000Z",
          "2020-07-31T18:00:00.000Z",
          "2020-07-31T21:00:00.000Z",
          ...
        ],
        "precipitations": [
          "2020-07-31T15:00:00.000Z",
          "2020-07-31T18:00:00.000Z",
          "2020-07-31T21:00:00.000Z",
          ...
        ],
        "temperature": [
          "2020-07-31T15:00:00.000Z",
          "2020-07-31T18:00:00.000Z",
          "2020-07-31T21:00:00.000Z",
          ...
        ]
      },
      "runTime": {
        "u-wind": [
          "2020-07-31T06:00:00.000Z",
          "2020-07-31T06:00:00.000Z",
          "2020-07-31T06:00:00.000Z",
          ...
        ],
        "v-wind": [
          "2020-07-31T06:00:00.000Z",
          "2020-07-31T06:00:00.000Z",
          "2020-07-31T06:00:00.000Z",
          ...
        ],
        "gust": [
          "2020-07-31T06:00:00.000Z",
          "2020-07-31T06:00:00.000Z",
          "2020-07-31T06:00:00.000Z",
          ...
        ],
        "precipitations": [
          "2020-07-31T06:00:00.000Z",
          "2020-07-31T06:00:00.000Z",
          "2020-07-31T06:00:00.000Z",
          ...
        ],
        "temperature": [
          "2020-07-31T06:00:00.000Z",
          "2020-07-31T06:00:00.000Z",
          "2020-07-31T06:00:00.000Z",
          ...
        ]
      }
    }
  ]
}

Note

Des éléments dérivés sont automatiquement calculés à partir des composantes du vent pour simplifier l'interprétation des données:

• windSpeed vitesse du vent à 10m en m/s,
• windDirection direction du vent à 10m en °.