.. _available-functions: Available Functions =================== .. note:: Example responses shown will only show the ``data`` object within the JSON response. To view more information regarding the full JSON response, see :ref:`response-object`. Get Licences ------------ ======= ================ Syntax: ``get-licences`` ======= ================ Get licences is used to return all available licences associated with a specified key. If the call is successful, the data object within the JSON response will contain a ``data`` object containing an array of ``items``, with each value in the items array being an associated licence. Parameters: ''''''''''' ========= ====================== ==== Name Input Type Example ========= ====================== ==== Key 16 character string ``key=Q1w2E3r4T5Y6u7I8`` ========= ====================== ==== Special/Optional Parameters: '''''''''''''''''''''''''''' *None.* Example Request: '''''''''''''''' URL: .. code-block:: none https://apps.noc-innovations.co.uk/api/polpred-api/latest/get-licences?key=U2uf2HSEBrDXV2jl cURL: .. code-block:: none curl "https://apps.noc-innovations.co.uk/api/polpred-api/latest/get-licences" \ -d key=U2uf2HSEBrDXV2jl \ -G Example Response: ''''''''''''''''' The response below is using the free :ref:`demonstration-key` available. Here we can see the 1 licence available: .. code-block:: JSON { "data": { "totalItems": 1, "items": [ { "id": 0, "type": "offshore", "details": { "model": { "code": "CS3X_10HC", "name": "NW Europe CS3X Model (Depth averaged 10HC)" }, "latN": "53.5", "lngW": "-11.5", "latS": "49.5", "lngE": "-2.5", "dateFrom": "2019-10-01", "dateTo": "2020-01-01" } }, ] } } Compute Time Series ------------------- ======= ================ Syntax: ``compute-time-series`` ======= ================ Compute Time Series allows users to compute tidal elevations and currents at a single location over the course of a specified time period. The location is referenced by the user's latitude and longitude inputs, and time period is calculated by the user's start and end date inputs. A time interval must also be given, which specifies in minutes the frequency of computations. For example, ``interval=15`` will compute data every 15 minutes for the duration of the given time period. When the call is made, the API will select the first licence which matches all parameters given. Licences are ordered in terms of resolution, and therefore will look to find the best licence first. To see all licences available for your API key, see `Get Licences <#get-licences>`_. If you wish to include/exclude certain licences when computing, you can specify which licences are used using the ``licence_ids`` optional parameter (`See below <#id5>`_). Parameters: ''''''''''' Here are all required parameters for a Time Series Computation. ========== =========================================================================================== ======= Name Input Type Key/value Example ========== =========================================================================================== ======= key 16 character string ``key=Q1w2E3r4T5Y6u7I8`` lat Decimal number ``lat=50.893`` lng Decimal number ``lng=1.396`` dt_start String formatted to the UTC `ISO8601 `_ standard. ``dt_start=2019-11-01T00:00:00Z`` dt_end String formatted to the UTC `ISO8601 `_ standard. ``dt-end=2019-11-01T23:59:00Z`` interval Integer of 5, 6, 10, 12, 15, 20, 30 or 60. ``interval=15`` ========== =========================================================================================== ======= Special/Optional Parameters: '''''''''''''''''''''''''''' +--------------+-----------------------------------------------------------------------------------------------------------+---------------------------------+ | Name | Input Type | Example | +==============+===========================================================================================================+=================================+ | datum | | Specify which datum type the computation will use. | ``datum=lat`` | | | | By default, data is computed using `Mean Sea Level (MSL) `_. | | | | | Currently the two data options are MSL and | | | | | `Lowest Astronomical Tide (LAT) `_. | | | | | | +--------------+-----------------------------------------------------------------------------------------------------------+---------------------------------+ | licence_ids | | You can manually specify which licences are used in | ``licence_ids=0&licence_ids_2`` | | | | computation by referencing that licences' ``id``. | | | | | This can be helpful when dealing with multiple overlapping | | | | | licences where you want to exclude certain models etc. | | | | | You can check a licence's id by calling `Get Licences <#get-licences>`_ | | +--------------+-----------------------------------------------------------------------------------------------------------+---------------------------------+ Example Request: '''''''''''''''' URL: .. code-block:: none https://apps.noc-innovations.co.uk/api/polpred-api/latest/compute-time-series?key=U2uf2HSEBrDXV2jl&lat=52.940&lng=-5.559&dt_start=2019-10-01T00:00:00Z&dt_end=2019-10-01T23:59:59Z&interval=15 cURL: .. code-block:: none curl "https://apps.noc-innovations.co.uk/api/polpred-api/latest/compute-time-series" \ -d key=U2uf2HSEBrDXV2jl \ -d lat=52.940 \ -d lng=-5.559 \ -d dt_start=2019-10-01T00:00:00Z \ -d dt_end=2019-10-01T23:59:59Z \ -d interval=15 \ -G Example Response: ''''''''''''''''' The response below is using the free :ref:`demonstration-key` available. Here we can see the call has returned 96 total computations under the ``items`` array for the given location and time period: .. code-block:: JSON { "data": { "totalItems": 96, "model": { "name": "NW Europe CS3X Model (Depth averaged 10HC)", "code": "CS3X_10HC" }, "headers": { "dt": "Date/Time", "z": "Height", "u": "EW Component", "v": "NS Component", "m": "Current Speed", "d": "Direction" }, "units": { "dt": "utc", "z": "m", "u": "m/s", "v": "m/s", "m": "m/s", "d": "deg" }, "items": [ { "dt": "2019-10-01T00:00:00Z", "z": 0.85567, "u": 0.09461, "v": 0.24221, "m": 0.26003, "d": 21.33525 }, { "dt": "2019-10-01T00:15:00Z", "z": 0.7841, "u": 0.04828, "v": 0.02838, "m": 0.056, "d": 59.55252 }, { "etc..." } ] } } Compute Spatial --------------- ======= ================ Syntax: ``compute-spatial`` ======= ================ Compute Spatial allows users to compute tidal elevations and currents over a specified area for a single point in time. The area is specified by giving the north/south limits of latitude and east/west limits of longitude. Prerequisite Information: ''''''''''''''''''''''''' Usage of multiple licences: ########################### When a call is made, all licences which are present within the given boundary are used in computing data. A call will still be valid as long as there is at least one valid licence within the given boundary. Below are some examples of calling a specified area: **Boundary Examples:** * **Red** - Licence boundary. * **Blue** - Area used for API call. The example call below would be **valid** as two licences are within the specified area. This will return two sets of data for each licence boundary. The region where the two licences overlap will appear in both data output blocks in the JSON response. .. image:: ../_static/img/available-functions-spatial-1.jpg :alt: available functions, spatial example 1 :width: 600 The example call below would be **valid** as two licences are within the specified area. This will return two sets of data for each licence boundary. The region in the bottom right corner of the selected area will occur in both data blocks. .. image:: ../_static/img/available-functions-spatial-2.jpg :alt: available functions, spatial example 2 :width: 600 .. The example call below would be **valid** as one licence is within the specified area. This will return one set of data for the valid licence boundary. .. .. image:: ../_static/img/available-functions-spatial-3.jpg :alt: available functions, spatial example 3 :width: 600 Which points are calculated for a given area: ############################################# The number of points calculated within a given boundary is determinded by 2 things: * | **The resolution of the model used:** | The spacing between calculated points within an area cannot be smaller than what the model is capable of. For example, the smallest space between points when using the `CS3X Model `_ would be 0.1111 latitude (1/9°) and 0.1666 longitude (1/6°). *Graphical representation of a spatial call being made using the CS3X model at its grid spacing.* .. image:: ../_static/img/available-functions-spatial-5.jpg :alt: available functions, spatial example 5 :width: 600 * | **The total number of points returned for a given licence boundary.** | There can only be a maximum of **1280** points returned for any given licence and it's boundary. For this to be calculated, the api will determine how many points can be placed inside the given boundary using the oceanographic model's resolution. For example: * Using the CS3X model's resolution of 1/9° latitude by 1/6° longitude, an area spanning 4 degrees latitude and 9 degrees longitude would have a total of 1944 points, which is above the threshold. * In this instance, the model resolution will be **halved** (1/4.5° latitude and 1/3° longtiude) and calculated again, giving a total of 486 points which is in the threshold of total points. * This process of halving resolution is repeated if needed until the total number of points within a boundary is within the threshold. .. note:: The current implementation of how points are calculated may be revisited by us at a later date. If you are interested and would like to be part of this discussion, please :ref:`contact-us`. *Graphical representation of a spatial call returning data for two licences where both licences are the same resolution. However, the upper left boundary has had it's resolution halved as too many points would be calculated as a result.* .. image:: ../_static/img/available-functions-spatial-6.jpg :alt: available functions, spatial example 6 :width: 600 Parameters: ''''''''''' Here are all required parameters for a Spatial Computation. ========== =========================================================================================== ======= Name Input Type Key/value Example ========== =========================================================================================== ======= key 16 character string ``key=Q1w2E3r4T5Y6u7I8`` lat_n Decimal number ``lat_n=53.500`` lat_s Decimal number ``lat_s=49.500`` lng_w Decimal number ``lng_w=-11.500`` lng_e Decimal number ``lng_e=-2.500`` dt String formatted to the UTC `ISO8601 `_ standard. ``dt=2019-11-01T00:00:00Z`` ========== =========================================================================================== ======= Special/Optional Parameters: '''''''''''''''''''''''''''' +--------------+-----------------------------------------------------------------------------------------------------------+---------------------------------+ | Name | Input Type | Example | +==============+===========================================================================================================+=================================+ | datum | | Specify which datum type the computation will use. | ``datum=lat`` | | | | By default, data is computed using `Mean Sea Level (MSL) `_. | | | | | Currently the two data options are MSL and | | | | | `Lowest Astronomical Tide (LAT) `_. | | | | | | +--------------+-----------------------------------------------------------------------------------------------------------+---------------------------------+ | licence_ids | | You can manually specify which licences are used in | ``licence_ids=0&licence_ids_2`` | | | | computation by referencing that licences' ``id``. | | | | | This can be helpful when dealing with multiple overlapping | | | | | licences where you want to exclude certain models etc. | | | | | You can check a licence's id by calling `Get Licences <#get-licences>`_ | | +--------------+-----------------------------------------------------------------------------------------------------------+---------------------------------+ | include_land | | Specify whether points spanning over land are included in | ``include_land=1`` | | | | the returned data. These points will still return a latitude | | | | | and longitude but will have ``null`` as their data values. | | | | | This option is **off** by default. | | +--------------+-----------------------------------------------------------------------------------------------------------+---------------------------------+ Example Request: '''''''''''''''' URL: .. code-block:: none https://apps.noc-innovations.co.uk/api/polpred-api/latest/compute-spatial?key=U2uf2HSEBrDXV2jl&lat_n=53.5&lat_s=49.5&lng_w=-11.5&lng_e=-2.5&dt=2019-11-01T00:00:00Z cURL: .. code-block:: none curl "https://apps.noc-innovations.co.uk/api/polpred-api/latest/compute-spatial" \ -d lat_n=53.5 \ -d lat_s=49.5 \ -d lng_w=-11.5 \ -d lng_e=-2.5 \ -d dt=2019-11-01T00:00:00Z \ -G Example Response: ''''''''''''''''' The ``items`` array returned is handled differently to Compute Time Series (`See Above <#id8>`_). The ``items`` array contains a set of data for each licence within the boundary. It is within each of these sets of data that tidal elevations and currents data is found in ``items[i].points``. For each set of data, the ``resultStep`` is returned which was used to determine which points in the area were used. This can be cross referenced with the ``modelStep`` and ``resolution`` to determine how the latitude/longitude points have been calculated. * See `Which points are calculated for a given area <#which-points-are-calculated-for-a-given-area>`_ for more details. .. code-block:: JSON :emphasize-lines: 33, 39, 48 :linenos: { "data": { "dt": "2019-11-01T00:00:00Z", "headers": { "lat": "Latitude", "lng": "Longitude", "z": "Height", "u": "EW Component", "v": "NS Component", "m": "Current Speed", "d": "Direction" }, "units": { "lat": "deg", "lng": "deg", "dt": "utc", "z": "m", "u": "m/s", "v": "m/s", "m": "m/s", "d": "deg" }, "totalItems": 2, "items": [ { "model": { "name": "NW Europe CS3X Model (Depth averaged 10HC)", "code": "CS3X_10HC" }, "modelStepLat": 0.1111111111, "modelStepLng": 0.1666666667, "resultStepLat": 0.2222222222, "resultStepLng": 0.3333333334, "resolution": 0.5, "totalPoints": 322, "points": [ { "lat": 53.5, "lng": -11.25, "z": -1.17172, "u": 0.02877, "v": -0.03802, "m": 0.04767, "d": 142.8871 }, { "lat": 53.5, "lng": -10.91666, "z": -1.20849, "u": 0.01507, "v": -0.02918, "m": 0.03284, "d": 152.6934 }, { "etc..." } ] }, { "etc..." } ], } } Compute Port ------------ ======= ================ Syntax: ``compute-port`` ======= ================ Compute Port allows users to compute tidal sea surface height for a selection of ports around the earth using the database of harmonic constants created and maintained by the National Oceanography Centre. Ports are referenced using one of the available port names (See `Get Port List <#id26>`_) while time period is calculated by the user’s start and end date inputs. A time interval must also be specified in minutes. For example, ``interval=15`` will compute data every 15 minutes for the duration of the given time period. Only one port name can be given per call. .. note:: If you would like more information regarding harmonic constants or have a specific request, please contact us. Parameters: ''''''''''' ========== =========================================================================================== ======= Name Input Type Key/value Example ========== =========================================================================================== ======= key 16 character string ``key=Q1w2E3r4T5Y6u7I8`` port_name String ``port_name=Liverpool (Gladstone Dock)`` dt_start String formatted to the UTC `ISO8601 `_ standard. ``dt_start=2019-11-01T00:00:00Z`` dt_end String formatted to the UTC `ISO8601 `_ standard. ``dt-end=2019-11-01T23:59:00Z`` interval Integer of 5, 6, 10, 12, 15, 20, 30 or 60. ``interval=15`` ========== =========================================================================================== ======= Special/Optional Parameters ''''''''''''''''''''''''''' +--------------+-----------------------------------------------------------------------------------------------------------+---------------------------------+ | Name | Input Type | Example | +==============+===========================================================================================================+=================================+ | datum | | Specify which datum type the computation will use. | ``datum=lat`` | | | | By default, data is computed using `Mean Sea Level (MSL) `_. | | | | | Currently the two data options are MSL and | | | | | `Lowest Astronomical Tide (LAT) `_. | | | | | | +--------------+-----------------------------------------------------------------------------------------------------------+---------------------------------+ Example Request: '''''''''''''''' URL: .. code-block:: none https://apps.noc-innovations.co.uk/api/polpred-api/latest/compute-port?key=U2uf2HSEBrDXV2jl&port_name=Liverpool%20(Gladstone%20Dock)&dt_start=2019-10-01T00:00:00Z&dt_end=2019-10-01T23:59:59Z&interval=15 cURL: .. code-block:: none curl "https://apps.noc-innovations.co.uk/api/polpred-api/latest/compute-time-series" \ -d key=U2uf2HSEBrDXV2jl \ -d port_name=Liverpool (Gladstone Dock) \ -d dt_start=2019-10-01T00:00:00Z \ -d dt_end=2019-10-01T23:59:59Z \ -d interval=15 \ -G Example Response: ''''''''''''''''' The response below shows results returned for Liverpool (Gladstone Dock). Here we can see the call has returned 96 total computations under the ``items`` array for the given location and time period: .. code-block:: JSON { "data": { "datum": { "name": "Mean Sea Level", "code": "msl" }, "headers": { "dt": "Date/Time", "z": "Height" }, "units": { "dt": "utc", "z": "m" }, "totalItems": 96, "items": [ { "dt": "2019-10-01T00:00:00Z", "z": 4.98302045118598 }, { "dt": "2019-10-01T00:15:00Z", "z": 4.983433895361333 }, { "dt": "2019-10-01T00:30:00Z", "z": 4.90690291094896 }, { "etc..." } ] } } Get Port List ------------- ======= ================= Syntax: ``get-port-list`` ======= ================= Get Port List is used to return all valid port names for the ``port_name`` parameter when using `Compute Port <#compute-port>`_. No licence key - or in fact any parameters - are needed to return a successful response. Parameters: ''''''''''' *None.* Special/Optional Parameters ''''''''''''''''''''''''''' *None.* Example Request: '''''''''''''''' URL: .. code-block:: none https://apps.noc-innovations.co.uk/api/polpred-api/latest/get-port-list cURL: .. code-block:: none curl "https://apps.noc-innovations.co.uk/api/polpred-api/latest/get-port-list" Example Response: ''''''''''''''''' .. code-block:: JSON { "data": { "items": [ { "name": "St. Helier", "lat": 49.18333, "lng": -2.11667 }, { "name": "St. Mary's", "lat": 49.91833, "lng": -6.31667 }, { "name": "Newlyn", "lat": 50.10333, "lng": -5.54333 }, { "name": "Plymouth", "lat": 50.36833, "lng": -4.185 }, { "name": "Weymouth", "lat": 50.60833, "lng": -2.44833 }, { "etc..." }, ] } } Compute Statistics ------------------ ======= ================= Syntax: ``compute-statistics`` ======= ================= Compute statistics is used to return various pieces of information regarding a specified point. Although a timepsan is not needed, the point given should be valid within a keys licenced boundaries. **Statistics returned**: * Highest Astronomical Tide * Mean High Water Spring * Mean High Water Neap * Mean Low Water Neap * Mean Low Water Spring * Lowest Astronomical Tide * Tide Type Value (Diurnal, Semidiurnal, Mixed) * Maximum Current Speed * Minimum Current Speed * Direction of Maximum Current Speed * Direction of Minimum Current Speed * Current Ellipse Eccentricity **Additional Resources**: * For more information on high/low water and spring/neap tides, see `the NTSLF website `_. Parameters: ''''''''''' ========== =========================================================================================== ======= Name Input Type Key/value Example ========== =========================================================================================== ======= key 16 character string ``key=Q1w2E3r4T5Y6u7I8`` lat Decimal number ``lat=50.893`` lng Decimal number ``lng=1.396`` ========== =========================================================================================== ======= Special/Optional Parameters ''''''''''''''''''''''''''' *None.* Example Request: '''''''''''''''' URL: .. code-block:: none https://apps.noc-innovations.co.uk/api/polpred-api/latest/compute-statistics?key=U2uf2HSEBrDXV2jl&lat=52.97&lng=-5.56 cURL: .. code-block:: none curl "https://apps.noc-innovations.co.uk/api/polpred-api/latest/compute-statistics" \ -d key=U2uf2HSEBrDXV2jl \ -d lat=52.97 \ -d lng=-5.56 \ -G Example Response: ''''''''''''''''' .. code-block:: JSON { "data": { "headers": { "hat": "Highest Astronomical Tide", "mhws": "Mean High Water Spring", "mhwn": "Mean High Water Neap", "mlwn": "Mean Low Water Neap", "mlws": "Mean Low Water Spring", "lat": "Lowest Astronomical Tide", "tide": "Tide Type Value (Diurnal, Semidiurnal, Mixed)", "maxc": "Maximum Current Speed", "minc": "Minimum Current Speed", "dmaxc": "Direction of Maximum Current Speed", "dminc": "Direction of Minimum Current Speed", "ec": "Current Ellipse Eccentricity" }, "items": { "hat": 1.0589, "mhws": 0.75618, "mhwn": 0.33562, "mlwn": -0.33562, "mlws": -0.75618, "lat": -1.12269, "tide": 0.18042, "maxc": 1.93476, "minc": 0.01531, "dmaxc": 193.75702, "dminc": 84.07843, "ec": 0.9843 } } }