Téléchargement des données

La diffusion des données marégraphiques coordonnées par REFMAR est assurée sur data.shom, le portail des données maritimes de référence.

Comment télécharger les données marégraphiques REFMAR mises à disposition sur data.shom ?

Pour télécharger les mesures du niveau de la mer coordonnées par REFMAR et mises à disposition sur data.shom.fr deux autres offres distinctes sont offertes :

  • Téléchargement "direct" ou "manuel". Ce mode de diffusion vous propose une fenêtre simple de paramétrage des données à télécharger (sources, dates, format d’export…) et fournit directement un fichier à télécharger au format « .zip » contenant le fichier de métadonnées du site et le fichier de données
  • Abonnement aux flux (mode expert). Ce mode de collecte permet à un utilisateur d’interroger et télécharger des données ou informations sur un observatoire par requêtes HTTP. Ce mode permet de s'affranchir de l'interface web data.shom.fr

 

Page d'un marégraphe REFMAR sur data.shom avec les boutons permettant de s'abonner aux flux ou de télécharger les données.

 

 

Accès aux données marégraphiques diffusées sur data.shom.fr

Le téléchargement "manuel" ou "direct" permet simplement et rapidement d'obtenir les mesures du niveau de la mer. Ce mode de diffusion vous propose une fenêtre simple de paramétrage des données à télécharger (sources, dates, format d’export…) avant de recevoir par mail un lien de téléchargement pour récupérer l’archive au format *.zip contenant le fichier de métadonnées du site et le fichier de données. Il est possible de télécharger, pour des paramètres identiques, les données d’un ou plusieurs marégraphes à la fois. Attention, l’option « Télécharger toutes les données disponibles » est limitée à un seul site à la fois. Le page de configuration du téléchargement est commune à tous les marégraphes, elle est accessible directement à cette adresse : https://data.shom.fr/donnees/refmar/download.

Depuis chaque page d'une station, vous avez la possibilité de télécharger, sous la forme d'un fichier, l'ensemble ou une partie des observations du niveau de la mer.

 

Étape 1 : Choix du - des mesures de hauteurs d'eau que vous souhaitez télécharger

Sélectionnez d’abord votre/vos marégraphe/s dans l’interface (label 1). Il est possible de les rechercher directement, soit par leur nom, soit par leur identifiant depuis la barre de recherche en haut à droite du tableau des marégraphes (label 2). Aussi, pour vous aider dans votre sélection, les dates de début et de fin des périodes disponibles sont indiquées pour chaque source ou type de données. Pour toutes les afficher, cliquez sur le bouton + en début de ligne (label 3). Enfin cochez les marégraphes dont vous souhaitez recevoir les données (label 4). 

Capture d'écran de la page de téléchargement des données marégraphiques sur data.shom

 

Étape 2 : Paramétrez votre demande

Sous le tableau de sélection des marégraphes, paramétrez votre demande de téléchargement. Cochez la case en label 1 si vous souhaitez télécharger toutes les données pour le marégraphe sélectionné. La configuration des dates de début et de fin n’est alors plus nécessaire. Vous devez toute de même choisir votre format de sortie et le type d’observation souhaité. Choisissez les dates de début (label 2) et de fin (label 3) et le format de sortie souhaité (label 4). Enfin, choisissez le type d’observation (label 5) : brutes haute fréquence, brutes temps différé, validées temps différé, validées horaires, brutes horaires ou pleines et basses mer (uniquement pour Brest. À venir).

Capture d'écran de la page de téléchargement des données marégraphiques sur data.shom

 

Étape 3 : Renseigner vos coordonnées

Renseignez ensuite votre nom et votre adresse mail (label 6). Vous avez la possibilité de vous inscrire à la lettre d’informations de l’équipe REFMAR en cochant la case dédiée (label 7). Cliquez sur "Générer l’archive" (label 8) pour valider votre commande. Si tout s’est bien passé un message de Succès s’affiche.

 

Étape 4 : Récupération des données dans un dossier zippé

Vous recevez alors, dans un délai plus ou moins bref selon la quantité de données à préparer, un mail contenant le lien de téléchargement du dossier zippé maregraphie.zip.

 

Contenu du dossier zippé

Le dossier zippé contient :

Un fichier ID-DU-MAREGRAPHE.sml contenant l'ensemble des informations utiles sur l'observatoire marégraphique. Le descriptif du fichier *.sml fait l'objet d'une page Internet spécifique explicative.
Un fichier de données dans le format choisi. Les différents formats sont également détaillés dans des pages Internet spécifiques. A noter que les données sont toujours fournies en UTC.

Le téléchargement "automatique" ou "par flux" permet d'obtenir automatiquement les mesures du niveau de la mer après paramétrage. Ce système permet à un utilisateur d’interroger et de collecter des données des marégraphes par requêtes. Attention le téléchargement par flux des observations est limité à 31 jours.

 

Fonctionnement

