User Guide

1. Quick Start

1.1 Presentation and principle

The SPOT Catalog REST API is an easy-to-use way to request the SPOT Catalogue. It contains the description of all “scenes” acquired by the successive SPOT satellites since the launching of SPOT 1 in February 1986.
SPOT satellites acquire 60 kilometres width ground strips when aiming at nadir. These strips are split into 60 kilometres-long scenes. A scene is the commercial order unit.

In the SPOT Catalog REST API, URLs and http GET method are used to request SPOT satellite scene “metadata” and sub sampled images. Results come in different formats according your needs.
The API is stateless but cacheable as an URL always points to the same scene or image.

Several kinds of requests are supported:

IMPORTANT : Every call 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 put it as a parameter of every url you create (sk={key}).

Example of a search link:
http://api.spotimage.com/catalog/spot/data/Dali.svc/search?of=kml&sd=2009-01-01T00:00:00&ed=2009-01-07T00:00:00&mc=100&mi=30&minr=2.5&maxr=20&zt=rectangle&nwlat=52&selat=48&nwlon=9&selon=13&sk={key}

This URL is made of:

Example of a scene link:
http://api.spotimage.com/catalog/spot/data/Dali.svc/Scenes/52873500304080312121S/Shift0?sk={key}

This URL is made of:

At present two response types are provided, each designed to be useful in some programming context:

The result of a search request is a list of scenes described by their “metadata”.
Metadata are a set of alphanumeric items describing the main technical characteristics of SPOT satellite scenes (acquisition date, spectral mode, viewing angle, latitude and longitude, etc.).

The result of a get-a-scene request (i.e. a scene link) is strictly identical although limited to a single scene description.

Apart from a severe internal server error, the http response code is always 200 (OK).

If a REST request results in an error, a void result is provided along with a message explaining the error.

Top

1.2 Search link

To search scenes you need only to construct a valid URL including all the criteria of your search. The URL begins with something like “http://hostname/something/dali.svc/search?”. Criteria are added after the question mark as key/value pairs and are separated by ampersands.

Following is the accepted parameters list (case does not matter):

Key

Parameter Name

Type

Values

(case-insensitive)

Default value

Description

sk

Sla Key

String

-

-

Service Level Agreement Key uniquely identifying you.

of

Output format

Enum

{JSON ; KML}

JSON

“Json” or “KML”.

sd

Start date

Date

-

Now – 1 hour

Beginning of the date range of interest. Precisely, the requested scene centre date is at least later than the provided date.

All dates are assumed to be expressed as UTC time.

Dates should be formatted according ISO 8601 format (for instance “2009-02-17T23:59:59Z”).

ed

End Date

Date

-

Now

End of the date range of interest.

Precisely, the requested scene centre date is prior than the provided date.

All dates are assumed to be expressed as UTC time.

Dates should be formatted according ISO 8601 format (for instance “2009-02-17T23:59:59Z”).

mc

Max cloud coverage

Double

]0;100]

100

Max cloud coverage percentage of the image.

ms

Max snow coverage

Double

]0;100]

100

Max snow coverage percentage of the image (either 0 or 100, intermediate values are unreliable).

mi

Max incidence

Double

]-30.04;

30.04]

30.04

Max incidence (in degrees) of the acquisition (correlated to the satellite side-looking mirror angle).

minr

Min resolution

Double

[2.5;20.0]

2.5

Min resolution of the image in metres. Default value is 2.5.

maxr

Max resolution

Double

[2.5;20.0]

20.0

Max resolution of the image in metres. Default value is 20.

zt

Zone Type

Enum

{circle; rectangle; polygon}

Null.

Specify the shape of the region of interest (if any).

By default the whole Earth is selected.

clon

Circle centre longitude

Double

[-360 ; +360]

 

Longitude of the centre of the circle of interest.

clat

Circle centre latitude

Double

[-180 ; +180]

 

Latitude of the centre of the circle of interest.

cr

Circle radius

Double

]0 ; 10000]

 

Radius in kilometres of the circle of interest.

nwlat

Rectangle NW latitude

Double

[-180 ; +180]

 

Latitude of the North West corner of the rectangle of interest.

nwlon

Rectangle NW longitude

Double

[-360 ; +360]

 

Longitude of the North West corner of the rectangle of interest.

selat

Rectangle SE latitude

Double

[-180 ; +180]

 

Latitude of the South East corner of the rectangle of interest.

selon

Rectangle SE longitude

Double

[-360 ; +360]

 

Longitude of the South East corner of the rectangle of interest.

pts

Polygon points

