Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
370 lines (315 sloc) 9.71 KB

API

Tawhiri provides a simple API for requesting predictions. The current API version is Version 1.

Version 1

API Endpoint

There is a single endpoint, http://predict.cusf.co.uk/api/v1/, to which GET requests must be made with request parameters in the query string.

Profiles

Tawhiri supports multiple flight profiles which contain a description of the model chain to be used when predicting a specific flight type.

Tawhiri currently supports the following profiles:
  • Standard Profile - standard_profile
  • Float Profile - float_profile

Standard Profile

A profile for the standard high altitude balloon situation of ascent at a constant rate followed by burst and subsequent descent at terminal velocity under parachute with a predetermined sea level descent rate.

The API refers to this profile as standard_profile.

Float Profile

A profile for the typical floating balloon situation of ascent at constant altitude to a float altitude which persists for some amount of time before stopping. Descent is not predicted when using this profile.

The API refers to this profile as float_profile.

Requests

The following parameters are accepted for all requests to the predictor API. In addition, each profile accepts various additional parameters.

Parameter Required Default Value Description
profile optional standard_profile The profile to use for this prediction.
dataset optional The latest dataset. The dataset to use for this prediction formatted as a RFC3339 timestamp.
launch_latitude required   Launch latitude in decimal degrees. Must be between -90.0 and 90.0.
launch_longitude required   Launch longitude in decimal degrees. Must be between 0.0 and 360.0.
launch_datetime required   Time and date of launch formatted as a RFC3339 timestamp.
launch_altitude optional Defaults to elevation at launch location looked up using Ruaumoko. Elevation of launch location in metres above sea level.

Standard Profile

The standard profile accepts the following parameters in addition to the general parameters above.

Parameter Required Default Value Description
ascent_rate required   The ascent rate of the balloon in metres per second. Must be greater than 0.0.
burst_altitude required   The burst altitude of the balloon in metres above sea level. Must be greater than the launch altitude.
descent_rate required   The descent rate of the balloon in metres per second. Must be greater than 0.0.

Float Profile

The float profile accepts the following parameters in addition to the general parameters above.

Parameter Required Default Value Description
ascent_rate required   The ascent rate of the balloon in metres per second. Must be greater than 0.0.
float_altitude required   The float altitude of the balloon in metres above sea level. Must be greater than the launch altitude.
stop_datetime required   Time and date to stop the float prediction formatted as a RFC3339 timestamp. Must be after the launch datetime.

Responses

Responses are returned in JSON and consist of various fragments. Successful responses contain request, prediction and metadata fragments. Error responses contain error and metadata fragments only.

The predictor API returns HTTP Status Code 200 OK for all successful predictions.

Request Fragment

The request fragment contains a copy of the request with any optional parameters filled in. If the latest dataset is being used, its timestamp is included. The API version is also included.

Example:

"request": {
  "ascent_rate": 5.0,
  "burst_altitude": 30000.0,
  "dataset": "2014-08-19T12:00:00Z",
  "descent_rate": 10.0,
  "launch_altitude": 0,
  "launch_datetime": "2014-08-19T23:00:00Z",
  "launch_latitude": 50.0,
  "launch_longitude": 0.01,
  "profile": "standard_profile",
  "version": 1
}

Prediction Fragment

The prediction fragment consists of a list of stages according to the profile in use. Each stage has a name and a trajectory. The trajectory is a list of points. A point consists of a latitude (decimal degrees), a longitude (decimal degrees), an altitude (metres above sea level) and a datetime (RFC3339 timestamp).

Profile Stages
standard_profile ascent, descent
float_profile ascent, float

Example (truncated for brevity):

