Skip to end of metadata
Go to start of metadata

Concepts

  • Single REST/JSON api to all services using HTTPS
  • Same API from outside ECMWF and inside ECMWF
  • User can create their own clients
  • Client should be implementable with the standard Python libraries (httplib2, simplejson,...)

Client libraries

Location

ECWMF REST Api

The API is designed in in such a way that it can support both synchronous and asynchronous requests: if a POST returns 200 OK,  the HTTP response will contain the JSON encoded result of the request. If it returns 303 See Other, the request resource is binary (PNG, GRIB, NetCDF), and can be downloaded from the URL given in the Location header. If the response is 202 Accepted, the request is too long, and will be handled asynchronously. In this case the URL given in the Location header will point to a resource that contain the progress status of the request. You must issue GET requests on this URL until you get a return code of 200 OK or 303 See Other, depending on whether the result can be provided in a JSON encoded form, or need to be downloaded. The flowchart below illustrate the process.

HTTP Headers

When calling the ECMWF Web API, you need to be identified by providing the following HTTP headers:

HeaderValueCommentEquivalent query string
X-ECMWF-KeyXXXXX key=XXXX
FromThe email address for which the key is registered.This is only required for self-registered users.from=<email>
X-ECMWF-Options

See API Options below.

Optional.options=...

Optional query string parameters

NameValueComment

Equivalent HTTP header

methodGET, POST, DELETE, ...For client that cannot set the HTTP method.N/A
json
A valid JSON string.This will take precedence on the HTTP request body.N/A
key

See API headers above.

 X-ECMWF-Key
fromSee API headers  above. From
optionsSee API options below. X-ECMWF-Options
offset<number>For pagination: number of results to skip.N/A
limit<number>For pagination: maximum number of result to return.N/A
filter"a.b.c"For selecting the JSON element matching the path "a.b.c"N/A
callback"string"This is for JSONP support. Please see JSONP example for more information. Please note that this parameter implies setting the only200 option to 1 in the API options below.N/A

API Options

NameValueDefaultComment
json-indent
<number>0For client that cannot set the HTTP method.
only200
0 or 10If set to 1, the API will always return the HTTP status 200 OK. The codes such as 202 Accep will be specified. Please note that you may still receive errors such as 500 Internal Server Error or 404 Not Found in certain conditions. This option is automatically set to 1 for JSONP calls. If set to 1, the HTTP headers will not contain the Location header, as some proxies are confused if the Location header is set with a return code of 200 OK.

Options are provided a semi-column separated of key/value pairs:

  • Request query string: options=json-indent=4;only200=1
  • HTTP Header: X-ECMWF-Options: json-indent=4;only200=1

POST requests flowchart

rest flowchart

Synchronous request with JSON result

  MessageComment

POST /v1/services/... HTTP/1.1
Host: api.ecmwf.int
Content-Type: application/json
X-ECMWF-Key: 1234567890
From: john.smith@example.com  

{request}

Use POST to submit a request to a given service.

HTTP/1.1 200 OK
Content-Type: application/json

{result}

The result is immediately available and is given in the HTTP response body, encoded in JSON.

Asynchronous request with JSON result

 

 
  MessageComment

POST /v1/services/... HTTP/1.1
Host: api.ecmwf.int
Content-Type: application/json
X-ECMWF-Key: 1234567890
From: john.smith@example.com 
{request}
Use POST to submit a request to a given service. You must specify you api in the X-ECMWF-Key header, Self-registered users must also provide their email address in the From header.
HTTP/1.1 202 Accepted
Location: http://api.ecmwf.int/v1/services/.../42
Content-Type: application/json
Retry-After: 10
{progress}
The results are not immediately available. The service returns 202 Accepted. The Location header points to a resource that will contain progress information. The body of the HTTP response contains a progress message. The Retry-After header is set to the number of seconds the client should wait before check for the request progress again.

GET /v1/services/.../42 HTTP/1.1
Host: api.ecmwf.int
X-ECMWF-Key: 1234567890
From: john.smith@example.com  
You need to check the progress of the request by issuing a GET on the URL provided before.
HTTP/1.1 202 Accepted
Location: http://api.ecmwf.int/v1/services/.../42
Content-Type: application/json
Retry-After: 10
{progress}
If the results are still not immediately available, the service returns 202 Accepted. Please note that the Location header and Retry-After header can be change at any time, so you need to keep track of them. The body of the HTTP response contains a progress message.

GET /v1/services/.../42 HTTP/1.1
Host: api.ecmwf.int
X-ECMWF-Key: 1234567890
From: john.smith@example.com  

