Discovery API: Quick Start

The Simple Catalog REST API is an easy-to-use way to request simultaneously all Airbus Defence and Space optical satellite catalogs. It is designed to fit REST principles.
Supported output formats include popular JSON, including its spatial extension GeoJSON as well as KML for an immediate visualization of selected imagery.
Links to overviews of the stored satellite image (“quicklook”) are also available, providing either standard JPEG image or georeferenced GeoTIFF rasters. Projected quicklooks are supplied as PNG images with an alpha transparency layer. SPOT 1-5 cloud and snow masks are also available as BMP or JPEG rasters.

Key benefits

The Simple Catalog REST API makes it easy to retrieve SPOT 1-6 and PHR data via:

  • A set of unified query criteria ;
  • A unified output semantic, although some specific SPOT 1-5 metadata can be explicitly requested ;
  • An adhesion to well known Web technologies ;
  • A budget aware design with a write-once your client application, gain-access-to-all-satellite-data philosophy.

Obtaining an API key

  • All API request must include an API key.
  • Using an API key ensure that Airbus Defence and Space can contact you about your application. This includes providing information about new releases or contacting you about specific issues.
  • Do not hesitate to contact us at connectors@astrium-geo.com for information about the API.
  • To apply for an API key, please visit the following link.
  • The generation of the API key is subject to your full approval of the pdf Terms & Conditions

Before starting any industrial development don’t forget to have a look at the Good Practice section to avoid any unwanted unpleasant experience.

Two important points worth mentioning are that all latitude and longitude coordinates use the Geographic WGS84 spatial reference system and date/time are given in Universal Coordinated Time (UTC) also informally referred to as GMT (Greenwich Mean Time).  

The easiest way to start learning about the catalog API is to see some examples.  Below we offer a representative sample of links to get a picture of the Simple Catalog API.
The User Guide is also available as well as tables with all the supported parameters.

Feature URL pattern

Links like http://api.astrium-geo.com/catalog/data/features.svc/features/<id> give you an instant access to the metadata (i.e. technical description) of the “feature” whose business identifier is <id>.

“Feature” URL follows this pattern:

  • A service address: http://api.astrium-geo.com/catalog/data/features.svc/feature/
  • An imagery identifier (an alphanumeric string)
  • An optional output format: of=kml  for instance (preceded by an question mark)
  • Your software key: ?sk=...

More information about feature URLs in§ Feature link.

Quicklook URL pattern

In the same way, links like http://api.astrium-geo.com/catalog/img/getfeatureimage.aspx/<id> returns a “quicklook” (i.e. a sub sampled image of the acquisition) of the “feature” whose business identifier is <id>.

Quicklook simple URL follows this kind of pattern:

  • A service address: http://api.astrium-geo.com/catalog/img/getfeatureimage.aspx/
  • An imagery identifier (an alphanumeric string).

Image link general pattern is:

  • A service address: http://api.astrium-geo.com/catalog/img/getfeatureimage.aspx/
  • An image type (/QL for quicklooks, /CLD for cloud masks…)
  • An imagery identifier (an alphanumeric string).

A more complex and powerful syntax using query strings is also available.
More information about quicklook URL in § Getting quicklooks.

Spatial and attribute queries URL pattern

Lastly 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 (for instance)
  • Some search criteria: “sd=2009-01-01T00:00:00&ed=2009-01-07T00:00:00&mc=100&mi=30&minr=2.5&maxr=20
  • An optional geographic filter: “zt=rectangle&nwlat=52&selat=48&nwlon=9&selon=13
    Your software key: ?sk=...

More information about search URLs in § Search request.

Getting Practical

How to get a scene JSON description?
http://api.astrium-geo.com/catalog/data/features.svc/features/54973830604292026421J?sk=...
provides the JSON description of a Bora-Bora SPOT 5 scene whose canonical identifier is 54973830604292026421J.

API Multi Catalog - Figure 1 - Bora-Bora by SPOT 5  
Figure 1 - Bora-Bora by SPOT 5

 

How to get an acquisition JPEG quicklook?

Three URL syntaxes are available:

  • Complete, using query strings to ask for some processing ;
  • Short, just made of a base URL and acquisition ID, cache-friendly;
  • Canonical, cache-friendly, it allows asking for SPOT 1-5 masks and quickones.

Here is the query-string way of requesting a quicklook of the previous Bora-Bora SPOT 5 scene whose canonical identifier is 54973830604292026421J:

  • http://api.astrium-geo.com/catalog/img/getfeatureimage.aspx?ID=54973830604292026421J
  • Short and cache-friendly URL:
    http://api.astrium-geo.com/catalog/img/getfeatureimage.aspx/54973830604292026421J
  • Canonical and cache-friendly URL:
    http://api.astrium-geo.com/catalog/img/getfeatureimage.aspx/QL/54973830604292026421J

Please note that quicklook URL are parts of feature metadata:

API Multi Catalog - Figure 2 – JSON output

Figure 2 – JSON output

How to get a SPOT 6 datastrip GEOJSON description?

http://api.astrium-geo.com/catalog/data/features.svc/features/DS_SPOT6_201211101947221_FR1_FR1_FR1_FR1_W152S17_01809?of=geojson&sk=...
returns the “DS_SPOT6_201211101947221_FR1_FR1_FR1_FR1_W152S17_01809” datastrip GeoJSON description of a Bora-Bora acquisition.

API Multi Catalog - Figure 3 - Bora-Bora by SPOT 6  
Figure 3 - Bora-Bora by SPOT 6

 

How to get a PHR Bora-Bora datastrip KML description?

http://api.astrium-geo.com/catalog/data/features.svc/features/DS_PHR1A_201204082024066_FR1_PX_W152S17_0413_01804?of=kml&sk=...
provides a KML description of PHR “DS_PHR1A_201204082024066_FR1_PX_W152S17_0413_01804” datastrip.

API Multi Catalog - Figure 4 - Bora-Bora by PHR 1A  
Figure 4 - Bora-Bora by PHR 1A

 

How to request for multispectral better-than-2.5-meter-resolution Bora-Bora imagery?

Bora-Bora island is situated at latitude 16°30'00" S and longitude 151°45'00" W (decimal equivalent: --16.5°, -151.75°).

We request for any imagery intersecting a 20km radius circle centered on the island location and acquired between January 1, 2010 and December, 31, 2012. Hours are given in UTC.  Result format is KML.

The corresponding query is:
  • http://api.astrium-geo.com/catalog/data/features.svc/search?of=kml&sf=multispectral&maxr=2.5&sd=2010-01-01T00:00:00&ed=2012-12-31T23:59:59&zt=circle&clon=-151.75&clat=-16.5&cr=20&sk=...

Where:

  • “of” means Output Format ;
  • “sf” stands for Sensor Family ;
  • “maxr” for Max Resolution ;
  • “sd” for Start Date ;
  • “ed” for End Date ;
  • “zt” for Zone Type ;
  • “clong” for Circle center longitude ;
  • “clat” for Circle center latitude ;
  • “cr” for Circle Radius.

The complete list of the supported input parameter is here.

API Multi Catalog - Figure 5 - feature footprints  
Figure 5 - feature footprints