Your Processing Environment

EOData Finder API

Using http API to query EO Data Finder

All queries may be executed as simple HTTP-Get calls, by typing the query in web browser address line, by using any HTTP client, e.g. curl or wget, or from inside of users’ program. The database is accessible free and anonymously (open for anonymous access for everyone, no authorization is used) It may be accessed both from the internal network (virtual machines in Creodias) and from outside, e.g. your home computer. Note, that the actual EO data themselves are restricted to to Creodias users, only the catalogue (EO Data Finder) is open.

General Rules

The queries may produce their results either in JSON or XML formats. To select the appropriate form, use the corresponding engine in the URL:

http://datahub.creodias.eu/resto/api/collections/search.json? - for JSON

http://datahub.creodias.eu/resto/api/collections/search.atom? - for XML response

The responses are by default formatted in compact form for machine interpretation.

The responses as text lists of products are not implemented directly yet. If you need just such a list, without additional info, provided by JSON, the solution is to filter out the formatted JSON response. For example, the following filtered command returns name list of 100 most recent Sentinel-1 products.

$ wget -O - "http://datahub.creodias.eu/resto/api/collections/Sentinel1/search.json?&maxRecords=100"

Most queries are case-sensitive.

Collections

The data are organized in so-called collections, corresponding to various satellites. A query may search for data in all collections, or in one particular collection only. If only one satellite is in the field of interest, the second approach is faster and more efficient, than filtering the general query. For example, to find 10 most recent Sentinel-2 products with cloud cover below 10%, the query should look like:

$ wget -O - "http://datahub.creodias.eu/resto/api/collections/Sentinel2/search.json?cloudCover=[0,10]&maxRecords=10"

while if the collection field is missing in the URL, the products from all the satellites are returned:

$ wget -O - "http://datahub.creodias.eu/resto/api/collections/search.json?&cloudCover=[0,10]&maxRecords=10"

As for today the following collections are defined and may be used:

Sentinel1

Sentinel2

Sentinel3

Sentinel5P

Landsat8

Landsat7

Landsat5

Envisat

Note, that collection names vary a bit from satellite names, as they are used in EO Data repository. For example, the collection is named Sentinel2, while in the repository its data are located within /eodata/Sentinel-2/.... branch of the repository tree.

Output sorting and limiting

By default, maximum 10 most recently published products are returned only. You may change the limit (beware of long execution time for queries about thousands of products) using the phrase

maxRecords=nnn

If the query is very general and the number of matching products is large, the next pages of products may be retrieved

page=nnn

You may also change the order of how the products are presented, using the phrase like

sortParam=startDate

will sort the output by observation date rather than by publication date. The following orderings are implemented:

published - the date when the product got published in our repository (default)

startDate - the date when the observation was made

cloudCover - the cloudiness of the scene

each of them may be accompanied by

sortOrder=ascending or sortOrder=descending

For example the query

http://datahub.creodias.eu/resto/api/collections/Sentinel2/search.json?startDate=2016-07-01&completionDate=2016-07-31&sortParam=cloudCover&maxRecords=20

will return 20 least cloudy products from July 2016, while the next query would return the next 20, a little bit cloudier, such product:

http://datahub.creodias.eu/resto/api/collections/Sentinel2/search.json?startDate=2016-07-01&completionDate=2016-07-31&sortParam=cloudCover&maxRecords=20&page=2

The last sub phrase, selecting the next page of the results, may be also written as page=2

Formal queries

The formal query is invoked as a sequence of sub phrases, separated by &. The result is a conjunction of all sub phrases. It is impossible to use an alternative in the question. The query must be specified as a formal query. 

The example of formal query - about cloudless (cloud cover below 10%) products from Warsaw Summer 2016:

http://datahub.creodias.eu/resto/api/collections/Sentinel2/search.json?startDate=2016-06-21&completionDate=2016-09-22&lon=21.01&lat=52.22

The queries are in form param=value or param=[minvalue,maxvalue]. Most of the parameters are common for all collections, but some are specific for some them (e.g. cloudCover applies to optical satellites, but polarisation applies to radar ones), or just single one.

Geography and time-frame

The common set of parameters are:

startDate, completionDate - the date limits of the observation. The time may also be specified, e.g. 2016-10-01T021:30:00Z Format as defined by RFC-3339

publishedAfter, publishedBefore - the date limits when the product was published in our repository

lon, lat - geographical position, expressed in military style (EPSG:4326, as decimal fraction of degrees, positive for eastern latitude and northern longitude)
radius - region of interest, defined as a circle with centre in point determined by the longitude and latitude with radius expressed in meters (it won't work with point manually selected in EOFinder)

geometry - region of interest, defined as WKT string (POINT, POLYGON, etc.)

box - region of interest, defined as the rectangle with given (west,south,east,north) values

name - region of interest, given as name (city name, country name, etc., the same as in natural language queries)

Region of interests may also be specified by KML file, attached to HTTP/POST query, e.g.

curl -X POST http://datahub.creodias.eu/resto/api/collections/Sentinel2/search.json?startDate=2016-07-01&completionDate=2016-08-31 –data @file/my.kml

will find all Sentinel-2 data from Summer 2016 from the area described as KML file my.kml .

Note that KML queries are restricted to simply connected areas (simple polygons).

Volatile features

Some terrain-like feature masks are not permanent but describing a single scene only. The most commonly used such feature is cloudiness, or cloudCover, which is defined for most of the products coming from optical sensors. For example:

cloudCover=[0,10]

selects only those scenes, which are covered by clouds by no more than 10%.

Caution: to be meaningful, the cloudiness must be provided with each product, while in many products is missing. If the cloudiness is unknown for the scene, it is marked by a value of 0 or -1. cloudCover=0 is therefore ambiguous: it may either mean totally cloudless sky or the cloudy scene for which cloud cover had not been estimated during original data processing.

Satellite features

instrument - meaningful only for satellites equipped with multiple instruments. The possible values are satellite specific.

productType - the actual types possible are specific for every satellite. For Sentinel-1 data you may select for example productType=GRD for products processed in standard mode for land observations.

sensorMode - also satellite and sensor specific. E.g. (for Sentinel-1):

productType=GRD&sensorMode=EW

orbitDirection - ascending or descending. For most heliosynchronous satellites descending orbits means the day scenes, while ascending means night ones. For many optical satellites (e.g. Sentinel-2) only day scenes are published.

resolution - expected spatial resolution of the product defined in meters.

status:

• online

• offline 

Some additional parameters are strictly satellite-specific, e.g. polarisation, which is defined only for Sentinel-1

For every satellite (collection) its set of query-able parameters may be obtained by a query like:

https://datahub.creodias.eu/resto/api/collections/Sentinel1/describe.xml

The resulting XML file provides full list of the parameters for the collection, with their very brief descriptions.

Order API Documentation

For comprehensive Order API description you can visit this pages::

Finder API

How to order products using finder API?

and new version ofAPI:

EO Data Finder API2 Manual