Spécifications techniques pour l’accès aux services web de ...tides.gc.ca/docs/Specifications -...

Spécifications techniques pour l’accès aux services web de

niveaux d’eau

Version 2.0.3

Septembre 2014

Service hydrographique du Canada

Pêches et Océans Canada

Services web de niveaux d’eau version 2.0.3

Service hydrographique du Canada sur 14

Table des matières

Introduction .................................................................................................................................................................... 3

Accès et aide ................................................................................................................................................................... 3

Adresses .......................................................................................................................................................................... 3

Technologies ................................................................................................................................................................... 3

Méthodes disponibles ..................................................................................................................................................... 4

getStatus ............................................................................................................................................................... 4

getName .................................................................................................................................................................... 4

getInfo .................................................................................................................................................................... 4

getVersion ............................................................................................................................................................. 4

getBoundaryDate ................................................................................................................................................. 4

getBoundaryDepth .............................................................................................................................................. 4

getBoundarySpatial ......................................................................................................................................... 4

getDataInfo .......................................................................................................................................................... 5

getMetadata .......................................................................................................................................................... 5

getMetadataInfo ................................................................................................................................................. 7

search ...................................................................................................................................................................... 7

Exemples d’appels à la méthode search ............................................................................................................. 8

interpolate .......................................................................................................................................................... 9

Références .................................................................................................................................................................... 10

Annexe A – Diagramme de classe de la norme WDS .................................................................................................... 11

ResultSet ............................................................................................................................................................. 11

Annexe B – Diagramme de classe de la méthode interpolate du service SPINE .......................................................... 12

ResultSpine ........................................................................................................................................................ 12

DataSpine ............................................................................................................................................................. 13

Annexe C – Les messages d’erreur ................................................................................................................................ 14



Introduction

Les trois services web décrits dans ce document permettent un accès direct aux données de niveaux d’eau

acquis et générés par le Service hydrographique du Canada de Pêches et Océans Canada (SHC).

Le service web de prévisions et d’interpolation des niveaux d’eau (communément appelé SPINE) est un

système permettant d’obtenir les niveaux d’eau à une date/heure et à un endroit précis dans le chenal de

navigation du fleuve St-Laurent entre Saint-Joseph-de-la-Rive et le port de Montréal. Ce système s’appuie

sur un modèle de prévisions maintenu par le Service hydrographique du Canada.

Le service web d’observations donne accès aux observations des niveaux d’eau recueillies par un réseau

de marégraphes et de limnimètres, installés le long du fleuve Saint-Laurent, de l’estuaire et du golfe.

Le service web de prédictions donne accès aux prédictions des niveaux d’eau côtiers d’un océan à l’autre

du Canada.

Accès et aide

Ces services web sont ouverts au grand public et ne nécessitent aucune autorisation d’accès spéciale. Si

vous avez des questions supplémentaires, vous pouvez communiquer directement avec le Service

hydrographique du Canada à l’adresse suivante : [email protected]

Veuillez noter que le Service hydrographique du Canada n’offrira aucune information supplémentaire sur

les données « informatives » de température de l’eau, salinité et pression atmosphérique. Les questions sur

les niveaux d’eau seront répondues dans les délais prescrits par les normes de service en vigueur au SHC.

Les conditions météorologiques peuvent engendrer des différences (temps et hauteur) entre les marées

prédites (prédictions) et les marées observées (observations). Ces différences résultent surtout des

variations de la pression atmosphérique, des vents forts soutenus ou des variations du débit d’eau douce.

Adresses

Les points d’entrées des services web sont :

Service web des prévisions : https://ws-shc.qc.dfo-mpo.gc.ca/spine

Service web des observations : https://ws-shc.qc.dfo-mpo.gc.ca/observations

Service web des prédictions : https://ws-shc.qc.dfo-mpo.gc.ca/predictions

Technologies

Les trois services web utilisent SOAP et XML comme protocole de communication et la langue anglaise pour

