MOLES API End Points

This page details the various API endpoints for MOLES.

In this article

Catalogue API Server

Though the API end points can be accessed via the main catalogue site (catalogue.ceda.ac.uk) a dedicated API server is also available which should be used to support bulk API calls to avoid over burdening the main catalogue service. This is available at:
http://api.catalogue.ceda.ac.uk/

RESTful API (api/v2)

A full RESTful API has been provided for most MOLES object classes. As this is built within Django the service supports standard Django arguments. See Django RESTApi online documentation and each class object under the URL below for details on how to use each class endpoint.

URL: http://api.catalogue.ceda.ac.uk/api/v2/

Legacy Lookup

MOLES1, MOLES2 URL look-up service for use by Apache server. Takes OLD URL and does a look-up to find which MOLES3 record the previous identifier has been recorded on. This is then returned to allow an appropriate redirect response to be sent to the

URL: http://api.catalogue.ceda.ac.uk/api/legacy_lookup/?identifier={url_to_check}

Example:

User requests http://badc.nerc.ac.uk/view/badc.nerc.ac.uk__ATOM__obs_11734597270316948

Apache script submits this to API call as:

http://api.catalogue.ceda.ac.uk/api/legacy_lookup/?identifier=http://badc.nerc.ac.uk/view/badc.nerc.ac.uk__ATOM__obs_11734597270316948

Request:

Is a url with the MOLES1/MOLES2 URL passed as an argument

Name Type Required Default Options Notes
identifier String Yes empty

Response:

Is a json object with the following fields:

Response Name Type Notes
body url String MOLES3 record URL corresponding to the requested MOLES1/MOLES2 URL
identifier String MOLES1/MOLES2 URL requested by the user
identifierType String type of identifier as recorded in MOLES3: one of moles1_url moles2_url

Positive Response:

{"url": "http://catalogue.ceda.ac.uk/uuid/5a1076bffc8c4c5d8a2ff3a4cfb29846", "identifier": "http://badc.nerc.ac.uk/view/badc.nerc.ac.uk__ATOM__obs_11734597270316948", "identifierType": "moles2_url"}

Negative Response

{"url": "UNKNOWN", "identifier": "", "identifierType": "UNKNOWN"}

Path To Record Lookup

Attempts to return the required Observation/Collection record for a given path in the archive where a definitive answer can be provided

URL: http://api.catalogue.ceda.ac.uk/api/v0/obs/get_info/{path}

Example: http://api.catalogue.ceda.ac.uk/api/v0/obs/get_info/badc/ukmo-midas/data/GL

Request:

Is a url with a CEDA Archive path

Name Type Required Default Options Notes
path String Yes empty

Response:

Is a json object with the following fields:

Response Name Type Notes
body url String MOLES Record URL relevant to the given archive path
  title String MOLES record title
record_type String type of MOLES3 record type in end-user speak: one of Dataset or Dataset Collection. These map to Observation and Observation Collection respectively.
record_path String The corresponding archive path as recorded on the Result object when the record_type is Dataset. (Blank for Collections)

Positive response:

Dataset (Observation):
{"url": "http://catalogue.ceda.ac.uk/uuid/0ec59f09b3158829a059fe70b17de951", "record_type": "Dataset", "record_path": "/badc/ukmo-midas/data/GL", "title": "MIDAS: Global Weather Observation Data"}
Dataset Collection (Observation Collection):
{"url": "http://catalogue.ceda.ac.uk/uuid/220a65615218d5c9cc9e4785a3234bd0", "record_type": "Dataset Collection", "record_path": "", "title": "Met Office Integrated Data Archive System (MIDAS) Land  and Marine Surface Stations Data (1853-current)"}

Negative response

{"url": "", "record_type": "", "record_path": "", "title": ""}

Observation Completeness Lookup

Gives a complete listing of all observation paths with a 'completed' status. For use use by the ingestion system to determine when writing to the archive is permitted.

Note: this takes a few seconds to run!

URL: http://api.catalogue.ceda.ac.uk/api/v0/complete

Example: http://api.catalogue.ceda.ac.uk/api/v0/complete

Request:

Is a straight url with no arguments

Response:

Is a plain text object where each line has two elements: the path and then a 'Completeness' indicator. This is used to indicate whether the given path (and everything below this) corresponds to a 'Completed' dataset. This is determined from the Data Status of the Observation Record.

Note: the first 6 lines are hardcoded covering the 6 top level data centre paths and are always set to False.

