Technical specifications for accessing Water Level Web Services

Transcription

1 Technical specifications for accessing Water Level Web Services Version September 2014 Canadian Hydrographic Service Fisheries and Oceans Canada

2 Contents Introduction... 3 Access and support... 3 Addresses... 3 Technologies... 3 Available Methods... 4 getstatus... 4 getname... 4 getinfo... 4 getversion... 4 getboundarydate... 4 getboundarydepth... 4 getboundaryspatial... 4 getdatainfo... 4 getmetadata... 5 getmetadatainfo... 7 search... 7 Examples of calls to method search... 8 interpolate... 9 References Appendix A Class Diagram of the WDS Standard ResultSet Appendix B Class Diagram of Method interpolate of web service SPINE ResultSpine DataSpine Appendix C Error Messages Canadian Hydrographic Service Page 2 of 14

3 Introduction This document describes three web services giving direct access to water levels measured and calculated by the Canadian Hydrographic Service (CHS) of Fisheries and Oceans Canada. The service web de prévisions et d interpolation des niveaux d eau (water level forecast and interpolation web service - also called SPINE) is a system allowing one to obtain water levels at any time on the St. Lawrence navigation channel between Saint-Joseph-de-la-Rive and the Port of Montréal. The observations web service offers water level observations collected by a network of tide and water level gauges deployed along the St. Lawrence River, its estuary and its gulf. The predictions web service offers water level predictions for over 800 coastal locations all over Canada. Access and support Access to the web services is available to general public, free of charge. Further information can be obtained by communicating with the Canadian Hydrographic Service at chsinfo@dfo-mpo.gc.ca. This address should also be used to get support for using the CHS s web services. Notice that the CHS will not provide any additional information on auxiliary environmental data, such as water temperature, salinity nor atmospheric pressure. Requests of information on water level data will answered as soon as possible, within current CHS level of service. Meteorological conditions can cause differences (time and height) between the predicted and the observed tides. These differences are mainly the result of atmospheric pressure changes, strong prolonged winds or variations of freshwater discharge. Addresses The web service entry points are : SPINE web service: observations web service: predictions web service: Technologies All three web services use SOAP and XML and communicate in English. Each service has a WSDL description (i.e. : to help generate code using tools such WSDL2Java from Apache Axis. Furthermore, each service faithfully respects the Web Data Service WDS standard established by the St. Lawrence Global Observatory (SLGO). Details about the WDS standard can be found at: Canadian Hydrographic Service Page 3 of 14

4 Available Methods The WDS standard describes ten methods offering information about the service itself and one method to search data. The detailed description of each method and its objects are available on the WDS standard website. Exceptionally, the SPINE web service adds one search method called interpolate that is described later in this section. getstatus getname getinfo Gives the status of the web service. With the WDS up and running, the status should read «ok», and when something is wrong the status gives «error». Gives the name of the web service. Gives the description of the web service. getversion Gives the version number of WDS standard used by the web service. getboundarydate Gives the time interval data is available for (all dates and times are in UTC). It is important to note that a search with temporal limits outside this time interval will not result in an error but an empty set. getboundarydepth Gives the depth interval data is available for. Water levels are always considered to be at the surface and thus at a depth of zero (0.0). Values are in meters. The observation web service is the only service for which depth values have a meaning. Temperature and salinity are taken under the surface and require depth values when searching for them. However, atmospheric pressure are taken above the surface and also have depths of zero (0.0). It is important to note that a search with depth limits outside this depth interval will not result in an error but an empty set. getboundaryspatial Gives the latitudes and longitudes inside of which data is available. Latitude and longitude values are in decimal degrees and follow the ISO 6709 standard (a positive latitude is North, a positive longitude is East). It is important to note that a search with spatial limits outside this bounding box will not result in an error but an empty set. getdatainfo Gives the list of data type and their description. Canadian Hydrographic Service Page 4 of 14

5 SPINE has a single value : spine : water level forecast in meters Observations has four values : wl : water level in meters sal : water salinity in parts per thousand ( ) temp : water temperature in Celcius degree atm_pres : atmospheric pressure in millibars Note : environment data (sal, temp, den et atm_pres) are available only as is and no quality control has been done. Additional information on those data will not be supplied. Prédictions has two values : hilo : water levels of high tides and low tides wl15 : water levels each 15 minutes ( :00, :15, :30 et :45) The predictions web service only offers water levels predictions. Consequently, Tidal bores (Moncton et Truro) and slack waters (Reversing Falls) are not available through this service. One of these values must be given as the first parameter of its respective web service method search. getmetadata Gives a list of metadata alongside their values. SPINE has six (6) metadata : Name of the metadata contact language name abstract reference_date max_results Value Gives information about the person to contact in case of trouble. Gives the language of messages exchanged between the server and the client. Gives the name of the web service. Gives the description of the web service. Gives a textual representation of temporal limits. A more standard way is to call getboundarydate. Gives the maximum number of elements returned by a query to interpolate. Observations has eleven (11) metadata: Name of the metadata Value station_id_list Gives the list of tidal gauge ids, each id separated by a comma : 03057,03071,03100, station_id_position Gives the list of tidal gauge ids alongside their geographical coordinates. These three values are separated by comma and decorated with square brackets : [15520, , ][15540, , ]. Canadian Hydrographic Service Page 5 of 14

6 contact language name abstract reference_date station_id_name_list metadata_selection_accepted max_rows total_nbr_obs Gives information about the person to contact in case of trouble. Gives the language of messages exchanged between the server and the client. Gives the name of the web service. Gives the description of the web service. Gives a textual representation of temporal limits. A more standard way is to call getboundarydate. Gives the list of tidal gauge ids alongside their names. These two values are separated by two semi-colon and decorated by square brackets : [15520;;Montréal, Jetée no 1][15540;;Montréal, rue Frontenac] Gives the list of metadata fields allowed in method search, each separated by a comma. For more information, please consult the WDS standard and look for parameter metadataselection in method search. Gives the maximum number of elements returned by a call to method search. Gives the number of data points in the database. Predictions has twelve (12) metadata: Name of the metadata contact date language topic name abstract reference_date Value Gives information about the person to contact in case of trouble. Gives the date the web service came online Gives the language of messages exchanged between the server and the client. Gives the topic of the web service Gives the name of the web service. Gives the description of the web service. Gives a textual representation of temporal limits. A more standard way is to call getboundarydate. station_id_list Gives the list of tidal gauge ids, each id separated by a comma : 03057,03071,03100, station_id_position station_id_name_list Gives the list of tidal gauge ids alongside their geographical coordinates. These three values are separated by comma and decorated with square brackets : [15520, , ][15540, , ]. Gives the list of tidal gauge ids alongside their names. These two values are separated by two semi-colon and decorated by square brackets : Canadian Hydrographic Service Page 6 of 14

7 [15520;;Montréal, Jetée no 1][15540;;Montréal, rue Frontenac] metadata_selection_accepted max_rows Gives the list of metadata fields allowed in method search, each separated by a comma. For more information, please consult the WDS standard and look for parameter metadataselection in method search. Gives the maximum number of elements returned by a call to method search. getmetadatainfo Gives a list describing the each metadata. It is important to note that there are three levels of metadata : Service level metadata and given by method getmetadata. Result level metadata, metadata about the set of data given by a search. Data level metadata, metadata about a single value. search Makes a search and gives back data points and their metadata inside an object of type ResultSet (see Appendix A). This method requires many parameters: one data type, one spatial interval, one depth interval, one temporal interval, the 1-based index for the start of the data, the number of data, the flag to include data-level metadata, the metadata selection and the sort order (example are given later). This method is available in SPINE but has been deprecated, use interpolate instead. Data from observations and predictions have the following metadata to help identify them : metadata : the metadata array : station_id : the unique station id (i.e : 02985) station_name : the name of the station (i.e. : Rimouski) vl : validation level (observations only) o 0 = invalid data, the data has not been subject to any validation test, it is the raw data from the tidal gauge. o 1 = valid data, the data has passed basic tests. o 2 = certified data, the data has passed extensive tests. These data-level metadata can be used as value to parameter metadataselection (i.e. station_id=02985 or again station_name=rimouski). Examples are given later. Furthermore, it is possible to use metadata vl with operator + and when using it as parameter metadataselection to select data at multiple levels (i.e vl=1+ would give data at level 1 and 2). Canadian Hydrographic Service Page 7 of 14

8 Examples of calls to method search Prédiction EXAMPLE 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") Searches all the high tides and all the low tides in the northwest of the Îles-de-la-Madeleine on February 1st 2012, asks for the first 100 beginning with the first value and requests datalevel metadata with everything in ascending order. search("wl15", 47.5, 47.7, -61.6, -61.4, 0.0, 0.0, " :43:54", " :17:27", 3, 5, true, "", "desc") Searches all the water levels in the northwest of the Îles-de-la-Madeleines during the night of February 3rd 2012 and asks, in decreasing order, the next five elements starting at 3 (données 3, 4, 5, 6 et 7) with data-level metadata and no metadata selection. Observations EXAMPLE 1 EXAMPLE 2 EXAMPLE 3 search("sal", -90.0, 90.0, , 180.0, 5.0, 50.0, " :15:00", " :30:00", 1, 1000, true, "", "asc") Searches for all salinity values taken between 5 meters and 50 meters on December 10th 2012 between 14 :15 et 14 :30 and gives the first 1000 in ascending order. search("wl", -90.0, 90.0, , 180.0, 0.0, 0.0, " :16:00", " :16:00", 1, 1, true, "station_id=02985", "desc") Assuming being December 10th 2012 at 14 :16, gives the most recent water level at Rimouski (02985) if it has been measured in the last hour. search("wl", 48.4, 48.5, -68.6, -68.5, 0.0, 0.0, " :00:00", " :00:00", 1, 1000, true, "vl=1+","asc") Searches for all the water levels in Rimouski during the afternoon of December 10th 2012 which have a validation level of 1 or 2. By replacing "vl=1+" with "vl=2", one can get only the level 2 water levels. Canadian Hydrographic Service Page 8 of 14

9 interpolate Makes a search of forecast water levels and gives back data points and metadata inside an object of type ResultSpine (see Appendix B). This method only works in SPINE and is much more simple than search, only needing three arrays : One array of real numbers for latitudes Another array of real numbers for longitudes A last array of strings for dates. Values at the same index in the arrays represent a set of coordinates and arrays must have the same length. Canadian Hydrographic Service Page 9 of 14

10 References To learn more about technologies used by the web services : SOAP : WDS Standard: WSDL : Canadian Hydrographic Service Page 10 of 14

11 Appendix A Class Diagram of the WDS Standard ResultSet Extrait du document «WDS Cookbook» ( An instance of class ResultSet is given back as results to a search. This object, drawn at the center of the diagram, contains an array of data in its property data of size size. Other properties are : boundaryspatial : the spatial limits of the data inside the results, boundaydepth : the depth limits of the data inside the results, boundarydate : the temporal limits of the data inside the results, boundaryvalue : the limits of the values themselves, status : the status of the request metatada : other metadata about the request Values themselves are instances of class Data. Properties spatialcoordinates, boundarydepth and boundarydate indicate the location of the sensor and property metadata gives more information (see the section about method search). The value itself is in property value. Canadian Hydrographic Service Page 11 of 14

12 Appendix B Class Diagram of Method interpolate of web service SPINE ResultSpine An instance of class ResultSpine is given as a result to a call to an interpolation. This object, drawn at the center of the diagram contains an array as property data of size size. Other properties are : status : the status of the request metatada : other metadata about the request Values themselves are instances of class DataSpine. Properties coordinates and date indicate the location and time of the forecast, properties metadata and type give more information (see the section on interpolate). The value itself is in property value. Canadian Hydrographic Service Page 12 of 14

13 DataSpine An instance of class DataSpine contains values and metadata about a water level forecast: value: the water level in meters w.r.t chart datum coordinate: spatial coordinate moved to be at the closest St. Lawrence channel center-line date: the date for which the forecast is for type: the type of data: it can be forecast for a forecast or begin with error to indicate an error. metadata: metadata about the forecast, including age_forecast indicating the age in minute of the forecast (that is the interval between the moment the forecast was made and the moment the forecast was requested) and precision_index indicating the margin of error in meters Any other type or metadata available at the moment does not have any significant value and are placeholders for future changes Canadian Hydrographic Service Page 13 of 14

14 Appendix C Error Messages If there are errors in a search request or if the service itself has errors, the property status in the ResultSet will have one of these messages : Valeur : Ce que cela signifie : The web service is currently unavailable. Please, try later. Invalid date format Invalid order Invalid datatype Self explanatory. The date has an incorrect format. The correct format is yyyy-mm-dd HH:mm:ss in UTC. The order is incorrect, the correct orders are asc or desc. The type in parameter dataname is incorrect. See getdatainfo for a list of correct values. If there are errors in a call to interpolate from SPINE or if the service itself has errors, property status of ResultSpine will have one of these messages : 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 Self explanatory. Self explanatory. Self explanatory. The date has an incorrect format. The correct format is yyyy-mm-dd HH:mm:ss in UTC. Data of class DataSpine from SPINE can also have the following message instead of a value: error, The geographic coordinate must be closer to the center of the St. Lawrence river. The coordinates are inside the spatial limits but too far from the center of St. Lawrence River channel. Canadian Hydrographic Service Page 14 of 14