String

long lat,long lat,long lat

 

List of points represented as longitude and latitude seperated by commas. Polygon must be closed (first and last points identical).

sc

Station code

String

-

Undefined

Archiving station two-letter code.

Results are restricted to scenes archived by this station.

sn

Satellite name

Enum

{SPOT1; SPOT2; SPOT3; SPOT4; SPOT5}

Undefined

SPOT satellite name.

Enable filtering of the data for a particular satellite.

sf

Sensor Family

Enum

{PANCHROMATIC; MULTISPECTRAL}

Undefined

 Panchromatic for black and white images, Multispectral for color images.

fullness

Scene fullness

Enum

{autoshift; completeOnly}

completeOnly

SPOT images can begin or end with a black strip. By default images like that will not be returned. But some of them can be shifted untill fullness. With "autoshift" these images are automatically shifted and returned.

The only mandatory parameter is the SLA key. Some other parameters may be mandatory in some special situations:

Top

1.3 Scene link

You can directly access a single scene metadata using a link. This link is the value of an attribute called “MetadataUrl” which can be found in the results of a search link. This URL is not to be modified manually but should be kept by users or applications in case they would have to retrieve quickly and directly this scene metadata.

For information only, these URLs are formed of several parts, either:

{static part}/{scene type}/{scene internal number}/{scene shift}?sk={key}

 

or