After a delay no less than the last value of the Retry-After header you can check the progress of the request by issuing a GET on the URL provided in the last value of the Location header.
HTTP/1.1 200 OK
Content-Type: application/json
{result}
Once the result is ready, the last GET will return 200 OK, an the result will be in the HTTP response body, encoded in JSON.

Synchronous request with downloadable binary result (PNG, GRIB,...)

 
 
  MessageComment

POST /v1/services/... HTTP/1.1
Content-Type: application/json
X-ECMWF-Key: 1234567890 
From: john.smith@example.com  
{request}
Use POST to submit a request to a given service. You must specify you api in the X-ECMWF-Key header, Self-registered users must also provide their email address in the From header.
HTTP/1.1 303 See Other
Location: http://download.ecmwf.int/.../data.grib
If the data is ready immediately, the HTTP response code is 303 See Other and the Location header contains the URL were the data can be downloaded from.

GET /.../data.grib
Host: download.ecmwf.int
X-ECMWF-Key: 1234567890 
From: john.smith@example.com  

To retrieve the data, issue a GET on the URL provided in the previous response.
HTTP/1.1 200 OK
Content-Type: application/x-grib
...GRIB message...
The resulting data will be streamed back to the client. The Content-Type header will describe the type of the data returned.

Asynchronous request with downloadable binary result (PNG, GRIB, ...)

 
  MessageComment

POST /v1/services/... HTTP/1.1
Host: api.ecmwf.int
Content-Type: application/json
X-ECMWF-Key: 1234567890 
From: john.smith@example.com  
{request}
Use POST to submit a request to a given service. You must specify you api in the X-ECMWF-Key header, Self-registered users must also provide their email address in the From header.
HTTP/1.1 202 Accepted
Location: http://api.ecmwf.int/v1/services/.../42
Retry-After: 10
{progress}
The results are not immediately available. The service returns 202 Accepted. The Location header points to a resource that will contain progress information. The body of the HTTP response contains a progress message. The Retry-After header is set to the number of seconds the client should wait before check for the request progress again.

GET /v1/services/.../42 HTTP/1.1
Host: api.ecmwf.int
X-ECMWF-Key: 1234567890
From: john.smith@example.com 
You need to check the progress of the request by issuing a GET on the URL provided before.
HTTP/1.1 200 OK
Content-Type: application/json
Retry-After: 10
{progress}
If the results are still not immediately available, the service returns 202 Accepted. Please note that the Location header and Retry-After header can be change at any time, so you need to keep track of them. The body of the HTTP response contains a progress message.

GET /v1/services/.../42 HTTP/1.1
Host: api.ecmwf.int
X-ECMWF-Key: 1234567890
From: john.smith@example.com
 

After a delay no less than the last value of the Retry-After header you can check the progress of the request by issuing a GET on the URL provided in the last value of the Location header.
HTTP/1.1 303 See Other
Location: http://download.ecmwf.int/.../data.grib
{progress}

Once the result is ready, the HTTP response code is 303 See Other and the Location header contains the URL were the data can be downloaded from.

 Please note that the body of response can still contain some progress message. This is useful when printing logging information, such as the output of the remote service that created the resulting data.

GET /.../data.grib
Host: download.ecmwf.int
X-ECMWF-Key: 1234567890
From: john.smith@example.com 

To retrieve the data, issue a GET on the URL provided in the previous response.

HTTP/1.1 200 OK
Content-Type: application/x-grib

...GRIB message...
The resulting data will be streamed back to the client. The Content-Type header will describe the type of the data returned.

 

Errors

ErrorWhenComment
400 Bad RequestIf the user provide a bad request, e.g. an invalid MARS requestThis means that the request should not be retried unmodified.
500 Internal Server ErrorSomething went wrongBut the user can retry later.

The body of the response is as follows:

{
	"error" : "Message for the user",

	// Optional stuff
	"details" : {
		 /* Where to find help about this error */
		 "url" :    "http://api.ecmwf.int/api/v1/docs/errors/400001",
		 "reason":  "Message for the programmer",
         "context": { /* Some more info, like a call stack */ }
   }
}

Pagination of results

The query params offset and limit are used to limit the size of long lists of results. Currently the lists which are limites are:

List nameContextComment
messagesdatasetsWhen querying the status of data retrievals, the JSON replies will contain the output of the retrieval task in "messages"

 

Filtering

You can select only part of a JSON reply by using the filter query parameter. If GET https://..../resource returns:

{
	"foo": {
		"bar" : [1,2,3],
		"quux" : [4,5,6]
	}
}

Then GET https://..../resource?filter=foo.bar will return:

[1,2,3]

JSONP support

ParamReplacesComment
callback=...Returns application/javascript instead of application/json, and apply the callback See jQuery for more about JSONP

 

 

 

  • No labels