API-reference v1

This web service aims to allow applications with access to run geography locked particle dispersion models (PADM) for running oil spill simulations.

Check what models that are available and invoke the methods marked Mandatory and Order which means you need to call the mandatory methods in the right order to be successful and to get the results out.

This version (v1) of PADM will expire at 2014-12-31. Due this date it will no longer be available, please upgrade your application before this date

Runner

Find out available models to execute

GET /model

Create a model workarea. Mandatory, Order 1

This workarea will expire after 1 hour from creation date.

POST /workarea/v1
Output: URL location of workarea

Set model version. Mandatory, Order 2

Look in the /model URL for available values.

POST /workarea/v1/{id}/op/version
Input: String padmVersion, String modelSetupVersion, String forcingVersion
Output: none

Set model setting. Mandatory, Order 3

Look in the seatrack web dialog 'Calculation parameters' for available values and use xsd below.

Note that some fields in xsd are special, like outlet type. Possible values for outlet type are:

POINT, which matches exactly 1 coordinate (see setting coordinates below)
LINE, which matches min 2, 500 max coordinates)
AREA, which matches min 3, 500 max coordinates

Start and End fields must match with models available fields and max 10 days simulation. See forcing section.

POST /workarea/v1/{id}/op/setting
Input Content-type: application/xml using xml-schema-setting
Output: none

Set model coordinates. Mandatory, Order 4

WGS84 Latitude and Longitude values, use xsd below. Note that the number of coordinates must match outlettype field in setting xml above.

POST /workarea/v1/{id}/op/coordinates
Input Content-type: application/xml using xml-schema-coordinates
Output: none

Example, using curl, for creating a workarea, setting model version, setting and coordinates:

We assume that the base url is https://padm.smhi.se
We assume that the result workarea Id = a0a280f8-4e0c-4877-86d8-afe26e1a908e
We assume that the start and end dates are valid

1) curl -u user:pwd -X POST -v https://padm.smhi.se/workarea/v1

2) curl -u user:pwd -X POST -v -d 'padmVersion=NS03_HIRLAM_2.6&modelSetupVersion=NS03_HIRLAM&forcingVersion=NS03_HIRLAM' https://padm.smhi.se/workarea/v1/a0a280f8-4e0c-4877-86d8-afe26e1a908e/op/version

3) curl -u user:pwd -v -X POST -H 'Content-type: application/xml' -d '<simulation> <continuedCase>false</continuedCase> <changeCenterPosition>false</changeCenterPosition> <changeCenterPositionLat></changeCenterPositionLat> <changeCenterPositionLon></changeCenterPositionLon> <forecastMethod>HIRLAM</forecastMethod> <outletType>AREA</outletType> <forwardCalculation>true</forwardCalculation> <start>2011-11-13 00:00:00</start> <end>2011-11-15 00:00:00</end> <calculationType>Oil classes</calculationType> <substance>Medium oils (100-1000 cSt)</substance> <fresh>true</fresh><winddrag>0.00</winddrag> <outletPoints>3</outletPoints> <depth>0</depth> <instantaneous>true</instantaneous> <amount>100</amount> <amountUnit>m3</amountUnit> <duration>24</duration> <durationUnit>hours</durationUnit> <prescribedCurrent>false</prescribedCurrent> <uncertainty>false</uncertainty> <calculationMode>Normal</calculationMode> </simulation>' https://padm.smhi.se/workarea/v1/a0a280f8-4e0c-4877-86d8-afe26e1a908e/op/setting

4) curl -u user:pwd -v -X POST -H 'Content-type: application/xml' -d '<coordinates> <coordinate> <latitude>58.417118072509766</latitude> <longitude>19.15887451171875</longitude> </coordinate> <coordinate> <latitude>58.396942138671875</latitude> <longitude>19.311656951904297</longitude> </coordinate> <coordinate> <latitude>58.338314056396484</latitude> <longitude>19.394878387451172</longitude> </coordinate> </coordinates>' https://padm.smhi.se/workarea/v1/a0a280f8-4e0c-4877-86d8-afe26e1a908e/op/coordinates

Get a list of model simulation files

GET /workarea/v1/{id}
Output: text list of files

Get a model simulation file

GET /workarea/v1/{id}/{filename}
Output: output file stream

Run a model simulation. Mandatory, Order 5

Used for running a model simulation.

POST /runner/v1
Input: workareaId
Output: none

Get a model process status.

This is the preferred resource for checking execution status of model process

GET /runner/v1/{id}
Output: Response will be 200 and execution status text which be one of the following:

INITIAL model process starting up
PARTIAL model process is running but not done
ERROR model process has error
COMPLETE model process is complete and successful

Get a model simulation result status.

This is the preferred resource for checking simulation progress

GET /workarea/v1/{id}/op/resultfileStatus
Output: Model result status text as a datetime string

Repository

Store model simulation result into repository. Mandatory, Order 6

Default expire date 3 hours. Expired results will be deleted from system.

POST /repository/v1
Input: workareaURI
Optional input: reporitoryId (used for storing results to fixed location)
Output: URL repository location.

Example 1:
 calling https://padm.smhi.se/repository/v1
with
workareaURI = https://padm.smhi.se/workarea/v1/a0a280f8-4e0c-4877-86d8-afe26e1a908e
gives
https://padm.smhi.se/repository/v1/a0a280f8-4e0c-4877-86d8-afe26e1a908e

Example 2:
 calling https://padm.smhi.se/repository/v1
with
workareaURI = https://padm.smhi.se/workarea/v1/a0a280f8-4e0c-4877-86d8-afe26e1a908e
and
repositoryId = bbb280f8-4e0c-4877-86d8-afe26e1a908e
gives
https://padm.smhi.se/repository/v1/bbb280f8-4e0c-4877-86d8-afe26e1a908e

Get a model simulation clouds

GET /repository/v1/{id}
Output: text list of cloud resource URIs

Get expire date of this repository simulation

GET /repository/v1/{id}/expire
Output: text date

Set expire date, max 2 years into the future.

Expired results will be deleted from system.

POST /repository/v1/{id}/op/expire
Input: date
Output: none

Get a model simulation result cloud. Mandatory, Order 7

Used to get the simulation results as xml.
GET /repository/v1/{id}/cloud/{cloudnr}
Output Content-type: application/xml using xml-schema-result

Get a model simulation results setting

GET /repository/v1/{id}/setting
Output Content-type: application/xml using xml-schema-setting

Get a model simulation results table

GET /repository/v1/{id}/table
Output Content-type: application/xml using xml-schema-setting

Forcing

Get available dates for model forcing, display text.

Use the forcing version found under /model.

GET /forcing/v1/{forcingVersion}/displayText
Input: forcing version
Output: Readable text of available dates

Get available dates for model forcing, dates.

Use the forcing version found under /model.

GET /forcing/v1/{forcingVersion}/availableTimes
Input: forcing version
Output: Comma seperated text availableFrom date, availableTo date

Extras

Java client, examples and with Java doc. Use wget, curl or similar to get the jar otherwise it seems to get corrupted when downloading through a browser.
Schema for setting input
Schema for coordinates input
Schema for cloud simulation result