File Download API

ERROR

JavaScript must be enabled.

A REST based API is available for data downloaders who wish to script the downloading of files.

Prerequisites

For some datasets, you must be a user who has been granted permissions or have group membership to download a dataset. Api tokens are used to provide authorization.

Other datasets are open access and don't require authorization via api tokens.

Authentication

The API supports API Tokens over SSL.

Your API Token can be sent via an HTTP Header or an HTTP Query Parameter. In both cases the header name or query parameter is named 'api-token'.

Download a File from a Dataset

Below is an example curl command to download a file from a dataset with the short name "CPL_MAR".

The -o or --output curl option allows you to give the downloaded file a different name.

In this example your API token is sent via an HTTP header attribute.

$ curl -v --header "authorization: api-token <api-token>" https://<host-name>/api/v1/dataset/CPL_MAR/file/filename.json -o ./<local_file.ext>"

To send your API token via an HTTP query parameter at the end of the url.

$ curl -v -o ./<file_name.ext> https://<host-name>/api/v1/<dataset-short-name>/file/file.json?api-token=<api-token>

If you were to download a file named "readme.txt" from a dataset with an api-token of 1234567890.

$ curl -v --header "authorization: api-token 1234567890" https://www.earthsystemgrid.org/api/v1/dataset/ncl.630.0/file/readme.txt

$ curl -v https://www.earthsystemgrid.org/api/v1/dataset/ncl.630.0/file/readme.txt?api-token=1234567890

A successful Download will show "200 OK" in the response: HTTP/1.1 200 OK

Download File from a Dataset Version

Files can be downloaded from a specific dataset version. The dataset version is identified by its dataset short name plus the dataset version identifier.

Below is an example curl command to download a file from a specific dataset version with the api-token as a parameter

$ curl -v -o ./<local_file.ext> https://<host-name>/api/v1/dataset/<dataset-short-name>/version/<dataset-version-identifier>/file/<filename.ext>?api-token=<api-token>

Below is an example curl command to Download a specific version of a file (2.1) from a dataset with the short name "CPL_MAR".

In this example your API Token is sent via an HTTP Header Attribute.

$ curl -v --header "authorization: api-token <api-token>" -o ./<local_file.ext> https://<host-name>/api/v1/dataset/CPL_MAR/version/2.1/file/filename.json

If you were to Download a file named "readme.txt" from your dataset version "2.0" with an api-token of 1234567890.

$ curl -v --header "authorization: api-token 1234567890" https://www.earthsystemgrid.org/api/v1/dataset/ncl.630.0/version/2.0/file/readme.txt

A successful download will show "200 OK" in the response: HTTP/1.1 200 OK

Debugging

You will get extensive other logging if using the curl verbose flag "-v".