The Harmonised Data Access API is a REST interface allowing users to subset and download WEkEO datasets. The following sections describe the API from the dynamic and static points of view.

Note that the endpoints in this document are available at the following broker address:

https://apis.wekeo.eu/databroker/0.1.0
example: https://apis.wekeo.eu/databroker/0.1.0/querymetadata/{datasetId})

Quick Reference

WEkEO HDA API supports the dataset search and data download operations via RESTful interface. Access token is required to work with the API which can be generated from the following endpoint using API Key. Note that this endpoint is a HTTP POST operation and expects Authorization field in header and 'grant type' in the body.

https://apis.wekeo.eu/token 

Data Broker API

The API endpoints in the table below must be prefixed by the broker address specified above.

example: https://apis.wekeo.eu/databroker/0.1.0/querymetadata/EO%3AEUM%3ADAT%3ASENTINEL-3%3AOL_2_WRR___ 

Terms and Conditions API

The API endpoints in the table below must be prefixed by the following T&C's endpoint

https://apis.wekeo.eu/dcsi-tac/0.1.0
example: https://apis.wekeo.eu/dcsi-tac/0.1.0/termsaccepted/Copernicus_General_License

Dynamic description

This section describes the Harmonised Data Access API from a dynamic perspective, showing each user request in context. For the detailed description of all API messages and responses, refer to the "Static description" section below.

Let's assume a user wants to access data in a given dataset. The user starts by sending a message to the Harmonised Data Access Broker at /querymetadata to obtain the list of parameters she can use to subset the data (see figure below). The response to this message includes an indication on whether the user has accepted the terms and conditions for this particular dataset. If not, the user can access the User Profile Service to update her profile.

The user then sends a request to /datarequest providing the desired subsetting parameters (e.g. bounding box) and immediately gets a subsetting job ID in return (see figure below).

With the job ID, the user can poll the Broker at /datarequest/status/{jobId} to determine when the job has finished and the data is available for download (see figure below). The Broker replies with either complete = false or complete = true. In this case, the Broker includes a list of URIs for the user to download the data subset.

The user downloads the data using the list of external URIs (see figure below), via the /datarequest/result/{jobId}/{resultId} endpoint.

Static description

GET /querymetadata/{datasetId}

Parameters:

• datasetId (in the URL), required, string: ID of the dataset

Responses:

• Code 200 (OK): a JSON object containing:
  • datasetId, required, string
  • userTerms, object:
    • termsId, string: unique label for the terms and conditions for the licence that must be accepted to use this dataset
    • accepted, boolean: whether the user has accepted or not the terms and conditions for the dataset
  • parameters, object:
    • stringInputs, Array<StringInput>, where StringInput is an object containing all Parameter attributes described below, and in addition:
      • details, required, object:
        • maxLength, required, integer: maximum length of the input value
        • pattern, string: regex used to validate the input value
    • stringChoices, Array<StringChoice>, where StringChoice is an object containing all Parameter attributes described below, and in addition:
      • details, required, object:
        • valuesLabels, required, object mapping internal values to human-readable labels
    • multiStringSelects, Array<MultiStringSelect>, where MultiStringSelect is an object containing all Parameter attributes described below, and in addition:
      • details, required, object:
        • groupedValueLabels, required, Array<object>: each object contains:
          • name, required, string: a human-readable name for the group
          • label, string: a human-readable label to complement the name
          • values_labels, object mapping internal values to human-readable labels
        • defaultValues, Array<string>
    • dateRangeSelects, Array<DateRangeSelect>, where DateRangeSelect is an object containing all Parameter attributes described below, and in addition:
      • details, required, object:
        • start, required, string in date-time format
        • end, required, string in date-time format
        • defaultStart, string in date-time format
        • defaultEnd, string in date-time format
    • boundingBoxes, Array<BoundingBox>, where BoundingBox is an object containing all Parameter attributes described below, and in addition:
      • details, required, object:
        • extent, required, Array<float> (4 elements)
        • crs, string enum (EPSG:4326)
  • constraints, Array<Constraint>: list of inter-parameter constraints. Constraint is an object containing:
    • name, required, string
    • comment, string
    • constraintType, string
  • rendering, Array<RenderingControl>: list of rendering options for the parameters and constraints, for UI use. Not required to construct a queryRequest. RenderingControl is an object containing:
    • name, required, string
    • comment, string
    • renderType, required, string

Parameter objects include:

• name, required, string: internal name of the parameter
• label, string: human-readable label to refer to this parameter
• comment, string: human-readable descriptive text to complement information on this parameter
• isRequired, require, boolean: whether the parameter is required in order to request data from this dataset

POST /datarequest

Parameters:

• queryRequest (message body), required, JSON object: subsetting query details for the dataset. The object should contain the following fields:
  • stringInputValues, Array<StringInputValue>, where StringInputValue is an object containing:
    • name, required, string
    • value, required, string
  • stringChoiceValues, Array<StringChoiceValue>, where StringChoiceValue is an object containing:
    • name, required, string
    • value, required, string
  • multiStringSelectValues, Array<MultiStringSelectValue>, where MultiStringSelectValue is an object containing:
    • name, required, string
    • values, required, Array<string>
  • dateRangeSelectValues, Array<DateRangeSelectValue>, where DateRangeSelectValue is an object containing:
    • name: required, string
    • start: required, string in date-time format
    • end: required, string in date-time format
  • boundingBoxValues, Array<BoundingBoxValue>, where BoundingBoxValue is an object containing:
    • name: required, string
    • bbox: required, Array<float> (4 elements)

Responses:

• Code 200 (OK): a JSON object containing:
  • jobId, string: ID of the subsetting job
  • complete, boolean, initially false: whether the subsetting job has completed
  • results, null | Array<string>, initially null: list of result URIs, or null if the job is still running. URIs will be compatible with the form /datarequest/result/{jobId}/{resultId} (see endpoint below)
• Code 400 (Bad Request): returned when the user request is invalid
• Code 403 (Forbidden): returned when the user has not accepted the terms & conditions for the concerned dataset
• Unspecified error

GET /datarequest/status/{jobId}

Parameters:

• jobId (in the URL), required, string: ID of the subsetting job

Responses:

• Code 200 (OK): a JSON object containing:
  • jobId, string: ID of the subsetting job
  • complete, boolean: whether the subsetting job has completed
  • results, null | Array<string>: list of result URIs, or null if the job is still running. URIs will be compatible with the form /datarequest/result/{jobId}/{resultId} (see endpoint below)
• Code 400 (Bad Request): returned when the user request is invalid
• Code 403 (Forbidden): returned when the user has not accepted the terms & conditions for the concerned dataset
• Unspecified error

GET /datarequest/result/{jobId}/{resultId}

Note: the complete URI is obtained as a result of a previous GET /datarequest/status/{jobId} request.

Parameters:

• jobId (in the URL), required, string: ID of the subsetting job
• resultId (in the URL), required, string: ID of the individual result (part of the URI obtained from the previous GET /datarequest/status/{jobId} request)

Reponses:

• Code 200 (OK): requested file
• Unspecified error