Data model and licences

The five fields every row carries

Every data row an agency tool returns, every point of a time series and every line of the risk index CSV carries the same five provenance fields, so a value can always be traced and cited:

Scales

• regional: a value of a regional model cell (ocean, wave or weather model) or an aggregate over a bay (bay signal aggregates, bay events, the risk index, skill). A model cell can sit several kilometres from a site.
• satellite: a satellite pixel or composite (chlorophyll-a, sea-surface temperature, turbidity), with cloud gaps.
• site: a measurement at a site or a ground-truth station (buoy, tide gauge), or a per-site signal.

Lead time

lead_hours says how far ahead of its issue a value was made: null for an observation or a dated event (nothing was predicted), 0 for an analysis (the model's best estimate of a past or present state), above 0 for a forecast (hours between the issue and the valid time). For a bay aggregate it is the smallest lead among the contributing values, so a day that mixes analysis and forecast reads as analysis only when every site has one. Signals also carry issued_at, the run they came from, and the latest issued run for a day wins when several exist.

The dataset registry

GET https://coastal-intelligence.triskelionaisystems.com/api/datasets (no key needed) lists every dataset the service reads: its registry key (which is the product of its rows), the provider's product and dataset ids, the variables requested, depths, scale, frequency, whether it is a forecast, DOI and URL, the licence and the attribution line with the DOI and year filled in. Shape, with placeholders:

{
  "generated_at": "<ISO 8601>",
  "datasets": [
    {
      "key": "<dataset key, the product of its rows>",
      "section": "<registry section>",
      "source": "<source of its rows>",
      "product": "<provider product id>",
      "dataset_id": "<provider dataset id | null>",
      "variables": [
        "<provider variable>"
      ],
      "depths_m": "<[number] | null>",
      "scale": "regional | satellite | site",
      "frequency": "<ISO 8601 duration | null>",
      "forecast": "<boolean>",
      "grid_deg": "<number | null>",
      "doi": "<DOI | null>",
      "url": "<url | null>",
      "verified": "<YYYY-MM-DD | null>",
      "licence": "<licence id>",
      "attribution": "<the attribution line with the DOI and year filled in>"
    }
  ],
  "licences": [
    {
      "id": "<licence id>",
      "name": "<name>",
      "provider": "<provider>",
      "url": "<url>",
      "attribution": "<template>",
      "sections": [
        "<section>"
      ]
    }
  ]
}

With a key, describe_datasets (GET /agency/datasets) returns the same registry as agency rows, each with in_scope (whether your key may read that dataset) and attribution_line; it is the list of valid product values for get_timeseries.

Licence ids and the attribution each requires

Every licence id that can appear in a row, with the attribution line it requires. The DOI list in a line names every dataset of that provider the service reads; cite the one(s) behind the rows you use, or the whole line.

Plain-language guidance on what the licences ask of you: Licences and attribution in the help knowledge base.

Products

A product is what an access request names and a key is approved for. The derived families are fixed; every dataset key of the registry is a product too (the request form and GET /datasets list them). Operator record sources are never a product.

How a key's products, bays, aggregation and date range are checked: Authentication and keys.