The UKCP Application Programming Interface (API)

Going beyond the GUI: the web API

One way of making web-functionality available is to create a graphical user interface (GUI). This allows a user with a web browser to click through pages and forms in order to make requests to a service. For a tool such as UKCP, with potentially millions of outputs, the GUI approach becomes limiting when the user wants to request a large number of outputs. Equally, if the user might wish to automate requests to the service - which is very hard to achieve through a web browser.

Introducing the web API approach

An alternative interface to the web GUI is the Application Programming Interface (API). This provides a "programmatic" interface rather than a visual interface. An API can be called by a remote computer, opening up the possibility of applications, models and programmes talking to it directly.

You might consider using the web API if:

you need to make a large number of requests (such as requesting and output for every location and every variable)
you are running a computer model that requires UKCP data as an input
you are building an application that needs dynamic access to UKCP data/plots

Your API key

Your home page shows the API key attached to your account. You will need to add it to each URL when you make requests directly to the WPS API.

What does the API look like?

The easiest way to demonstrate the API is to give an example. All you need to do is build a URL with the appropriate components to define your request. Note that every time you complete a WPS request through the web GUI you are shown the URL that can be used to regenerate that request. In fact, you can even select that request and paste it into your browser in order to re-run it (provided you are logged in).

Here is an example request URL, some white space has been added to make it more legible:

                            https://ukclimateprojections-ui.metoffice.gov.uk/wps?
    service=WPS&
    request=Execute&
    version=1.0.0&
    Identifier=LS1_CDF_PDF_01&
    Format=text/xml&
    Inform=true&
    Store=false&
    Status=false&
    DataInputs=
        Area=point|245333.38|778933.24;
        Baseline=b8100;
        Collection=land-prob;
        ColourMode=c;
        DataFormat=csv;
        FontSize=m;
        ImageFormat=png;
        ImageSize=1200;
        LegendPosition=7;
        PlotType=PDF_PLOT;
        Scenario=sres-a1b;
        TemporalAverage=jul;
        TimeSlice=2050-2069;
        TimeSliceDuration=20y;
        Variable=tasAnom;&
    ApiKey=<YOUR_API_KEY>

Key parameters:

Inform This flag can be set to 'true' or 'false'. If true, an email notification will be sent when the product is ready.
DataInputs These are the values used as inputs to the job to generate the product.
ApiKey This is required when you are using the API to authorise you to use the service.

Interpreting the API response

The WPS will quickly return a response from the API is a WPS in the form of an "Execute Response" XML document. The XML document will include a "statusLocation" URL in the second line (the "ExecuteResponse" XML element). Another important component of the XML document is the "Status" element - this will indicate whether the request has been accepted, has started running or has failed.

If the status shows as "ProcessFailed" then there has been an error in interpreting your request. The "Status" element should include an error message providing some information about the issue that caused the job to fail.

Assuming the request was accepted, it will be queued or running on the UKCP WPS servers. You can copy the "statusLocation" URL and poll it in order to get an updated version of the "Execute Response" document. Again, view the "Status" element to find out the current status.

Downloading the outputs - append the API Key

Once the "Status" shows as "ProcessSucceeded" then you can proceed to download your outputs. Search the XML document for the "FileURL" elements which contain URLs that you can download the outputs from. The ".zip" outputs should be downloaded as they contain all other files listed.

Please note that you must append the following to the download URL in order to be able to download the file via the web API: ?ApiKey=<YOUR_API_KEY>

A walk-through of how to use the API key

The following steps will help get you started:

Log in to the web site and run a process
- Click on the Login link on the top right corner of the screen
- Log in
- Make a note of your API key, you will need this later
- Go to the Products page
- Select the Plume plot of time series anomaly from probabilistic UK climate projections product
- Fill in the form and then Submit it
On the job viewer page copy the URL
- When the process has finished go to the Job Details tab
- Use the embedded copy button to copy the Job Request URL
Modify the inputs as required
- Initially just keep them the same
- Later you could try changing the TimeSlice to 2000|2030 or the TimePeriod to jun
Test in the browser
- Paste the URL into a browser
- You should get an XML response telling you the job has run
- The XML includes details of the job as well as links to the outputs generated

Using the API directly from code

You can directly interact with the API via your own code. However, due to the complex interactions between the client and server (see diagram) we strongly recommend that you use the freely available UKCP API Python Client library. The example code shown below makes use of this client library:

                            from ukcp_api_client.client import UKCPApiClient
api_key = "<YOUR_API_KEY>"

cli = UKCPApiClient(outputs_dir="my-outputs", api_key=api_key)

request_url = "https://ukclimateprojections-ui.metoffice.gov.uk/wps?service=WPS&request=Execute&version=1.0.0&Identifier=LS3_Subset_01&Format=text/xml&Inform=true&Store=false&Status=false&DataInputs=TemporalAverage=jan;Area=bbox|474459.24|241777.72|486311.19|246518.35;Collection=land-rcm;ClimateChangeType=absolute;EnsembleMemberSet=land-rcm;DataFormat=csv;TimeSlice=2075|2076;Variable=psl"

file_urls = cli.submit(request_url)