Overview

This API web service provides a way to easily and programmatically access the complete dataset metadata record for a DOI or Query PID. Using the Oceans 3.0 API allows this process to be automated, which facilitates easy computer-to-computer tasks such as scheduled record retrieval or download of large numbers of records. Citations provided along with the metadata record are formatted according to ESIP guidelines established by the earth science community.

Metadata records for ONC DOIs are retrieved from DataCite. The Dataset Metadata Service generates a URL (the dataciteMetadataURL field) that can then be used to call on DataCite's own API to download the full record. As this also uses an API, this two-step process can be fully automated. See more information about DataCite's API at https://support.datacite.org/docs/api-get-doi.

However, DataCite can only provide a metadata record for a complete dataset assigned a DOI. The metadata for specific subsets of ONC data can only be accessed from Ocean Networks Canada's Oceans 3.0 system, using Query PIDs generated for every data search performed in our database. These Query PIDs are stored locally on ONC servers, and when a Query PID is used with the Dataset Metadata Service, the query parameters of that data subset search are returned in addition to the metadata record for the complete parent dataset DOI. See below for details about the information provided when a Query PID is used with the Dataset Metadata Service.

See the External Web Services for method, and responseType usage and error messages.

URL

https:/data.oceannetworks.ca/api/datasetMetadata

get

The get method retrieves metadata from the DOI in the same fashion as the dataset landing page.

Parameters

Response

Example DOI request: https://data.oceannetworks.ca/api/datasetMetadata?method=get&doi=10.34943/115343a9-6d88-4f6c-a88b-9a7b17ad53e0

Example Query PID request: https://data.oceannetworks.ca/api/datasetMetadata?method=get&queryPid=8297994

Success (HTTP 200)

Currently, a successful API call returns information about the metadata record in JSON format, including a link to call on DataCite's API to retrieve the full metadata record for the dataset.

Example results via web browser using a DOI

• Firefox offers added functionality that formats the JSON to be easier for a human to read:

Key information:

• dataSearchURL - a link to the search used to retrieve that dataset from Oceans 3.0
• dataciteMetadataURL  - a URL for the DataCite API call that returns the metadata record for that DOI
• device - information about the instrument that supplied the data for the dataset (mostly for internal use)
• doiCitation - a citation for the dataset, formatted to ESIP standards

Example results via web browser using a Query PID:

• Firefox offers added functionality that formats the JSON to be easier for a human to read:

Key information:

• dataSearchURL, dataciteMetadataURL, device, doiCitation - the same as the results for a DOI search, where the DOI is the parent dataset from which the the query result data subset is extracted
• queryCitation - a citation for the subset of data defined by the query. Useful for improving reproducibility of results.
• queryDetails - the specific search parameters that were used to generate that query PID
  • dataProductCode: for internal ONC use
  • dataProductName: what kind of data it is
  • dataProductOptions: details of the options selected when downloading the data subset, e.g. how to fill in data gaps, raw or clean data, etc
  • dateCreated: the original date and time the search query was executed
  • dateFrom and dateTo: the beginning and end dates of the data subset itself, as selected in the search
  • extension: the file format chosen for the results
  • queryPID: the value entered in the queryPID= parameter

Bad Request (Error) (HTTP 400)