l’appel des méthodes et l’échange des données. Chacun des trois services possède une description en XML

accessible en langage WSDL (https://ws-shc.qc.dfo-mpo.gc.ca/predictions?wsdl). Cette description est très

utile pour générer automatiquement (par exemple, à l’aide d’outils comme WSDL2Java d’Apache Axis) du

code pour communiquer avec les services. De plus, les services respectent entièrement la norme Web Data

Service WDS établie par l’Observatoire Global du St-Laurent (OGSL). La documentation détaillée de la

norme WDS se trouve à : http://weds.sourceforge.net/cookbook/fr/index.html

https://ws-shc.qc.dfo-mpo.gc.ca/spine

https://ws-shc.qc.dfo-mpo.gc.ca/observations

https://ws-shc.qc.dfo-mpo.gc.ca/predictions

https://ws-shc.qc.dfo-mpo.gc.ca/predictions?wsdl

http://weds.sourceforge.net/cookbook/fr/index.html



Méthodes disponibles

La norme WDS décrit dix méthodes donnant de l’information sur le service lui-même et une méthode pour la

recherche de données. La description détaillée des méthodes et des objets utilisés par celle-ci est disponible

sur le site web de la norme WDS.

Exceptionnellement, le service de prévisions SPINE ajoute la méthode de recherche interpolate décrite

plus bas.

getStatus

Donne le statut du service. Si le service est disponible et fonctionnel, le statut est à « ok », tandis que s’il y a

un problème, le statut est à « error ».

getName

Donne le nom du service.

getInfo

Donne la description du service.

getVersion

Donne la version de la norme WDS utilisée pour le service web.

getBoundaryDate

Donne les limites temporelles du service en UTC (toutes les dates sont en UTC).

Il est important de mentionner qu’une recherche de données effectuée avec des bornes temporelles

excédant les limites temporelles du service ne génèrera pas d’erreur, mais un résultat vide, car aucune

donnée ne respecte les critères temporaux de la recherche.

getBoundaryDepth

Donne la limite de profondeur du service. Tous les services donnent des niveaux d’eau et ceux-ci sont

considérés à la surface à une profondeur de zéro (0.0). Les valeurs sont en mètres.

Le service d’observations est le seul service pour lequel les limites et les valeurs de profondeurs sont

significatives. Les valeurs de température et de salinité de l’eau sont prises sous la surface, rendant les

limites de profondeurs requises lors de leur recherche. Cependant, les valeurs de pression atmosphérique

sont prises au-dessus de la surface et elles ont donc une profondeur de zéro (0.0).

Il est important de mentionner qu’une recherche de données effectuée avec des bornes de profondeur

excédant les limites de profondeurs du service ne génèrera pas d’erreur mais un résultat vide car aucune

donnée ne respecte les critères de profondeur de la recherche.

getBoundarySpatial

Donne les latitudes et longitudes à l’intérieur desquelles il est possible d’interroger le service. Les valeurs

des latitudes et des longitudes sont en degrés décimaux et suivent les règles de la norme ISO 6709 pour ce

qui est du signe (une latitude positive est au Nord et une longitude positive est à l’Est).



Il est encore important de mentionner qu’une recherche de données effectuée avec des bornes spatiales

excédant les limites spatiales du service, ne génèrera pas d’erreur, mais un résultat vide, car aucune donnée

ne respecte les critères géographiques de la recherche.

getDataInfo

Donne la liste des types de données disponibles pour le service ainsi que leur description.

Le service SPINE donne une seule valeur :

spine : prévision de la hauteur du niveau d’eau en mètre

Le service d’observations donne quatre valeurs :

wl : niveau d’eau en mètre au zéro marégraphique (zéro des cartes)

sal : salinité en partie par millier (‰)

temp : température de l’eau en degrés Celcius

atm_pres : pression atmosphérique en millibars

Note : Les données de type environnementales (sal, temp et atm_pres) sont des données auxiliaires,

fournies à titre informatif seulement. Aucun contrôle de la qualité n’est effectué sur ces données et aucune

information supplémentaire ne sera fournie sur celles-ci.

Le service de prédictions donne deux valeurs (en mètre au zéro marégraphique) :

hilo : les niveaux d’eau des marées hautes et marées basses

wl15 : les niveaux d’eau aux quinze minutes ( :00, :15, :30 et :45)

Le service web de prédictions n’offre que les prédictions de niveaux d’eau. Les prédictions reliées aux

arrivées de mascarets (Moncton et Truro) et aux étales de courants (Reversing Falls) ne sont donc pas

disponibles à travers ce service.

Une de ces valeurs doit être fournie comme premier paramètre à la méthode search de son service

respectif.

getMetadata

Donne une liste de métadonnées (informations connexes) du service web accompagnée de leur valeur.

Le service SPINE a six (6) métadonnées :

Nom de la métadonnée Valeur

Contact Donne l’information sur les personnes à contacter en cas de problèmes ou à des fins de validation de données.

Language Donne la langue des différents messages entre le service web et le client.

Name Donne le nom du service web.

Abstract Donne la description du service web.

reference_date Donne l’intervalle temporel ayant des données. Toutefois, les extrêmes temporels définissant les limites du service doivent être accédés via la

méthode getBoundaryDate.

max_results Donne le nombre maximum d’éléments retournés lors d’une requête aux

méthodes search ou interpolate.



Le service d’observations a onze (11) métadonnées:


station_id_list Donne la liste des identifiants des marégraphes disponibles, séparés par

des virgules : 03057,03071,03100,…

station_id_position Donne la liste des identifiants des marégraphes disponibles ainsi que

leurs latitudes et leurs longitudes séparés par des virgules. Ces trois

valeurs sont englobées par des crochets : [15520,45.5035,-

73.5525][15540,45.5286667,73.5424444]….

contact Donne l’information sur les personnes à contacter en cas de problèmes

ou à des fins de validation de données.

language Donne la langue des différents messages entre le service web et le client.

name Donne le nom du service web.

abstract Donne la description du service web.

reference_date Donne l’intervalle temporel ayant des données. Toutefois, les extrêmes

temporels définissant les limites du service doivent être accédés via la


station_id_name_list Donne la liste des identifiants et des noms des marégraphes disponibles

séparés par deux points-virgules et englobés par des crochets :

[15520;;Montréal, Jetée no 1][15540;;Montréal, rue Frontenac]…

metadata_selection_accepted Donne la liste des champs acceptés dans la méthode search afin de

sélectionner les données correspondantes à une certaine valeur : le tout,

séparé par des virgules. Pour plus d’informations, consultez la

documentation des WDS et ciblez le paramètre metadataSelection de la

méthode search.

max_rows Donne le nombre maximum d’éléments retournés lors d’une requête à la

méthode search.

total_nbr_obs Donne le nombre total de valeurs dans la base de données.

Le service de prédictions a douze (12) métadonnées:


contact Donne l’information sur les personnes à contacter en cas de problèmes

ou à des fins de validation de données.

date Donne la date de mise en service du service web.

language Donne la langue des différents messages entre le service web et le client.

topic Donne le sujet du service web.



name Donne le nom du service web.

abstract Donne la description du service web.

reference_date Donne l’intervalle temporel ayant des données. Toutefois, les extrêmes

temporels définissant les limites du service doivent être accédés via la


station_id_list Donne la liste des identifiants des stations disponibles, séparés par des

virgules : 03057,03071,03100,…

station_id_position Donne la liste des identifiants des stations disponibles ainsi que leur

latitude et leur longitude séparées par des virgules. Ces trois informations

sont englobées par des crochets

: [15520,45.5035,-73.5525][15540,45.5286667,-73.5424444]…

station_id_name_list Donne la liste des identifiants et des noms des stations disponibles

séparés par des points-virgules et englobés par des crochets :

[15520;;Montréal, Jetée no 1][15540;;Montréal, rue Frontenac]…

metadata_selection_accepted Donne la liste des champs acceptés dans la méthode search afin de

sélectionner les données correspondantes à une certaine valeur : le tout,

séparé par des virgules. Pour plus d’informations, consultez la

documentation des WDS et ciblez le paramètre metadataSelection de la

méthode search.

max_rows Donne le nombre maximum d’éléments retournés lors d’une requête à la

méthode search.

getMetadataInfo

Donne une liste avec la description des différentes métadonnées du service.

Il est important de mentionner qu’il y a trois paliers de métadonnées :

Les métadonnées reliées directement au service, accessible par la méthode getMetadata et

décrites par cette méthode.

Les métadonnées qui sont liées au résultat d’une recherche.

Les métadonnées qui sont reliées à chacune des données du résultat d’une recherche.

search

Fais une recherche et retourne un objet ResultSet, les données elles-mêmes, ainsi que diverses

métadonnées reliées à ces résultats (l’objet ResultSet est décrit à l’annexe A).

Cette méthode nécessite une multitude d’informations : un type de donnée, un zone géographique (latitude

minimale et maximale, longitude minimale et maximale), un intervalle de profondeur, un intervalle temporel,

ainsi que l’indice de la première donnée du résultat et le nombre désiré de données, l’indicateur d’inclusion

des métadonnées, la sélection de données basée sur les métadonnées et l’ordre temporel (voir les

exemples plus loin).

Bien que cette méthode soit disponible pour les trois services web, elle est dépréciée (deprecated) pour le

service SPINE, qui utilise plutôt la méthode interpolate pour rechercher les données.



Les données des services d’observations et de prédictions ont les métadonnées suivantes pour aider à

les identifier :

metadata : tableau d’informations connexes à la donnée qui contient :

station_id : Numéro unique de la station (i.e. : 02985)

station_name : Nom de la station (i.e. : Rimouski)

vl : Niveau de validation de la donnée (pour observations seulement)

0 = donnée invalide, la donnée acquise n’a subi aucun niveau de validation. C’est la

valeur brute donnée par les capteurs du marégraphe.

1 = donnée vérifiée, la donnée est validée préliminairement selon certains

paramètres de validation comme des valeurs minimum et maximum et un écart

maximum entre les capteurs.

2 = donnée certifiée, les deux niveaux de validation précédents ont été effectués et un algorithme complexe

comparant l’observation avec les prévisions et prédictions permet de certifier cette donnée.Les métadonnées

décrites ci-haut peuvent être utilisées comme valeur au paramètre metadataSelection (c.-à-d.

station_id=02985 ou encore station_name=Rimouski). Des exemples de recherche sont donnés

plus loin.

Il aussi est possible d’utiliser le niveau de validation vl comme paramètre metadataSelection lors d’un appel

à la méthode search, avec en plus, les opérateurs + et - afin d’effectuer une sélection de données de

plusieurs niveaux (i.e vl=1+ ne donnera que les données de niveau 1 et 2).

Exemples d’appels à la méthode search

Service web des prédictions EXEMPLE 1

search("hilo", 47.5, 47.7, -61.6, -61.4, 0.0, 0.0, "2012-02-01

00:00:00", "2012-02-01 23:59:59", 1, 100, true, "", "asc")

Recherche toutes les marées hautes et basses dans le nord-est des Îles-de-la-Madeleine le

1er

février 2012 et demande les 100 premières données en commençant par la première

avec les métadonnées sans sélections de métadonnées le tout en ordre croissant de date.

EXEMPLE 2

search("wl15", 47.5, 47.7, -61.6, -61.4, 0.0, 0.0, "2012-02-03

23:43:54", "2012-02-04 00:17:27", 3, 5, true, "", "desc")

Recherche les niveaux d’eau prédits dans le nord-est des Îles-de-la-Madeleines dans la nuit

du 3 février 2012 au 4 février 2012 et demande, en ordre décroissant, les cinq premières

données en commençant par la troisième (données 3, 4, 5, 6 et 7) avec les métadonnées

sans sélections de métadonnées.

Service web des observations EXEMPLE 1

search("sal", -90.0, 90.0, -180.0, 180.0, 5.0, 50.0, "2012-12-10

14:15:00", "2012-12-10 14:30:00", 1, 1000, true, "", "asc")

Recherche toutes les mesures de salinité prise entre 5 mètres et 50 mètres le 10 décembre

2012 entre 14h15 et 14h30 et donne les 1000 premières valeurs triées en ordre croissant.



EXEMPLE 2

search("wl", -90.0, 90.0, -180.0, 180.0, 0.0, 0.0, "2012-12-10

13:16:00", "2012-12-10 14:16:00", 1, 1, true, "station_id=02985",

"desc")

En supposant être le 10 décembre 2012 à 14h16, donne le niveau d’eau le plus récent à

Rimouski (02985) si celui-ci a été mesuré dans la dernière heure.

EXEMPLE 3

search("wl", 48.4, 48.5, -68.6, -68.5, 0.0, 0.0, "2012-12-10

12:00:00", "2012-12-10 18:00:00", 1, 1000, true, "vl=1+","asc")

Recherche tous les niveaux d’eau à Rimouski durant l’après-midi du 10 décembre 2012 dont

le niveau de validation est 1 ou 2. En remplaçant « vl=1+ », par « vl=2 », l’utilisateur

obtiendrait seulement les données validées de niveau 2.

interpolate

Fait une recherche de prévisions de niveaux d’eau et donne un objet complexe ResultSpine contenant les

données ainsi que diverses métadonnées reliées au résultat (l’objet ResultSpine est décrit à l’annexe B).

Cette méthode exclusive au service SPINE est beaucoup plus simple que la méthode search, ne

nécessitant que trois tableaux en paramètre :

Un tableau de nombres réels pour indiquer la latitude

Un deuxième tableau de nombres réels pour indiquer la longitude

Un tableau de type chaine de caractères pour la date.

Il est important de mentionner que le même indice pour chaque tableau correspond à une même requête.



Références

Pour en savoir plus sur les technologies utilisées dans nos services web, nous vous suggérons les

hyperliens suivants :

SOAP :

http://www.w3.org/TR/soap/

http://en.wikipedia.org/wiki/SOAP

Norme WDS :


http://weds.sourceforge.net/cookbook/en/index.html

WSDL :

http://www.w3.org/TR/wsdl

http://en.wikipedia.org/wiki/Web_Services_Description_Language

http://www.w3.org/TR/soap/

http://en.wikipedia.org/wiki/SOAP


http://weds.sourceforge.net/cookbook/en/index.html

http://www.w3.org/TR/wsdl

http://en.wikipedia.org/wiki/Web_Services_Description_Language



Annexe A – Diagramme de classe de la norme WDS

Extrait du document « WDS Cookbook » (http://weds.sourceforge.net/cookbook/fr/index.html)

ResultSet

Une instance de la classe ResultSet est retournée comme résultat d’une recherche. Cet objet, au centre

du diagramme ci-haut, contient un tableau de données dans sa propriété data de taille size. En plus des

données, un objet ResultSet contient plusieurs autres propriétés :

boundarySpatial : les limites spatiales des données comprises dans le résultat,

boundayDepth : les limites de profondeur des données comprises dans le résultat,

boundaryDate : les limites temporelles des données comprises dans le résultat,

boundaryValue : les limites des valeurs des données elles-mêmes,

status : le statut de la requête

metatada : d’autres métadonnées sur la requête

Pour ce qui des valeurs elles-mêmes, celles-ci sont des instances de la classe Data. Les propriétés

spatialCoordinates, boundaryDepth et boundaryDate indiquent l’emplacement du senseur qui l’a mesuré et

la propriété metadata donne de l’information supplémentaire (voir la section sur la recherche). La valeur de

la donnée est dans la propriété value.




Annexe B – Diagramme de classe de la méthode interpolate du service SPINE

ResultSpine

Une instance de la classe ResultSpine est retournée comme résultat d’une interpolation. Cet objet, au

centre du diagramme ci-haut, contient un tableau de données dans sa propriété data de taille size. En plus

des données, un objet ResultSpine contient :

status : le statut de la requête

metatada : d’autres métadonnées sur la requête

Pour ce qui des valeurs elles-mêmes, celles-ci sont des instances de la classe DataSpine. Les propriétés

coordinates et date indiquent l’emplacement de la mesure et les propriétés metadata et type donnent de

l’information supplémentaire (voir la section sur interpolate). La valeur de la donnée est dans la propriété

value.



DataSpine

Une instance de la classe DataSpine contient les valeurs d’une prévision d’un niveau d’eau et ses

métadonnées :

value : le niveau d’eau en mètre

coordinate : les coordonnées spatiales ramenées au centre du chenal, sur le fleuve Saint-Laurent

date : la date pour laquelle le niveau d’eau est prévu

type : le type de donnée; peut être forecast pour une prévision ou peut commencer par error pour

indiquer une erreur

metadata : les métadonnées sur la prévision, dont age_forecast qui indique l’âge en minute de la

prévision (c’est-à-dire l’écart entre la date de production de la prévision et la date de la demande de

prévision) et precision_index qui donne la marge d’erreur en mètre

Tout autre type ou métadonnée disponible à ce moment n’a pas de valeur significative et sont des espaces

réservés pour des changements futurs.



Annexe C – Les messages d’erreur

S’il y a des erreurs dans une requête à la méthode search ou encore si le service lui-même est en erreur, la

propriété status de l’objet ResultSet pourrait contenir les messages suivants :

Valeur : Ce que cela signifie :

The web service is currently unavailable.

Please, try later.

Le service web n’est pas disponible dû à des problèmes

de communication avec sa source de données ou pour un

entretien, veuillez réessayer plus tard.

Invalid date format La date entrée est invalide. Le format requis est le yyyy-

MM-dd HH:mm:ss en UTC.

Invalid order Les valeurs acceptées pour l’ordre des données

retournées sont asc ou desc.

Invalid datatype Le type de donnée spécifié dans le paramètre dataname

n’est pas valide. Voir getDataInfo pour la liste des

valeurs.

S’il y a des erreurs dans une requête à la méthode interpolate du service SPINE ou encore si le service

lui-même est en erreur, la propriété status de l’objet ResultSpine pourrait contenir les messages suivants :

Valeur Ce que cela signifie :

The forecast web service is currently

unavailable. Please, try later.

Le service web n’est pas disponible dû à des problèmes

de communication avec sa source de données ou pour un

entretien, veuillez réessayer plus tard.

error, Out of Date Boundary Les dates sont en dehors des limites temporelles.

error, Out of Spatial Boundary Les coordonnées géographiques sont en dehors des

limites spatiales.

error, Wrong date format La date entrée est invalide. Le format requis est le yyyy-

MM-dd HH:mm:ss en UTC.

Finalement, les données DataSpine du service SPINE pourraient avoir comme valeur le message suivant :

error, The geographic coordinate must be

closer to the center of the St. Lawrence river.

Les coordonnées géographiques sont dans les bornes

spatiales mais trop loin du chenal du fleuve Saint-Laurent.

Spécifications techniques pour l’accès aux services web de ...tides.gc.ca/docs/Specifications -...

Documents

Transcript of Spécifications techniques pour l’accès aux services web de ...tides.gc.ca/docs/Specifications -...