Skip to main content

Models

Each model in our API is a collection of datasources representing the output of a particular forecast model over a period of time.

Metadata​

The /modelsumamries/ endpoint provides a brief overview of model available to you as metadata.

The /models/ endpoint lists the name of each model available to you, and full metadata details of those models are available from /models/\{model-name\}.

Model Selection​

When you make an API call to the /point, /point/time, /route/time, or /route/speed endpoints, the models used to produce a response will be selected from either the full set of models available at the access level of your API key, or a subset of those models as specified by the models or kind request parameters.

The API selects the most suitable models per requested variable. Except for /point, data from multiple models may be combined within a variable. In the case of /point/time this is controlled by the joinModels parameter. In the case of the route endpoints, it is not configurable. You can also split one request covering a large area into multiple requests covering smaller regions in time or space if you need more control. Data from models is taken in order, for each requested variable, for as much of the requested time range as possible.

  • The /point endpoint has no time data to consider so the single highest-ranked model is selected per variable.

  • The /point/time endpoint has cycle-locking enabled and joinModels set to true by default. When both are disabled, it selects the highest-ranked model per variable.

  • Both /route endpoints may join data from multiple models within each variable. Conceptually, these endpoints make little sense without that behaviour.

Cycle locking​

By default, the API considers batches of data from different models by the time the base stack was run. We call this a cycle. Models with a different stack are considered separately.

Within a group of variables with a selected stack, the most recent cycle with non-zero coverage will be used for all variables in that group, unless the cycle immediately prior to that has a finer average spatial resolution, in which case the latter cycle will be used. Within that cycle, the models with the best spatial resolution will be selected per variable. Ties are broken first by exact time coverage and then model ranking.

This means all atmospheric variables are locked to one cycle of one stack and all wave variables are locked to one cycle of a different stack.

Hydrodynamic and spatial variables do not have a configurable stack so they are considered separately. When cycle locking is enabled, the API will prefer to return these variables from a single cycle where possible, but may choose different stacks or different cycles within a stack for different variables if that provides better coverage.

The default behaviour described above is also the case when the cycleLock parameter is set to group, but there are other options:

  • stack: Models selected for variable groups with the same configured stack are locked together. For example, if you select the gfs stack for both atmospheric and wave variable groups, all variables from both groups must select models from the same cycle.
  • variable: Models selected for individual variables are locked to the same cycle, regardless of what group they are in or what stack has been configured for that group. Like group and stack, this does not apply to hydrodynamic or spatial variables.
  • none: Cycle locking is completely disabled and model order is determined purely by model ranking.

Smoothing​

By default, the joinModels request parameter for /point/time is set to true. In addition to false, which means only the single best model will be used for each variable, it may also be set to smooth. In this case, the API may use overlaps in the time domain between some models to smooth the boundaries between those models within each variable. Even when set to smooth, it may not apply to all variables or all model boundaries within a given variable - it depends on the type of variable and which specific models are used.

Model sorting​

To be considered as a candidate for a given request, a model must meet some criteria:

  • For /point requests, a model must cover all requested points.
  • For /point/time requests, a model must cover all requested points and at least one requested or inferred time.
  • For both types of /route request, a model must cover at least one requested or inferred point-time pair.

After that, where any candidate models overlap in time, the model to use data from is chosen in order determined by several factors:

  • Priority, the model priority key.
  • Area, the spatial area the model covers. By default, smaller, more local, domains are preferred.
  • Time resolution, the mean interval between time samples in a model run.
  • Spatial resolution, the mean product of longitudinal and latitudinal resolution.

The order in which these are used and whether small or large values are preferred is configurable with the modelSort parameter, but you should very rarely need to use this. If all these are equal, the tie is broken first by approximate time coverage and finally by model name.