Discovery API: User Guide

The multi-catalog satellite imagery access is provided through two services, both of which are accessible via http: the catalog REST API and GetImage.

REST API

REST API allows querying and retrieving available imagery metadata using an HTTP Get request. Available imagery metadata consist of SPOT 1-5 scenes or Pleiades and AstroTerra datastrips.
Features can be directly retrieved using their canonical identifiers.

You can also perform spatial and attribute queries on the data held in the catalogs. Most commonly used criteria are acquisition date range, imagery technical quality, cloud percentage, resolution and geographical area of interest (AOI).
Each query results in a collection of “features”. Features are encoded in JSON (default format), GeoJSON or KML format.

A feature describes in a standardized way any satellite imagery regardless of its acquisition platform (SPOT, Pleiades or AstroTerra). Notwithstanding some extra platform specific properties can be requested using the parameter “odf”.

Two kinds of links are embedded in the provided metadata:
o    A static link to the feature description;
o    A static link to the feature quicklook.

IMPORTANT:    Every request to the Simple Catalog API must contain the SLA Key corresponding to the IP address (or e-mail) of the caller. You must generate a SLA Key for your IP address (or e-mail) on the KeyGenerator page and add it as a parameter of every URL (sk={key}).
 

GetImage

GetImage: quicklook and mask retrieval using an HTTP Get request.

According to the satellite, you can stretch the image dynamic or you can “reproject” the quicklook to most cartographic coordinate systems or get a crop.

Supported output formats are Jpeg (default), Windows BMP (SPOT 1-5 cloud and snow masks), GeoTiff (not allowed with the re-projection and cropping functions) or PNG (projected quicklooks).

No SLA key is required to get an image.

Spatial and attribute queries

This section shows the possibilities offered by the REST API through examples. Each example highlights a search criterion. You can freely combine these criteria to narrow your search.

Warning: If the number of results is too important because of a too large area of interest or a too important range of dates then:

  • The results are limited to the most recent data;
  • The response time is longer;

A quota is applied independently to each underlying catalog (SPOT 1-5, SPOT 6 and PHR) to guaranty that a minimum number of features is provided for each satellite family.

Spatial and attribute queries URL pattern

Spatial and attribute queries URLs follow this pattern:

  • A service address: http://api.astrium-geo.com/catalog/data/features.svc/search?
  • An output format: of=kml
  • Some search criteria: “sd=2009-01-01T00:00:00&ed=2009-01-07T00:00:00&mc=100&mi=30&minr=2.5&maxr=20
  • A geographic filter: “zt=rectangle&nwlat=52&selat=48&nwlon=9&selon=13
  • Your software key: “&sk=...

Example 1: Get all imagery intersecting a rectangular area of interest and more recent than a specified date

The rectangle is defined by its opposite northwest and southeast corners.
Dates are formatted according ISO 8601 format (for instance “2009-02-17T23:59:59Z”, although you can omit the Z – Z stands for Zulu hour –formerly Greenwich Mean Time):
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T00:00:00&zt=Rectangle&nwlon=3&nwlat=50&selon=2&selat=49&sk=...

Query string:

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
zt Zone Type area of interest shape whose opposite corners coordinates follow
nwlon North West LONGitude decimal longitude, from -180 to +180
nwlat North West LATitude decimal latitude, from -90 to +90
selon South East LONGitude decimal longitude, from -180 to +180
selat South East LATitude decimal latitude, from -90 to +90

Results come as JSON (default output format).

Example 2: Get all imagery intersecting a rectangular area of interest and acquired within a specific time interval

The rectangle is defined by its opposite northwest and southeast corners:
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T00:00:00&ed=2013-03-09T00:00:00&zt=Rectangle&nwlon=3&nwlat=50&selon=2&selat=49&sk=...

Query string:

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
zt Zone Type area of interest shape whose opposite corners coordinates follow
nwlon North West LONGitude decimal longitude, from -180 to +180
nwlat North West LATitude decimal latitude, from -90 to +90
selon South East LONGitude decimal longitude, from -180 to +180
selat South East LATitude decimal latitude, from -90 to +90

Results come as JSON (default output format).

Example 3: Get all imagery intersecting a circular area of interest and acquired within a specific time interval

The circle is defined by its center and radius:
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2012-11-01T00:00:00&ed=2012-11-05T00:00:00&zt=circle&clon=11.5&clat=5.5&cr=200&sk=...

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
zt Zone Type area of interest shape whose opposite corners coordinates follow
clon Circle LONGitude decimal longitude, from -180 to +180
clat Circle LATitude decimal latitude, from -90 to +90
cr Circle Radius Expressed in kilometers

Results come as JSON (default output format).

Example 4: Get all imagery intersecting a polygonal area of interest and acquired within a specific time interval

