Service API Details

NEANIAS A3 Atmospheric Service API

This file describes the endpoints and structure of request data to generate forecasts

Initial considerations

  • All API endpoints accept and return JSON structured data

  • All fields presented below are mandatory

  • All data relating to the content of the files must be represented in a base 64 string format

JSON forecast endpoint

Endpoint: /api/jsonforecast
Method: POST

Request:

The following fields should be present in JSON request body:

  • name

  • description

  • json_configuration

  • json_matrices

name
  • Type: string

  • Description: Representative name of the forecast

description
  • Type: string

  • Description: Forecast description

json_configuration
  • Type: string base 64

  • Description: JSON configuration represented in a base 64 string respecting the structure rules presented here

json_matrices:
  • Type: string base 64

  • Description: JSON matrices represented in a base 64 string respecting the structure rules presented here

Response in success

The following fields will be present in the response to the request if it is successful:

  • forecast_id

  • status

forecast_id
  • Type: integer

  • Description: Id with which the request was registered

status
  • Type: integer

  • Description: Request processing status

Response in failure

The following fields will be present in the response to the request if it fails:

  • message

message
  • Type: string

  • Description: Reason why request was failed

Example

Request body example:

{
 "name": "example",
 "description": "example of a JSON forecast request",
 "json_configuration": "ewogICJncmlkX2NvbnRyb2wiOiB7Ci ... QogICAgfQogIH0KfQ==",
 "json_matrices": "eyIyRCI6IHsiUFNGQyI6IHsiZGF0YS ... DM3Ny45NjI5XV1dXX19"
}

Response body example:

{
 "forecast_id": 34,
 "status": "In Queue"
}

GRIB forecast endpoint

Endpoint: /api/gribforecast
Method: POST

Request:

The following fields should be present in JSON request body:

  • name

  • description

  • grib

  • is_grib2

  • vtable

  • wps

  • input

name
  • Type: string

  • Description: Representative name of the forecast

description
  • Type: string

  • Description: Forecast description

grib
  • Type: list

  • Items type: string base 64

  • Description: GRIB files content represented in a base 64 string

is_grib2:
  • Type: boolean

  • Description: Should be TRUE if GRIB content come in grib2 format

vtable
  • Type: string base 64

  • Description: Vtable file content represented in a base 64 string

wps
  • Type: string base 64

  • Description: namelist.wps file content represented in a base 64 string

input
  • Type: string base 64

  • Description: namelist.input file content represented in a base 64 string

Response in success

The following fields will be present in the response to the request if it is successful:

  • forecast_id

  • status

forecast_id
  • Type: integer

  • Description: Id with which the request was registered

status
  • Type: integer

  • Description: Request processing status

Response in failure

The following fields will be present in the response to the request if it fails:

  • message

message
  • Type: string

  • Description: Reason why request was failed

Example

Request body example:

{
 "name": "example",
 "description": "example of a GRIB forecast request",
 "grib": ["R1JJQgAAAAIAAAAAAAA76AAAABU..., 5WLlZWDlYGVgZWLlZGVk5WRlZOV...]",
 "is_grib2": true,
 "vtable": "R1JJQjF8IExldmVsfCBGcm9tIHwgIF ... ICB8IG1ldGdyaWQgIHw",
 "wps": "JnNoYXJlCiB3cmZfY29yZSA9ICdBUl ... 3JpZCA9IDIsIAovCg==",
 "input": "JnRpbWVfY29udHJvbCAgICAgICAgIC ... CAgICAgPSAxLAovCg=="
}

Response body example:

{
 "forecast_id": 38,
 "status": "In Queue"
}

Forecast status endpoint

Endpoint: /api/forecaststatus/
Method: GET

Response if forecast processing is finished

The following fields will be present in the response to the request if it is successful:

  • forecast_id

  • name

  • description

  • status

  • output_files

forecast_id
  • Type: integer

  • Description: Id with which the request was registered

name
  • Type: string

  • Description: Representative name of the forecast

description
  • Type: string

  • Description: Forecast description

status
  • Type: integer

  • Description: Request processing status

output_files
  • Type: list

  • Items type: structure

  • Description: Information and download links of forecast result files

The following fields will be present in each output_files list structure:

  • filename

  • path

  • size

  • Type: string

  • Description: file name

  • Type: string

  • Description: url where file is available for download

  • Type: integer

  • Description: size of file in bytes

Response if forecast is still processing

The following fields will be present in the response to the request if it is successful:

  • forecast_id

  • name

  • description

  • status

forecast_id
  • Type: integer

  • Description: Id with which the request was registered

name
  • Type: string

  • Description: Representative name of the forecast

description
  • Type: string

  • Description: Forecast description

status
  • Type: integer

  • Description: Request processing status

Response request in failure

The following fields will be present in the response to the request if it fails:

  • message

message
  • Type: string

  • Description: Reason why request was failed

Example when finished

Response body example:

{
 "forecast_id": 38,
 "name": "example"
 "description": "example of a GRIB forecast status response when finished"
 "status": "Finished",
 "ouput_files": [{
    "filename": "wrfout_d01_2020-11-09_22:00:00",
    "path": "www.exampleurl.com/files/wrfout_d01_2020-11-09_22:00:00/download",
    "size": 915540
 }, {...}, ...]
}

Example when processing

Response body example:

{
 "forecast_id": 38,
 "name": "example"
 "description": "example of a GRIB forecast status response when processing"
 "status": "Running"
}