Skip to main content

Point Time-Series

Overview​

Point times-series return data for the selected variables and points across a specified time range. You can query these either by a basic GET method or by a POST request as shown below.

Example​

Request​

let url = '{{ &forecastUrl }}/point/time';

let data = {
  points: [{lon: 174.7842, lat: -37.7935}],
  variables: ['wave.height'],
  time: {
    from: '{{fromDate}}T00:00:00Z',
    interval: '3h',
    repeat: 3,
  }
};

let options = {
  method: 'post',
  body: JSON.stringify(data),
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '{{apiKey}}'
  }
};

await fetch(url, options)
    .then(response => {
      console.log('API response status:', response.status);
      return response.json();
    }).then(json => {
      console.log('API response JSON:', json);
      document.getElementById('response').innerHTML = JSON.stringify(json);
    });
curl -X 'POST' \
  '{{ &forecastUrl }}/point/time' \
  -H 'x-api-key: {{apiKey}}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [{
      "lon": 174.7842,
      "lat": -37.7935
    }],
    "variables": [
      "wave.height"
    ],
    "time": {
      "from": "{{fromDate}}T00:00:00Z",
      "interval": "3h",
      "repeat": 3
    }
  }'
# you may need to run "pip3 install requests" in your environment
from requests import post

resp = post('{{ &forecastUrl }}/point/time',
  headers={'x-api-key': '{{apiKey}}'},
  json={
    "points": [{
      "lon": 174.7842,
      "lat": -37.7935
    }],
    "variables": [
      "wave.height"
    ],
    "time": {
      "from": "{{fromDate}}T00:00:00Z",
      "interval": "3h",
      "repeat": 3
    }
  }
)

print(resp.json())
# print just values of wave height:
print(resp.json()['variables']['wave.height']['data'])

Response​

{
  "dimensions": {
    "point": {
      "type": "point",
      "units": "unknown",
      "data": [{"lon": 174.7842, "lat": -37.7935}]
    },
    "time": {
      "type": "time",
      "units": "unknown",
      "data": ["{{fromDate}}T00:00:00Z", "{{fromDate}}T03:00:00Z","{{fromDate}}T06:00:00Z"]
    }
  },
  "noDataReasons": {"GOOD": 0, "MASK_LAND": 1},
  "variables": {
    "wave.height": {
      "standardName": "sea_surface_wave_significant_height",
      "units": "meter",
      "dimensions": ["time", "point"],
      "data": [1.2897577, 1.3445014, 1.3846742],
      "noData": [0, 0, 0]
    }
  }
}

Request arguments​

points: An array of key values [{"lat:", "lon":}] geographical points in degrees. Requesting multiples points in a single request means the API will fetch the data for the points from the same model / dataset for consistancy across the points. If you choose to split your points across multiple requests the API will fetch data from different model's and more likely select the best / highest resolution model for each point. Note you get charged the same amount no matter the method you choose.

variables: An array of variables names you would your like data for.

times: An array of ISO 8601 UTC time strings you want data for. instead of times you can use time

time:

   from: a date where to start fetching data from (ISO 8601 UTC string).

   interval: the duration between data points, e.g. 1h, 3h or 12h.

   repeat: number of times to repeat the internal value for. times formula = start, start + (interval x 1), start + (interval x 2) ..., start + (interval x N repeat)

   to: a date where to stop fetching data at. Note: if you use to you won't use repeat (ISO 8601 UTC string). times formula = start, start + (interval x 1), start + (interval x 2) ..., < to

Response fields

In the response you will will see a JSON scheme similar to the layout below.

dimensions:
  point:
    type: point
    data: [{lat:, lon: }]
  time:
     type: time
     data: [t0, t1]
  noDataReasons:
    GOOD: 0
    MASK_LAND: 1
variables:
  variable.name:
    units: meter
    dimensions: [time, point]
    data: [1.2897577, 1.3445014, 1.3846742]
    noData: [0, 0, 0]

"dimensions": contains the values of dimensions selected point and time.

"noDataReasons": Is a mask descirbing why you might not get data. For instance, you might select a ocean variable, but the point you have selected is on land MASK_LAND, or is near to land and we don't have a model with data that close to land. NOTE: "GOOD": 0 will always equal zero, but no other value's order is guaranteed.

"variables": a map of the actual variable's data.

   "variable.name": see here

      "units": The units of the variable

      "data": The values of the requested variable.

      "noData": An array of flags stating if the data is valid and describes why it is. noData has a one to one index relationship with the data field.

      "dimensions": states the dimensions and shape of the variable data.

How to read the data field's data is related to the dimensions order and the each dimension's size. Often, science libaraies and files refer to this as the data's shape.

Below we give examples of the dimension's and how their size relate to the data's shape / order. t denotes time and p denotes a point:

dims: time x 2, point x 1 means you can read the data like [t1-p1,t2-p1]

dims: time x 1, point x 2 means you can read the data like [t1-p1,t1-p2]

dims: time x 1, point x 2 means you can read the data like [t1-p1,t1-p2,dt2-p1,t2-p2]

Example of noData​

Below is an example of selecting two geographical points, one in the ocean -37.7935, 174.7842 and the other on land -37.7734, 175.2158. The variable selected wave.height is an ocean variable. In the repsonse output a few things can be seen:

  • Every odd data value is null e.g. [1.099627, null, ...].
  • Every even noData value is 0 which mean the data is valid e.g. [0, 1, ...]. But every odd has a noData value, in this case if you look up noDataReasons map you will find "MASK_LAND": 1 meaning the point is on land.
  • The order of point.data in the response determind the order of the output of both data and noData.

Request

curl -X 'POST' \
  '{{ &forecastUrl }}/point/time' \
  -H 'x-api-key: {{apiKey}}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [{
      "lon": 174.7842,
      "lat": -37.7935
    },
    {
      "lon": 175.2158,
      "lat": -37.7734
    }],
    "variables": [
      "wave.height"
    ],
    "time": {
      "from": "{{fromDate}}T00:00:00Z",
      "interval": "3h",
      "repeat": 3
    }
  }'
from requests import post

resp = post('{{ &forecastUrl }}/point/time',
  headers={'x-api-key': '{{apiKey}}'},
  json={
    "points": [{
      "lon": 174.7842,
      "lat": -37.7935
    },
    {
      "lon": 175.2158,
      "lat": -37.7734
    }],
    "variables": [
      "wave.height"
    ],
    "time": {
      "from": "{{fromDate}}T00:00:00Z",
      "interval": "3h",
      "repeat": 3
    }
  }
)

print(resp.json())

Response

{
 "dimensions": {
  "point": {
    ...
   "data": [{"lon": 174.7842, "lat": -37.7935}, {"lon": 175.2158, "lat": -37.7734}]
  },
  "time": {
    ...
   "data": ["2021-08-29T00:00:00Z", "2021-08-29T03:00:00Z", "2021-08-29T06:00:00Z"]
  }
 },
 "noDataReasons": {"GOOD": 0, "MASK_LAND": 1, ...},
 "variables": {
  "wave.height": {
   ...
   "dimensions": ["time", "point"],
   "data": [1.099627, null, 1.0731194, null, 1.0428492, null],
   "noData": [0, 1, 0, 1, 0, 1]
  }
 }
}