EMD-API: EMD-WRF On-Demand

2023-05-23 - NOTE: This page is describing a system in beta-release. It has not been released for general use yet.

Introduction

The EMD-API: EMD-WRF On-Demand is a part of EMD-API. It provides a unified interface to the EMD-WRF mesoscale on-demand services (see here and here). The service is aimed at detailed time-series analysis. EMD-API helps consultants, analysts and scientists working with high-resolution climate data in achieving their goals in an efficient way. It has the following key-features:

• Global data delivery: All models in the EMD-API: EMD-WRF On-Demand has a global footprint - so you can make your calculations virtually everywhere.
• On-demand calculation: Calculations are executed on-demand at the high-performance computing (HPC) facilities at EMD
• Multiple model configurations: EMD-API: EMD-WRF On-Demand provides access more multiple model configurations aimed at single points, larger areas - and even a special configuration aimed at icing calculations with full reporting.
• Unified interface: The unified interface which allows for integration to internal processes and tools.
• Trusted datasets: EMDAPI builds upon the trusted data-bases and data-sources that have been used through the online-data services in windPRO for more than a decade.
• Built on open standards: EMDAPI is a REST based service that implements the OpenAPI standard].
• Available from any development tool: Access to the climate databases is available from your preferred development platform - C#, R, python, html, java, php, scala and swift. Just use the OpenAPI tools to generate the client software for your preferred platform.

In order to use the EMD-API: EMD-WRF On-Demand, you will need to:

1. Have an API access token for your user and company account. Note: Your access token is personal and will allow to operate through the EMD-API. You can browse/view credit-status and pending calculations for your company in read-only model
2. Have some calculation credits on your account (a calculation credit corresponds to one month of mesoscale time-series data in the standard 1-point model configuration)

Access

To see more documentation and to access the data-services, please visit the API through the following URL's:

• EMD-API Overview (Wiki) - here.
• EMD-API Main Page (API) - here.
• EMD-API Climate Data UI (API) - here.

Any technical questions on our climate databases can be addressed to our Senior Technical Specialist - Morten Lybech Thøgersen: mlt@emd.dk.

Data Model - EMD-API: EMD-WRF On-Demand

The EMD-API: EMD-WRF On-Demand -services is documented in a REST based API using the OpenAPI Specification. You can view the interfaces and download the interfaces as json or yaml, here. The service provides the following functionality:

• List Models: Full list of available EMD-WRF On-Demand model configurations including their ID’s and other meta-data
• Information on used and purchased credits: Request information of completed, cancelled or pending calculations for your company account.
• Place Order: Order a mesoscale time-series data for any location whith any model (dataset) - given any latitude-longitude location). You can decide which period to download.
• Order Status: Request progress for a specific order - and eventually recieve the download URL for the order. Options: [PENDING, CANCELLED OR SUCCESS].,
• Cancel Order: Cancel an order that has not started yet (status must be PENDING)

Python - Installation and Example Code

These examples privides a demonstration on how to use the EMD-API: EMD-WRF On-Demand with python installed in a virtual environment. If you are using CONDA or MINICONDA, we recommend that you create a new virtual environment and use a recent 3.x version of python. When the virtual environment is created, then activate the environment.

Open your Anaconda Prompt. Copy-paste the following lines:

conda create -n emdapiclient_emdwrfod python=3.8
conda activate emdapiclient_emdwrfod

Install the required packages needed in order to use the EMD-API: EMD-WRF On-Demand interface use the examples further below on this page. We have tried to keep dependicies at a minumum.

In the Anaconda Prompt, copy-paste the following line, one by one:

conda install -c conda-forge pandas requests tabulate

Python - Example Code

In order to test your setup and learn to use the EMD-API: EMD-WRF On-Demand, we suggest that you download and run the three examples that we have created - here.
Unpack the zip files, activate your python environment and run the command below in your integrated-environment, terminal or command-shell.

Then work your way through through each example provided. Each of the three python samples holds a specific focus:

1. emdwrfod_example_status.py: Status and overview of user-request and past-calculations.
2. emdwrfod_example_order_submit.py: Submit a calculation.
3. emdwrfod_example_order_check.py: Check calculation status and retrieve data from one or more calculations.

Client Software Other Languages and Tools

REST and OpenAPI is easily consumed from a lot of software tools. It is perfectly possible that your preferred language is supported. OpenAPI works well with languages such as - but not limited to - C#, R, python, java, php, scala and swift. Just download the YAML or JSON service description and use the Swagger Editor or OpenAPI Generator to generate the client libraries for your preferred software. Then you are ready to integrate towards your preferred systems and workflows.

To generate the client libries yourself - one possible process is to:

1. Download the OpenAPI (openapi.yaml or openapi.json) description files - here-yaml or here-json
2. Load it into the swagger editor - here
3. Choose to "Generate Client" from the drop-down menu within the swagger editor.