Depuis chaque page d'une station, vous pouvez demander l'URL du service. L'URL est identique pour tous les marégraphes. C'est en paramétrant la requête envoyée au service qu'on interroge différentes stations.

 

Étape 1 : Renseignez les champs demandés dans la nouvelle fenêtre ouverte

Dans la nouvelle fenêtre qui s'ouvre après avoir cliquer sur le bouton "S'abonner aux flux", renseignez votre nom (1), ainsi que votre adresse mail (2) et cochez la case (3) si vous souhaitez recevoir des informations de la part de l’équipe REFMAR. Cliquez sur "Envoyer le lien" (4).

Capture d'écran de la page de téléchargement des données marégraphiques par flux sur data.shom

 

Une fois reçue l'URL du serveur à l'adresse mail renseignée, il est possible d’exécuter des requêtes par différents moyens : o collecte par un éditeur de requêtes GET ou POST dans son navigateur Internet ; o collecte par script. Le flux est disponible à l’adresse suivante : https://services.data.shom.fr/maregraphie/service/help Les données sont disponibles sous formes XML (POX), JSON ou TXT.

 

Étape 2 : Paramétrage de la collecte

Une fois reçue l'URL du serveur à l'adresse mail renseignée l’URL, il est possible d’exécuter des requêtes http par différents moyens :

  • Collecte par l'interface du serveur
  • Collecte par un éditeur de requêtes POST dans son navigateur Internet
  • Collecte par script

l'URL du service est https://services.data.shom.fr/maregraphie/sos/service pour obtenir les données sous formes XML (POX) ou JSON. Pour obtenir le format TXT, l'URL est http://services.data.shom.fr/fast-sos/service/txt

 

Requête GET

Une requête de type GET est une URL qui s’exécute directement dans la barre d’adresse de son navigateur. Ex : https://services.data.shom.fr/maregraphie/observation/json/3?sources=1&dtStart=2024-01-01&dtEnd=2024-01-10

 

Requête POST

Une requête POST est une requête qui envoie elle-même de la donnée. Pour l’exécuter dans son navigateur il faut installer un module complémentaire comme RESTClient ou Postman.

Ces requêtes sont composées d’un site cible ou url cible, d’un en-tête ou header et d’un corps de requête ou body.

Pour la suite de la description des requêtes en POST, le module utilisé est «Postman». Comme pour la plupart des modules existants, il est également possible de l’utiliser pour des requêtes de type GET.

 

Requête GetCapabilities (GET)

La requête GetCapabilities fournit l’ensemble des fonctions et des paramètres disponibles par marégraphes (quelles sources, périodes de disponibilité, position du marégraphe…).

Cette requête n’est disponible qu’en GET : https://services.data.shom.fr/maregraphie/sos/service?request=GetCapabilities

 

Requête DescribeSensor (POST)

