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 The 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:

https://apps.noc-innovations.co.uk/api/polpred-api/latest/get-licences?key=U2uf2HSEBrDXV2jl

cURL:

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 Demonstration Key available. Here we can see the 1 licence available:

{
  "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. 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).

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. By default, data is computed using Mean Sea Level (MSL). Currently the two data options are MSL and Lowest Astronomical Tide (LAT).	`datum=lat`
licence_ids	You can manually specify which licences are used in 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	`licence_ids=0&licence_ids_2`

Example Request:¶

URL:

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:

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 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:

{
  "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.

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.

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.

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 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.

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. By default, data is computed using Mean Sea Level (MSL). Currently the two data options are MSL and Lowest Astronomical Tide (LAT).	`datum=lat`
licence_ids	You can manually specify which licences are used in 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	`licence_ids=0&licence_ids_2`
include_land	Specify whether points spanning over land are included in 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.	`include_land=1`

Example Request:¶

URL:

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:

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). 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 for more details.

{
  "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) 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. By default, data is computed using Mean Sea Level (MSL). Currently the two data options are MSL and Lowest Astronomical Tide (LAT).	`datum=lat`

Example Request:¶

URL:

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:

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:

{
  "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.

No licence key - or in fact any parameters - are needed to return a successful response.

Parameters:¶

None.

Special/Optional Parameters¶

None.

Example Request:¶

URL:

https://apps.noc-innovations.co.uk/api/polpred-api/latest/get-port-list

cURL:

curl "https://apps.noc-innovations.co.uk/api/polpred-api/latest/get-port-list"

Example Response:¶

{
  "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:

https://apps.noc-innovations.co.uk/api/polpred-api/latest/compute-statistics?key=U2uf2HSEBrDXV2jl&lat=52.97&lng=-5.56

cURL:

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:¶

{
  "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
    }
  }
}