Spécifications techniques pour l accès aux services web de niveaux d eau

Transcription

1 Spécifications techniques pour l accès aux services web de niveaux d eau Version Septembre 2014 Service hydrographique du Canada Pêches et Océans Canada

2 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 Annexe A Diagramme de classe de la norme WDS ResultSet Annexe B Diagramme de classe de la méthode interpolate du service SPINE ResultSpine DataSpine Annexe C Les messages d erreur Service hydrographique du Canada Page 2 sur 14

3 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 : shcinfo@dfo-mpo.gc.ca 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 : Service web des observations : Service web des prédictions : 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 ( 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 à : Service hydrographique du Canada Page 3 sur 14

4 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 getname getinfo 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». Donne le nom du service. 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). Service hydrographique du Canada Page 4 sur 14

5 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 Contact Language Name Abstract reference_date max_results Valeur Donne l information sur les personnes à contacter en cas de problèmes ou à des fins de validation de données. Donne la langue des différents messages entre le service web et le client. Donne le nom du service web. Donne la description du service web. 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. Donne le nombre maximum d éléments retournés lors d une requête aux méthodes search ou interpolate. Service hydrographique du Canada Page 5 sur 14

6 Le service d observations a onze (11) métadonnées: Nom de la métadonnée station_id_list station_id_position contact language name abstract reference_date station_id_name_list metadata_selection_accepted max_rows total_nbr_obs Valeur Donne la liste des identifiants des marégraphes disponibles, séparés par des virgules : 03057,03071,03100, 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, , ][15540, , ]. Donne l information sur les personnes à contacter en cas de problèmes ou à des fins de validation de données. Donne la langue des différents messages entre le service web et le client. Donne le nom du service web. Donne la description du service web. 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. 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] 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. Donne le nombre maximum d éléments retournés lors d une requête à la méthode search. Donne le nombre total de valeurs dans la base de données. Le service de prédictions a douze (12) métadonnées: Nom de la métadonnée contact date language topic Valeur Donne l information sur les personnes à contacter en cas de problèmes ou à des fins de validation de données. Donne la date de mise en service du service web. Donne la langue des différents messages entre le service web et le client. Donne le sujet du service web. Service hydrographique du Canada Page 6 sur 14

7 name abstract reference_date station_id_list station_id_position station_id_name_list metadata_selection_accepted max_rows Donne le nom du service web. Donne la description du service web. 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. Donne la liste des identifiants des stations disponibles, séparés par des virgules : 03057,03071,03100, 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, , ][15540, , ] 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] 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. 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. Service hydrographique du Canada Page 7 sur 14

8 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 EXEMPLE 2 search("hilo", 47.5, 47.7, -61.6, -61.4, 0.0, 0.0, " :00:00", " :59:59", 1, 100, true, "", "asc") Recherche toutes les marées hautes et basses dans le nord-est des Îles-de-la-Madeleine le 1 er 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. search("wl15", 47.5, 47.7, -61.6, -61.4, 0.0, 0.0, " :43:54", " :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, 5.0, 50.0, " :15:00", " :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. Service hydrographique du Canada Page 8 sur 14

9 interpolate EXEMPLE 2 EXEMPLE 3 search("wl", -90.0, 90.0, , 180.0, 0.0, 0.0, " :16:00", " :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. search("wl", 48.4, 48.5, -68.6, -68.5, 0.0, 0.0, " :00:00", " :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. 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. Service hydrographique du Canada Page 9 sur 14

10 Références Pour en savoir plus sur les technologies utilisées dans nos services web, nous vous suggérons les hyperliens suivants : SOAP : Norme WDS : WSDL : Service hydrographique du Canada Page 10 sur 14

11 Annexe A Diagramme de classe de la norme WDS ResultSet Extrait du document «WDS Cookbook» ( 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. Service hydrographique du Canada Page 11 sur 14

12 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. Service hydrographique du Canada Page 12 sur 14

13 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. Service hydrographique du Canada Page 13 sur 14

14 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. Invalid date format Invalid order Invalid datatype 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. La date entrée est invalide. Le format requis est le yyyy- MM-dd HH:mm:ss en UTC. Les valeurs acceptées pour l ordre des données retournées sont asc ou desc. 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. error, Out of Date Boundary error, Out of Spatial Boundary error, Wrong date format 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. Les dates sont en dehors des limites temporelles. Les coordonnées géographiques sont en dehors des limites spatiales. 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. Service hydrographique du Canada Page 14 sur 14