La requête DescribeSensor permet de demander des informations d’un marégraphe (ici celui de Roscoff dont l'identifiant est 54). Une page spéciale du site refmar.shom.fr rassemble pour chaque marégraphe l'identifiant qui lui est attribué. Le paramétrage du marégraphe s’effectue sur la ligne "procedure". L’URL sera celle fournie par le GetCapabilities.

 

URL : https://services.data.shom.fr/maregraphie/sos/service

Header : Content-Type: application/json

Body :

    {

    "request": "DescribeSensor",

    "service": "SOS",

    "version": "2.0.0",

    "procedure": "https://shom.fr/maregraphie/procedure/54",

    "procedureDescriptionFormat": "http://www.opengis.net/sensorML/1.0.1"

     }

 

Requête GetObservation (GET ou POST)

Cette requête permet d’extraire les données du marégraphe interrogé. Il est possible de faire des requêtes GetObservation en GET (3 formats disponibles) ou POST (JSON et XMl en sortie uniquement). Attention le téléchargement par flux des observations est limité à 31 jours par requête. Dans cet exemple, toutes les données (WaterHeight/0) de l'observatoire marégraphique de Toulon (identifiant 68), du 15/01/2014 à 00h00 au 17/01/2014 à 23h59min59sec. Le Z correspond à l'heure Zoulou (= UTC = TU + 0h).

Cette requête permet d’extraire des données de l'observatoire marégraphique de Toulon (identifiant 68), du 15/01/2014 à 00h00 au 17/02/2014 à 23h59min59sec. Le Z correspond à l'heure Zoulou (= UTC = TU + 0h).

 

En GET (tous formats) :

https://services.data.shom.fr/maregraphie/observation/json/68?sources=0&dtStart=2014-01-15T00:00:00Z&dtEnd=2014-02-17T23:59:59Z

  • Format, choisissez le format de sortie : json, pox (xml) ou txt
  • Identifiant du marégraphe
  • Source(s) demandée(s) "observedProperty" permet de choisir le type de hauteur d’eau, parmi les différents types d’enregistrements : 1 : Brutes Haute fréquence ; 2 : Brutes temps différé ; 3 : Validées temps différé ; 4 : Validées horaires ; 0 : Toutes les sources disponibles sur la période demandée ; Il est aussi possible d’en demander plusieurs en les séparant par des virgules : 3,4
  • dtStart et dtEnd permettent de préciser les bornes temporelles entre lesquelles vous souhaitez récupérer les données. Le format "2015-01-15T00:00:00+00:00", correspond à : [année]-[mois]-[jour]T[heure]:[minutes]:[secondes][système horaire ici UTC] 

 

En POST, format JSON :

 

URL : https://services.data.shom.fr/maregraphie/sos/service

Header : Content-Type: application/json

Body :  

{

 "request": "GetObservation",

 "procedure": ["https://shom.fr/maregraphie/procedure/68"],

 "observedProperty": ["https://shom.fr/maregraphie/observedProperty/WaterHeight/0"],

 "temporalFilter": [{

   "during": {

     "ref": "om:phenomenonTime",

     "value": [

       "2014-01-15T00:00:00Z",

       "2015-02-17T23:59:59Z"

     ]

   }

 }

]

}

 

  • "procedure" = identifiant du marégraphe
  • "observedProperty" permet de choisir le type de hauteur d’eau, parmi les différents types d’enregistrements : WaterHeight/1 : Brutes Haute fréquence ; WaterHeight/2 : Brutes temps différé ; WaterHeight/3 : Validées temps différé ;
    WaterHeight/4 : Validées horaires ; WaterHeight/0 : Toutes les sources disponibles sur la période demandée


    Il est aussi possible d’en demander plusieurs en séparant les url par des virgules: "observedProperty": ["https://shom.fr/maregraphie/observedProperty/WaterHeight/4", "https://shom.fr/maregraphie/observedProperty/WaterHeight/3"]

  • "temporalFilter", permet de préciser les bornes temporelles entre lesquelles vous souhaitez récupérer les données. Le format "2015-01-15T00:00:00+00:00", correspond à : [année]-[mois]-[jour]T[heure]:[minutes]:[secondes][système horaire ici UTC]
  •  
EN POST, format XML:

 

URL : https://services.data.shom.fr/maregraphie/sos/service

Header : Content-Type: application/xml

Body :

<GetObservation

xmlns="http://www.opengis.net/sos/1.0"

xmlns:om="http://www.opengis.net/om/1.0"

xmlns:ogc="http://www.opengis.net/ogc"

xmlns:gml="http://www.opengis.net/gml"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0.0" service="SOS" xsi:schemaLocation="http://www.opengis.net/sos/1.0 http://schemas.opengis.net/sos/1.0.0/sosGetObservation.xsd">

<offering>http___shom.fr_maregraphie_offering_68</offering>

<eventTime>

<ogc:TM_During>

<ogc:PropertyName>om:samplingTime</ogc:PropertyName>

<gml:TimePeriod>

<gml:beginPosition>2014-01-15T00:00:00Z</gml:beginPosition>

<gml:endPosition>2014-01-17T23:59:59Z</gml:endPosition>

</gml:TimePeriod>

</ogc:TM_During>

</eventTime>

<observedProperty>http://shom.fr/maregraphie/observedProperty/WaterHeight/0</observedProperty>

<responseFormat>text/xml; subtype="om/1.0.0"</responseFormat>

<resultModel>om:Measurement</resultModel>

<responseMode>inline</responseMode>

</GetObservation> 

 

  • <offering> = identifiant du marégraphe
  • <observedProperty> permet de choisir le type de hauteur d’eau, parmi les différents types d’enregistrements : WaterHeight/1 : Brutes Haute fréquence ; WaterHeight/2 : Brutes temps différé ; WaterHeight/3 : Validées temps différé ; WaterHeight/4 : Validées horaires ; WaterHeight/0 : Toutes les sources disponibles sur la période demandée.


Il est aussi possible d’en demander plusieurs en séparant les url par des virgules: "observedProperty": ["https://shom.fr/maregraphie/observedProperty/WaterHeight/4", "https://shom.fr/maregraphie/observedProperty/WaterHeight/3"]

  • <eventTime>, permet de préciser les bornes temporelles entre lesquelles vous souhaitez récupérer les données. Le format "2015-01-15T00:00:00+00:00", correspond à : [année]-[mois]-[jour]T[heure]:[minutes]:[secondes][système horaire ici UTC]

 

Étape 3 : Scripter la collecte de données

Pour automatiser la récupération des données, il est possible de scripter les requêtes avec une commande de type wget :

wget -O fichier_sortie.extension "GetObservation_enGet"

Par exemple la requête pour récupérer les données brutes haute fréquence de la station de Brest du 3 juillet 2019 au 9 juillet 2019 au format TXT est la suivante :

wget -O reponse.txt "https://services.data.shom.fr/maregraphie/observation/txt/3?sources=1&dtStart=2019-07-03T00:00:00Z&dtEnd=2019-07-09T23:59:59Z"

Aide sur les API pour les données marégraphiques REFMAR

A découvrir également