{static part}/{scene id}/{scene shift}?sk={key}

  • {static part}: a first part identical for each scene such as http://api.spotimage.com/catalog/spot/data/Dali.svc/scenes
  • {scene type}: the type of scene, “S” for a normal scene and “C” for combined scenes (scenes created by the combination of two or three normal scenes to improve image resolution);
  • {scene internal number}: a meaningless internal number allowing an efficient access;
  • {scene id}: so called "enhanced" scene id ("A21++ code");
  • {scene shift}: the shift along the track or SAT that tells how much the scene has to be shifted to encompass your area of interest. See chapter 4 for more information about shifting;
  • {key}: All of the URL subparts must be valid to make the link works, particularly the SLA key has to be yours. By default results come in Json. Adding “&of=kml” set output format to KML.

    1.4 Results

    1.4.1 Result description


    Result structure

    Output fields descriptions:

    Field Name

    Description

    Code

    The operation status code based on http codes.

    Possible values can are

    {“OK”;”PartialContent”; ”BadRequest”;”InternalServerError”}

    See below for more explanation about their meaning.

    Message

    A message explaining the error if any.

    Scenes

    The list of selected scenes.

    Id

    The scene ID, nicknamed “A21 code” (*), see below for some complementary information.

    MetadataUrl

    A link pointing to the scene metadata.

    ImageUrl

    A link to the scene quicklook (a sub sampled 500 x 500 pixel image).

    Acquisition date

    The ISO 8601 formatted date of acquisition of the scene,

    Satellite

    The name of the satellite which shot this scene.

    Resolution

    The resolution of the image expressed in metres within a [2.5; 20.0] range.

    IncidenceAngle

    The incidence angle of the acquisition.

    SensorFamily

    The sensor family. Panchromatic sensors produce black and white images and multispectral sensors produce color images.

    ArchivingStation

    The two-letter code of the station holding the image of the scene.

    CloudCoverPercentage

    The cloud coverage percentage of the scene.

    SnowCoverPercentage

    The snow coverage percentage of the scene (either 0 or 100, no intermediate value, 100 means some snow).

    Shift

    Shift along the track of the scene.

    MinShift

    The minimum allowed shift for this scene.

    MaxShift

    The maximum allowed shift for this scene.

    SceneCenter

    The geodetic position of the centre of the scene (using WGS-84 coordinates).

    Upper Left

    The positions of the 4 corners of the scene (using WGS-84 coordinates).

    Upper Right

    Lower Right

    Lower Left

    Sun Azimuth

    The azimuth of the sun.

    Sun Elevation

    The elevation of the sun.

    Technical Quality

    The technical quality of the reference scene.

    (*)In case you are wondering about Astrium Services GEO-Information long product ID's, SPOT uses a unique A21 code for each scene. For example: 20422620611021103321X, is better shown as 2-042,262-061102-110332-1-X where:

    In almost all cases a result as described above is to be returned even if an error has occurred.
    In case of error the status code warns you that something went wrong (it is not set to “OK”). The "Message" attribute gives you some clues to pinpoint the problem. Even some results may be provided since the API policy is to process all what it understands.
    In case of a “PartialContent” result status (loose criteria select too many scenes) the 50 most recent scenes are returned by the API.

    No result is returned only when the server encounters a critical error that it cannot handle. An http 500 error with no result and no message are sent.

    Top

    1.4.2 JSON

    The JSON format keeps the structure of objects. A JSON document always begins with ‘{‘ and finishes with ‘}’. Fields are separated by ‘,’ and are represented by a key/value pair separated by ‘:’. JSON supports different types such as String, Integer, Double, Object, Array… Strings are written within double quotes, whereas types such as Integer or Double are not. Objects are written within ‘{}’ and arrays within ‘[]’. Keys are strings and the values can be of any type defined before.

    Some examples:

    A correctly processed two-scene result:

    {

    "Code":"OK",

    "Message":"OK",

    "Scenes":

     [

     {

      "AcquisitionDate":"2006-01-07T08:31:48Z",

      "ArchivingStation":"RS",

      "CloudCoverPercentage":87,

      "Id":"21252720601070831482P",    "ImageUrl":"http:\/\/api.spotimage.com\/catalog\/spot\/img\/getImage.aspx?ST=S&SN=19057151&SF=0&FT=JPG",

      "LowerLeft":{"Latitude":38.627399444580078,"Longitude":39.8068},

      "LowerRight":{"Latitude":38.479801177978516,"Longitude":40.5824},

      "MaxShift":"Shift6",

      "MetadataUrl":"http:\/\/api.spotimage.com\/catalog\/spot\/data\/Dali.svc\/Scenes\/S\/19057151\/Shift0",

      "MinShift":"Shift0",

      "Resolution":10,

      "Satellite":"SPOT2",

      "SceneCenter":{"Latitude":38.815299987792969,"Longitude":40.287},

      "Shift":"Shift0",

      "SnowCoverPercentage,":100

      "SunAzimuth,":163

      "SunElevation,":54.0999984

      "TQuality,":"EEEE"

      "UpperLeft":{"Latitude":39.147499084472656,"Longitude":40.0016},

      "UpperRight":{"Latitude":38.998600006103516, "Longitude":40.7825}

      },

     {

      "AcquisitionDate":"2006-01-07T08:31:43Z",

      "ArchivingStation":"RS",

      "CloudCoverPercentage":87,

      "Id":"21162700601070831431P",

      "ImageUrl":"http:\/\/api.spotimage.com\/catalog\/spot\/img\/getImage.aspx?ST=S&SN=19057068&SF=0&FT=JPG",

      "LowerLeft":{"Latitude":39.5791015625,"Longitude":35.7867},

      "LowerRight":{"Latitude":39.477298736572266,"Longitude":36.4741},

      "MaxShift":"Shift9",

      "MetadataUrl":"http:\/\/api.spotimage.com\/catalog\/spot\/data\/Dali.svc\/Scenes\/S\/19057068\/Shift0",

      "MinShift":"Shift0",

      "Resolution":10,

      "Satellite":"SPOT2",

      "SceneCenter":{"Latitude":39.791301727294922,"Longitude":36.215900000000005},

      "Shift":"Shift0",

      "SnowCoverPercentage":0,

      "SunAzimuth,":163

      "SunElevation,":54.0999984

      "TQuality,":"EEEE"

      "UpperLeft":{"Latitude":40.104698181152344,"Longitude":35.9528},

      "UpperRight":{"Latitude":40.002101898193359,"Longitude":36.6453}

      }

     ]

    }

     

    Please note a “PartialContent” code does not mean no scene is returned, any value different of “Ok” and “PartialContent” means a void result due to some error (usually bad input criteria).

    An incorrectly processed scene search, the input geographic filter is wrong:

    {

      "Code":"BadRequest",

      "Message":"Rectangle.bottomRight [long=13 ; lat=48454] must be in [-360 ; +360] for longitude and [-180 ; +180] for latitude (WGS-84 CoordinateRefSystem).",

      "Scenes":null

    }

    Top

    1.4.3 KML

    KML is an XML-based language schema for expressing geographic annotation and visualization on two-dimensional maps and three-dimensional Earth browsers. KML was developed for use with Google Earth but can also be used with Google Maps, ArcGIS Explorer, Microsoft Virtual Earth, etc. The KML file specifies a set of features (placemarks, images, polygons, 3D models, textual descriptions, etc.) that permits to define the appearance and layout of geospatial data and text.

    The KML response of the API is different from the JSON response because it contains information about how to display the scenes metadata. It has not been designed to be used in applications interested only in the metadata it contains but should be used with applications such as Google Earth.

    A successfully processed request (status “Code” = “OK” or “PartialContent”):


    KML search result opened with Google Earth

    Legend:

    Remark: a search form seated within a balloon can be displayed on selecting the root element. It contains the full result message of the request and an interactive search form. See below for the description of its description.

    An unsuccessfully processed request:


    A “search by rectangle” ROI balloon


    A “search by circle” ROI balloon

    As shown above, no scene appears below the root element when the request fails. The root element is still a kind of clickable link that makes an interactive search balloon pops up. Depending on the error and geographic filter you provided one of two search balloons is displayed. The first one allows you to set a rectangular filter, the latter let you define a circle (when no region of interest was previously set or your ROI shape was a circle).
    Hitting the “submit” button creates a search URL and asks the API for KML results. The request results are then displayed in Google Earth as explained before.

    Please note only the most important criteria are available in the search balloons.

    Remark: to directly process an interactive search by circle you can use the following URL http://.../search?of=kml&sk=....

    Top

    2 Good Practice, please read carefully

    2.1 Limits

    Some protections are applied to avoid loose requests to extract millions of results and preserve Astrium Services GEO-Information servers from very large queries. Please keep in mind the limitations detailed below in order to get proper performances.

    As a rule of thumb, the less information is requested in the query, the quicker is the answer.

    In case of loose criteria, SPOT catalog API truncates the results to a subset of them and warns you with a “PartialContent” status code. In this case, there is no other way to get the missing scenes than refining your criteria.

    2.2 Performances and advices

    Performances of the SPOT Catalog do not depend directly on the number of results but on the filtering character of the request. The two most filtering parameters are:

    If at least one of these criteria is discriminating then you end up on a quick search:

    Please note that networks, notably the Internet, adds latency times that can exceed those figures.

    If none of these criteria is discriminating (for example one year of images of Australia) the search can take over 30 seconds and the number of results exceeds 10,000 scenes.

    When the estimated number of results is over 300 scenes, the search is automatically refined by splitting your time range into shorter ones (typically week-long step). Successive calls to the SPOT Catalog are done from the end of the time range until 50 results are extracted.
    This is not penalizing as it is usually difficult to set criteria not selecting 50 scenes by day. However, on some areas on Earth like central Africa, casual criteria can select less than one scene per day. When this happens, the request duration can become significant (1 minute or more) because of the iterative building of the response.

    As a conclusion, you should avoid setting large time range and large region of interest to get response within a few seconds. The best practice with this API is to always use time ranges less than a month and have the other criteria as selective as possible to get less than 50 results.

    Top

    3 SPOT Catalog overview

    The SPOT Catalog includes metadata and preview (so-called “Quick Look”) of all images acquired by SPOT 1 to SPOT 5 satellites, from 1986 up to now.

    3.1 Metadata

    SPOT satellites acquire “data strips” of 60 kilometres swath when aiming at nadir. These data strips are split into 60 kilometres long scenes. There is an overlap between two adjacent scenes of data strip. This overlap depends on the latitude.

    The scene is the order unit. Astrium Services GEO-Information sells only scenes (full scenes or scenes extracts). The data strip can not be accessed.


    Data strip cut into 3 scenes

    Each scene can be shifted along the data strip by steps of 1/10Th of scene. The shift value must be chosen between its min and max values. The max= 9 indicates that the next scene is full. A shift of 10 is not allowed, but it can be extracted approximately using the next scene.

    In the example below, the first scene is incomplete. The first image line starts between shift 3 and shift 4. So, the first scene that can be ordered is scene n°1 with a shift of four. The first scene can be shifted until nine. The next scene is scene n°2 with a shift of one. As the last image line is in the middle of scene three, the max shift of scene 2 is 3.
    There is a little overlap between scene 1 with shift 9 and scene 2 with shift 1, because of the size of the overlap between the two scenes.


    Different Shifts possible for a scene

    There are two main receiving stations for SPOT data and a worldwide network of secondary receiving stations. The SPOT Catalog includes SPOT data received from all receiving stations. A given scene can be referenced several times in the SPOT Catalog, because of the visibility-circle overlap between different stations.
    However theses identical scenes, regarding to their localisation, could have different quality quotations, depending on the environment of the receiving station. e.g.: one scene can be acquired at high elevation by one station while it is acquired at low elevation by another one.

    Metadata describes the condition of acquisition: geographic localisation, temporal range, optical instrument and sensor mode used and the technical conditions of the acquisition (in particular, angles).
    The table below presents the optical instruments and sensors of each SPOT satellite and their associated characteristics of the previews:

    Satellite

    Optical instrument

    Sensor

    Colour

    Resolution in meters

    SPOT 1 to SPOT 3

    HRV

    P

    Black and white

    10

    X

    Colour

    20

    SPOT 4

    HRVIR

    M

    Black and white

    10

    I

    Colour with SWIR

    20

    SPOT 5

    HRG

    A

    Black and white

    5

    B

    Black and white

    5

    J

    Colour with SWIR

    10

    By combination of several scenes, Astrium Services GEO-Information can make products with better resolution as shown in the table below:

    Satellite

    Optical instrument

    Sensor

    Colour

    Resolution in meters

    SPOT 5

    HRG

    A and B

    Black and white

    2,5

    A and B and J

    Colour

    2,5

    (one of A,B) and J

    Colour

    5

    Theses scenes are called “combined scenes” and restricted to SPOT 5.

    Top

    3.2 Preview

    Previews are delivered in jpeg format without any projection. Two different sizes are available depending on the level of details required:

    Quicklooks are stored in the catalogue in each acquired spectral band without any projection. They are accessible by the REST service called “getImage”.

    The SPOT Catalog also stores cloud masks in bitmap format, to exactly delimit cloud coverage.

    The link to the scene image is provided in all API responses by the “ImageUrl” field. If you need to retrieve the false colour quicklook or the cloud mask, you have to add some of the following keys to the link.

    Remark: The first part of the image URL should not be modified as it is subject to changes. The following chart is just provided as information.

    1. The type of scene (combined or not) and the scene ids are the only two mandatory keys.
    Scene ids are made of the scene meaningless internal id (SN key) or their alphanumerical ids (ID key).

    Key

    Meaning

    Values

    ST

    Scene type

    S: ordinary scene

    C: combined scene

    Scene designation, one of:

    ·       SN

    ·       ID (ordinary scene)

    ·       ID and CT (combined scene)

    SN

    Scene number

    Any positive integer. Interpreted as a combined scene number or scene number depending on ST key value.

    or

    ID

    Scene identifier

    Any valid A21 code.

    CT

    Combination type

    THR: 2.5 m panchromatic scene;

    HMX: 5 m multi-spectral  scene;

    THX: 2.5 m multi-spectral scene;

     

    Combined scene only.


    2. Optional keys, can be freely added to the returned image link to get complementary or alternative processing

    Key

    Meaning

    Default value

    Values

    IT

    Image type

    QL

    QK (quickone),

    QL (quicklook),

    CLD (cloud mask)

    SNW (snow mask).

    CP

    Colour processing

    N

    F (false colour composite)

    N (pseudo-natural colours)

    SB (spectral band). When using SB, BN key (band number) has to be specified.

    SD

    Dynamic stretching

    T

    T (true)

    F (false)

    FT

    Mask format

     

    JPG (JIFF file format)

    BMP (IBM/Microsoft DIB file format).

    CM

    Compression

    75

    JPG image quality, ranging from 0 (worst) to 100 (best). Image size rises as CM value increases.

    SF

    Scene shift

    0

    0 to 9. Means a 0 to 90% shift toward south.

    Top

    3.3 Examples

    Here is an example of a multi-spectral scene acquired by SPOT 2 in November 2005 over Japan. The false colour quicklook has been projected over the map using Esri ArcMap.


    Projected quicklook with Esri ArcMap

    The quicklook returned by the REST service “getImage” is not projected. The associated non projected cloud mask if shown below:


    Cloud mask (IT=CLD)

    The satellite acquisition spans south of the scene so it can be shifted “along the track”. Here is the projected quicklook of the same scene with a SAT of 4. The land covered by the data strip appears in yellow with the limits of references scenes (scenes on sat 0 with a little overlap).


    Quicklook with a Sat of 4 (SF=4)

    Quicklook and quickone histogram can be linearly stretched on demand. The darkest 2 percent and lightest 2 percent pixels are “removed” to produce a highly contrasted image.


    False colour composite quicklook (CP=F)
    without (left, SD=F) or with (right, SD=F) dynamic stretching


    SPOT Catalog also provides a pseudo-natural appearance for multi-spectral quicklooks and quickones, on demand:


    Natural colour composite quicklook (CP=N)
    without (left, SD=F) or with (right, SD=F) dynamic stretching

    Top

Please contact Astrium Services GEO-Information if you have any questions or comments regarding the SPOTCatalog Simple API or if you have any suggestions for improvements you would like to see in future versions.

geolabs@astrium-geo.com

Spot Image S.A. - 5, rue des Satellites, BP 14 359, F 31030 Toulouse cedex 4, France