Response

In case of success, the response is a JSON formatted text with the following structure :

{
  "timezone": <string>,
  "longitude": <float>,
  "latitude": <float>,
  "forecast": [ <ForecastPoint>, ... ],
  "warnings": [ <Warning>, ... ],
  "errors": [ <Error>, ... ],
  "metadata": <Metadata>
}

The fields "warnings", "errors" and "metadata" could not be present.

The returned timezone value can be null in case the timezone could not be infered from the specified location.

<ForecastPoint> Object

The <ForecastPoint> objects are the essence of the response as they are precisely the ones containing the forecast data. Each <ForecastPoint> object contains the values of the different weather measures listed in the Variables section (or a subset depending on what variables were passed in the query string) at the location specified in the query string and at a particular moment. Here is an example :

{
  "timestamp": {
    "unix": 1483704000,
    "localTimestamp": "2017-01-06T12:00:00Z"
  },
  "windGust": 5.1000000000000005,
  "windSpeed_10m": 5.1684136831333465,
  "windDirection_10m": 204.58157448256867,
  "windSpeed_200hPa": 17.203778654702578,
  "windDirection_200hPa": 330.00726539900563,
  "windSpeed_300hPa": 20.175727991822253,
  "windDirection_300hPa": 341.2058346955275,
  "windSpeed_925hPa": 2.640549185302179,
  "windDirection_925hPa": 198.77803322244554,
  "pressure": 103789.4625,
  "totalCloudCover": 49,
  "temperature_2m": 279.1,
  "temperature_500hPa": 249.9,
  "temperature_850hPa": 271.1
}

If some measure is not applicable at the specified location (for example "primaryWaveDirection" is not applicable for a land location), then we return the value "N/A" for that measure.

If some measure is not available at the specified time and location (the weather model doesn't go that far for example), then we return the value "MISSING" for that measure.

<Warning> Object

The <Warning> objects indicate some issues that we encoutered when processing the request but that are non-critical and therefore do not prevent the forecast from being computed. They are always a consequence of the request arguments and can often (the exception is the for "unknown_timezone" warning) be fixed by tweaking the request. Here are the possible warnings that can be thrown :

Here is an example :

{
  "type": "horizon_too_high",
  "message": "Provided horizon : 10,d is higher than maximum allowed value for horizon, using 7,d instead"
}

<Error> Object

The <Error> objects indicate some issues we encoutered when processing the forecast and that caused to forecast to be only partially computed. Here are the errors that can be thrown :

Here is an example :

{
  "type": "ignored_variable",
  "variable": "pressure",
  "message": "Variable : 'pressure' was omitted in the response because no data was available at the specified location for the specified horizon"
}

<Metadata> Object

The <Metadata> object contains information about the values that are contained in the <ForecastPoint> objects. As of right now, for each measure present in the <ForecastPoint> objects you will find the corresponding unit and weather model (and its running time) in the <Metadata> object. Here is an example :

{
  "windGust": {
    "unit": "m s-1",
    "model": "gfs_0_5",
    "runtime": "2017-01-11T06:00:00Z"
  },
  "windSpeed_10m": {
    "unit": "m s-1",
    "model": "gfs_0_5",
    "runtime": "2017-01-11T06:00:00Z"
  }
}

Note that the models depicted here are not the definitive models that will be used in practice. The choice of the models will be determined based on the specified location and may differ from one measure to the other.

Reponse in case of Error

In case of error, the response has the following JSON structure :

{
  "error": {
    "message": <string>,
    "query": <Query>
  }
}

<Query> Object

The <Query> object is only present when an error occurred during the computation and its sole purpose is to help debugging. Its content will be the query string that was passed in the GET request. Here is an example :

{
  "token": "SOME_AUTHORIZED_TOKEN",
  "longitude": "4.533706",
  "latitude": "50.711665",
  "horizon": "10,a"
}

HTTP Status Codes