A polygon is defined by its vertices, a list of longitudes and latitudes separated by commas.
Polygon must be” closed” (first and last point must be identical).
Multipart polygons and donut polygons are not supported.
Be careful not to exceed the maximum length of an URL which depends on underlying network equipments (varying usually from 2 000 to 4 000 characters).
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2006-12-01T00:00:00&ed=2008-12-31T23:59:59&zt=Polygon&pts=-48.8741805+-1.9575008,-48.6635995+-1.9575008,-48.6635995+-1.7769312,-48.8741805+-1.9575008&sk=...
or
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2006-12-01T00:00:00&ed=2008-12-31T23:59:59&zt=Polygon&pts=-48.8741805 -1.9575008,-48.6635995 -1.9575008,-48.6635995 -1.7769312,-48.8741805 -1.9575008&sk=...

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
zt Zone Type area of interest shape whose opposite corners coordinates follow
pts PoinTS Polygon vertices, in a WKT way.
A vertex is defined by its longitude and latitude separated by a space or a “+” sign :
“-48.8741805 -1.9575008” or “-48.8741805+-1.9575008” for instance.
Two consecutive vertices are separated by a comma.
The first and last vertices must be identical.

Results come as JSON (default output format).

Example 5: Restrict search results to a specific acquisition platform

The current list of satellites is SPOT1, SPOT2, SPOT3, SPOT4, SPOT5, PHR1A, PHR1B and SPOT6.
The following link lists all SPOT 6 acquisition done worldwide on March 2, 2013 from 00:00 to 12:30, UTC time.
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T00:00:00Z&ed=2013-03-02T12:30:00Z&sn=spot6&sk=...

Query string:

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
sn Satellite Name SPOT1, SPOT2, SPOT3, SPOT4, SPOT5, PHR1A, PHR1B or SPOT6

Results come as JSON (default output format).

Example 6: Restrict search results to a range of resolutions

The following link lists all acquisitions done worldwide on March 2, 2013 from 10:15 to 11:30, UTC time whose resolution is greater than 0.5 meter and lowers than 3 meter (inclusive):
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T10:15:00Z&ed=2013-03-02T11:30:00Z&minr=0.5&maxr=3&sk=...

Of course, you can ask for imagery with a better-than-2-meter resolution by omitting the “minr” key:
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T10:15:00Z&ed=2013-03-02T11:30:00Z&maxr=2&sk=...

Alternatively, you can ask for imagery with a greater-than-15-meter resolution by omitting the “maxr” key:
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T10:15:00Z&ed=2013-03-02T11:30:00Z&minr=15&sk=...

Or you can target a specific resolution with an equal value for “minr” and “maxr”:
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T10:15:00Z&ed=2013-03-02T11:30:00Z&minr=2.5&maxr=2.5&sk=...

Query string: 

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
minr MINimum Resolution Resolution given in meter, decimal separator is a dot
maxr MAXimum Resolution Resolution given in meter, decimal separator is a dot

Results come as JSON (default output format).

Example 7: Setting a minimal quality criterion

The following link lists all acquisitions done worldwide on March 2, 2013 from 12:00 to 12:30, UTC time with an equal or better cloud coverage percentage than 10% (i.e. imagery with a cloud cover of less than 10% of their surface):
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T12:00:00Z&ed=2013-03-02T12:30:00Z&mc=10&sk=...

Query string:

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
qm Quality Mark Available values are E (Excellent), G (Good), P (Poor), U (Unusable)

Results come as JSON (default output format).

Example 8: Setting a maximum cloud coverage criterion

The following link lists all acquisitions done worldwide on March 2, 2013 from 12:00 to 12:30, UTC time with an equal or better cloud coverage percentage than 10% (i.e. imagery with a cloud cover of less than 10% of their surface):
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T12:00:00Z&ed=2013-03-02T12:30:00Z&mc=10&sk=...

Query string:

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
mc Max Cloud cover Percentage, integer value required (otherwise the criterion is ignored)

Results come as JSON (default output format).

Example 9: Setting a maximal snow coverage criterion

The following link lists all acquisitions done worldwide on March 2, 2013 from 12:00 to 12:30, UTC time with an equal or better snow coverage percentage than 20% (i.e. imagery with a snow cover of less than 20% of their surface):
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T12:00:00Z&ed=2013-03-02T12:30:00Z&ms=20&sk=...

Query string:

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ms Max Snow cover Percentage, integer value required (otherwise the criterion is ignored)

Pay attention to the following:

  • Data with an undefined snow cover quote are not provided when a snow criterion is set. This happens for some old SPOT scenes.
  • Snow quotation is not as reliable as cloud cover quotation (often resulting in a “no snow / some snow” quotation)

Results come as JSON (default output format).