/badc False
/neodc False
/edc False
/sparc False
/bodc False
/ngdc False
/badc/ukmo-tovs/ True
/badc/ukmo-tovs/ True
/badc/csip/data/ukmo-nrt True
/badc/op3/data/op3-1/ceh-temp-gradient/2008 True
/badc/op3/data/op3-1/york-dc-gc-fid2/2008 True

DRS to Record lookup

Allows mapping a DRS to an archive path by finding the relevant Observation record that hold the DRS entry and returning its Result.dataPath entry.

URL: http://api.catalogue.ceda.ac.uk/api/v0/drs_lookup/{drs id}

Example: http://api.catalogue.ceda.ac.uk/api/v0/drs_lookup/esacci.AEROSOL.day.L3C.AER_PRODUCTS.AATSR.Envisat.ORAC.03-02.r1.v20170402

Request:

Is a url ending with the DRS ID to look up.

Name Type Required Default Options Notes
identifier String Yes empty

Response:

Is a json object with the following fields:

Response Name Type Notes
body directory String MOLES3 record URL corresponding to the requested MOLES1/MOLES2 URL
  identifier String MOLES1/MOLES2 URL requested by the user
version String version of the identifier

Positive Response

{"directory": "/neodc/esacci/aerosol/data/AATSR_ORAC/L3/v3.02/DAILY/", "identifier": "esacci.AEROSOL.day.L3C.AER_PRODUCTS.AATSR.Envisat.ORAC.03-02.r1.v20170402", "version": "v20170402"}

Negative Response

{"directory": "UNKNOWN", "identifier": "esacci.AEROSOL.day.L3C.AER_PRODUCTS.AATSR.Envisat.ORAC.03-02.r1.v2017040", "version": "UNKNOWN"}

DRS to Record listing

An API to see all the DRS to Record results given an optional prefix. Same as DRS to Record lookup but given a prefix will find all the matches.

URL: http://api.catalogue.ceda.ac.uk/api/v0/drs_listing/{ prefix }

Example: http://api.catalogue.ceda.ac.uk/api/v0/drs_listing/esacci

Request:

URL with the prefix of a DRS dataset.

Name
Type
Required
Default
Options
Notes
prefix
String
Yes
empty

Empty prefix will show
all DRS datasets.

Response:

Json object with the following fields:

Response Name Type Notes
body { DRS dataset } String Value is archive path of each DRS dataset

Positive Response:

{"esacci.CLOUD.day.L3U.CLD_PRODUCTS.MODIS.Terra.MODIS_TERRA.1-0.r1": "/neodc/esacci_cloud/data/L3U/modis_terra", "esacci.CLOUD.day.L3U.CLD_PRODUCTS.MODIS.Aqua.MODIS_AQUA.1-0.r1": "/neodc/esacci_cloud/data/L3U/modis_aqua"}

Negative Response:

{}

All Observation Mappings

Returns all observation data paths with metadata attached as in the Path to Record Lookup

URL: http://api.catalogue.ceda.ac.uk/api/v0/obs/all

Example: http://api.catalogue.ceda.ac.uk/api/v0/obs/all

Request: 

No arguments

Response: 

A JSON object. The top-level keys are the MOLES data path attached to each observation in the listing. Each of these keys has another JSON object attached with the following fields:

Response Name Type Notes
data path url String MOLES Record URL relevant to the given archive path
  title String MOLES record title
record_type String type of MOLES3 record type in end-user speak: one of Dataset or Dataset Collection. This API only returns datasets so it will always be Dataset

Positive Response

{
	"/badc/sage3/data/g3assp.004": {
		"url": "http://catalogue.ceda.ac.uk/uuid/bbf55db100ce4d0995f86cb1d607011b", 
		"record_type": "Dataset", 
		"title": "SAGE III: Level 2 Solar species profiles version 4, HDF-EOS formatted"
	}, 
	"/badc/cmip5/data/cmip5/output1/IPSL/IPSL-CM5B-LR/piControl/": {
		"url": "http://catalogue.ceda.ac.uk/uuid/cc6bac7b82de4d6aaa56f24bdf123edd", 
		"record_type": "Dataset", 
		"title": "WCRP CMIP5: Institut Pierre-Simon Laplace (IPSL) IPSL-CM5B-LR model output for the piControl experiment"
	}, 
	...
}

Negative Response

Should always respond with a listing. A negative response would indicate a fundamental problem with the API or database.

{}
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us