"prediction": [
  {
    "stage": "ascent",
    "trajectory": [
      {
        "altitude": 0.0,
        "datetime": "2014-08-19T23:00:00Z",
        "latitude": 50.0,
        "longitude": 0.01
      },
      {
        "altitude": 29997.65625,
        "datetime": "2014-08-20T00:39:59.53125Z",
        "latitude": 50.016585320900354,
        "longitude": 1.0037172612852707
      }
    ]
  },
  {
    "stage": "descent",
    "trajectory": [
      {
        "altitude": 29997.65625,
        "datetime": "2014-08-20T00:39:59.53125Z",
        "latitude": 50.016585320900354,
        "longitude": 1.0037172612852707
      },
      {
        "altitude": 69.78466142247058,
        "datetime": "2014-08-20T01:02:50.625Z",
        "latitude": 50.01827279347765,
        "longitude": 1.2934223933861644
      }
    ]
  }
]

Metadata Fragment

The metadata fragment contains start_datetime and complete_datetime which are RFC3339 formatted timestamps representing the time and date when the prediction was started and completed.

Example:

"metadata": {
  "complete_datetime": "2014-08-19T21:32:52.036925Z",
  "start_datetime": "2014-08-19T21:32:51.929028Z"
}

Error Fragment

The API currently outputs the following types of errors in the error fragment:

Type HTTP Status Code Description
RequestException 400 Bad Request Returned if the request is invalid.
InvalidDatasetException 404 Not Found Returned if the requested dataset is invalid.
PredictionException 500 Internal Server Error Returned if the predictor's solver raises an exception.
InternalException 500 Internal Server Error Returned when an internal error occurs.
NotYetImplementedException 501 Not Implemented Returned when the functionality requested has not yet been implemented.

Example:

"error": {
  "description": "Parameter 'launch_datetime' not provided in request.",
  "type": "RequestException"
}

Full Examples

Successful Standard Prediction

Request:

$ curl "http://predict.cusf.co.uk/api/v1/?launch_latitude=50.0&launch_longitude=0.01&launch_datetime=2014-08-20T00%3A00%3A00%2B01:00&ascent_rate=5&burst_altitude=30000&descent_rate=10"

Response (prediction truncated for brevity):

{
  "metadata": {
    "complete_datetime": "2014-08-19T21:32:52.036925Z",
    "start_datetime": "2014-08-19T21:32:51.929028Z"
  },
  "prediction": [
    {
      "stage": "ascent",
      "trajectory": [
        {
          "altitude": 0.0,
          "datetime": "2014-08-19T23:00:00Z",
          "latitude": 50.0,
          "longitude": 0.01
        },
        {
          "altitude": 29997.65625,
          "datetime": "2014-08-20T00:39:59.53125Z",
          "latitude": 50.016585320900354,
          "longitude": 1.0037172612852707
        }
      ]
    },
    {
      "stage": "descent",
      "trajectory": [
        {
          "altitude": 29997.65625,
          "datetime": "2014-08-20T00:39:59.53125Z",
          "latitude": 50.016585320900354,
          "longitude": 1.0037172612852707
        },
        {
          "altitude": 69.78466142247058,
          "datetime": "2014-08-20T01:02:50.625Z",
          "latitude": 50.01827279347765,
          "longitude": 1.2934223933861644
        }
      ]
    }
  ],
  "request": {
    "ascent_rate": 5.0,
    "burst_altitude": 30000.0,
    "dataset": "2014-08-19T12:00:00Z",
    "descent_rate": 10.0,
    "launch_altitude": 0,
    "launch_datetime": "2014-08-19T23:00:00Z",
    "launch_latitude": 50.0,
    "launch_longitude": 0.01,
    "profile": "standard_profile",
    "version": 1
  }
}

Missing Parameters

Request:

$ curl "http://predict.cusf.co.uk/api/v1/?launch_latitude=50.0&launch_longitude=0.01"

Response:

{
  "error": {
    "description": "Parameter 'launch_datetime' not provided in request.",
    "type": "RequestException"
  },
  "metadata": {
    "complete_datetime": "2014-08-19T21:40:08.697297Z",
    "start_datetime": "2014-08-19T21:40:08.697059Z"
  }
}