Example 10: Restrict search results to panchromatic or multispectral imagery

The following link lists all SPOT 5 panchromatic acquisitions done worldwide on March 2, 2013 from 12:00 to 12:30, UTC time:
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T12:00:00Z&ed=2013-03-02T12:30:00Z&sn=spot5&sf=panchromatic&sk=...

Alternatively, you get the SPOT 5 multispectral acquisition with:
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T12:00:00Z&ed=2013-03-02T12:30:00Z&sn=spot5&sf=multispectral&sk=...

Usually, sensor family and resolution range are combined, for instance to get all 1 to 3 meter multispectral imagery acquired during the same date range:
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T12:00:00Z&ed=2013-03-02T12:30:00Z&sn=spot5&sf=multispectral&minr=1&maxr=3&sk=...

Query string:

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
sf Sensor Familiy Multispectral or Panchromatic

Pay attention to the following:

  • Pléiades Catalog considers storing 0.5 meter multispectral imagery exclusively (i.e. pan sharpened products) although 0.5 m panchromatic and 2 m color products can be ordered. Requesting for 0.5 m panchromatic imagery or 2 m multispectral gives no result.
  • SPOT 6 Catalog considers storing 1.5 meter multispectral imagery exclusively (i.e. pan sharpened products) although 1.5 m panchromatic and 6 m color products can be ordered. Requesting for 1.5 m panchromatic imagery or 6 m multispectral gives no result.
  • If the sensor family and the resolution are inconsistent, for instance requesting for some PHR 5 m multispectral imagery, the resolution criteria are ignored. This also applies to SPOT 6.

Results come as JSON (default output format).

Example 11: Restrict search results to a range of incidence angles

The following link selects all acquisitions done worldwide on March 2, 2013 from 10:15 to 11:30, UTC time whose viewing incidence angle is between -8.5° and +8.5° (inclusive):
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T10:15:00Z&ed=2013-03-02T11:30:00Z&mi=8.5&sk=...

Query string:

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
mi Maximum Incidence angle Incidence angle given in decimal degrees, decimal separator is a dot

Results come as JSON (default output format).

Example 12: Restrict search results to imagery stored at a specific receiving station

The following link selects 10-meter-resolution acquisitions done worldwide on March 2, 2013 from 09:15 to 11:30, UTC time whose full resolution data are stored in Toulouse, France (internally referred as TT):
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T09:15:00Z&ed=2013-03-02T11:30:00Z&minr=10&maxr=10&sc=TT&sk=...

Query string: 

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
minr MINimum Resolution Resolution given in meter, decimal separator is a dot
maxr MAXimum Resolution Resolution given in meter, decimal separator is a dot
sc Station Code

Archiving station alphanumerical acronym (TT, FR1…).
Acronyms differ according to the satellite family.
SPOT specific: several comma separated station acronyms can be provided : TT,KK etc.

Pay attention to the following:

  • This criterion does not apply to SPOT combined scenes which are made of several native scenes (i.e. SPOT 5 2.5 m color or B&W, 5 m color ; SPOT 4 10m color), each individual native scene being possibly held by different archiving stations ;
  • A given receiving station may have several acronyms. For instance FR1 is Astrium GEO Toulouse facility for Pleiades while TT is SPOT acronym for the same facility.

Results come as JSON (default output format).

Example 13: SPOT 1 to 5 specific. Scene fullness adjustment

SPOT 1 to 5 scenes boundaries are computed using a fixed land-based grid. Usually the first and last scenes of an acquisition are incomplete. Their quicklook begins or ends with a filling black strip. By default scenes like these are not provided. They can be automatically shifted until fullness to gain access to whole SPOT acquisition datastrips.

The following link selects SPOT5 acquisitions done worldwide on March 2, 2013 from 10:15 to 10:20, UTC time using the scene “autoshift” mode. Many of the returned scenes are shifted as shown by the value of the “shift” property which is different of Shift0:
http://api.astrium-geo.com/catalog/data/features.svc/search?sd=2013-03-02T10:15:00Z&ed=2013-03-02T10:20:00Z&sn=SPOT5&fullness=autoshift&sk=...

Query string:

Key Criteria Value
sd Start Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
ed End Date UTC time, date format : “YYYY-MM-DD HH24:MI:SS[Z]”
mi Maximum Incidence angle Incidence angle given in decimal degrees, decimal separator is a dot
sn Satellite Name SPOT1, SPOT2, SPOT3, SPOT4, SPOT5, PHR1A, PHR1B or SPOT6
fullness SPOT scene fullness Autoshift or CompleteOnly.
CompleteOnly is default value resulting in zero shifted scenes while AutoShift computes the necessary “SAT”
(Shift Along the Track) to gain access to SPOT datastrip beginning and ending.

Results come as JSON (default output format).