Language
Geostore Guide
  1. Search
    1. Prerequisites
    2. Search an Image and Retrieve Its Identifier
    3. Request a Quicklook Image
    4. Example Code

Search API

This guide explains how to search for an archive image, step by step, with examples, using the Search API. Online reference documentation can be found here, to get all possible options.

Prerequisites

The first action of this tutorial deals with the token that was obtained during Authentication, in the previous chapter. Once you have retrieved your access token you will be able to use our Search API.


Use the endpoint https://search.federated.geoapi-airbusds.com/api/v1/search along with the access token you retrieved in the authentication step. Use this variable in the requests headers:

export MY_TOKEN="Bearer <access_token>"
Not available
Not available

Search an Image and Retrieve Its Identifier

This example demonstrates how to find a SPOT image and extract its identifier to order it through the Order API.


You can now request the desired images using a POST search request. The request deals with all images that:

  • are within the bounding box 1.18, 43.52, 1.25, 43.56 expressed in geographic coordinates
  • were acquired with one of the optical satellite of the SPOT constellation (i.e. SPOT 1 to 7)
  • were acquired in July 2016
  • have an incidence angle less or equal to 20 degrees
  • have less than 10 percent of it covered by clouds
curl -X POST -H "Authorization: $MY_TOKEN" -H "Content-Type: application/json" -d '{
  "bbox": [
    1.18,
    43.52,
    1.25,
    43.56
  ],
  "constellation": [
    "SPOT"
  ],
  "acquisitionDate": "[2016-07-01,2016-07-31T23:59:59]",
  "incidenceAngle": "20]",
  "cloudCover": "10]",
  "count": 10,
  "startPage": 1
}' "https://search.federated.geoapi-airbusds.com/api/v1/search"
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://search.federated.geoapi-airbusds.com/api/v1/search",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer <access_token>",
    "Content-Type": "application/json",
    "Cache-Control": "no-cache"
  },
  "processData": false,
  "data": "{\n  \"bbox\": [\n    1.18,\n    43.52,\n    1.25,\n    43.56\n  ],\n  \"constellation\": [\n    \"SPOT\"\n  ],\n  \"acquisitionDate\": \"[2016-07-01,2016-07-31T23:59:59]\",\n  \"incidenceAngle\": \"20]\",\n  \"cloudCover\": \"10]\",\n  \"count\": 10,\n  \"startPage\": 1\n}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
import requests

url = "https://search.federated.geoapi-airbusds.com/api/v1/search"

payload = "{\n  \"bbox\": [\n    1.18,\n    43.52,\n    1.25,\n    43.56\n  ],\n  \"constellation\": [\n    \"SPOT\"\n  ],\n  \"acquisitionDate\": \"[2016-07-01,2016-07-31T23:59:59]\",\n  \"incidenceAngle\": \"20]\",\n  \"cloudCover\": \"10]\",\n  \"count\": 10,\n  \"startPage\": 1\n}"
headers = {
    'Authorization': "Bearer <access_token>",
    'Content-Type': "application/json",
    'Cache-Control': "no-cache",
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Each matching image is returned as a GeoJSON feature under the /features[] property. The response should look like:

{
    "startIndex": 1,
    "itemsPerPage": 10,
    "totalResults": 1,
    "query": {
        "count": 10,
        "startPage": 1,
        "constellation": [
            "SPOT"
        ],
        "acquisitionDate": "[2016-07-01,2016-07-31T23:59:59]",
        "incidenceAngle": "20]",
        "cloudCover": "10]",
        "bbox": [
            1.18,
            43.52,
            1.25,
            43.56
        ]
    },
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "viewingAngleAlongTrack": 17.842472,
                "sourceId": "DS_SPOT7_201607291038129_FR1_FR1_FR1_FR1_E001N44_01140",
                "acquisitionDate": "2016-07-29T10:38:18.749Z",
                "viewingAngleAcrossTrack": 17.909748,
                "cloudCover": 1,
                "illuminationAzimuthAngle": 138.17620223373999,
                "azimuthAngle": 180.02305999992444,
                "creationDate": "2017-06-09T18:34:07.993655Z",
                "resolution": 1.5,
                "productName": "SPOT 1.5-m",
                "incidenceAngle": 19.932425767385716,
                "constellation": "SPOT",
                "provider": "Airbus Defence and Space",
                "satellite": "SPOT7",
                "illuminationElevationAngle": 60.113767096927724,
                "productType": "SPOTArchive1.5Mono"
            },
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            1.004096367945723,
                            43.70465186274181
                        ],
                        [
                            1.839631530291143,
                            43.69153457181614
                        ],
                        [
                            1.840765797911517,
                            43.3869345568225
                        ],
                        [
                            1.002817646184104,
                            43.4014298007982
                        ],
                        [
                            1.004096367945723,
                            43.70465186274181
                        ]
                    ]
                ]
            },
            "id": "ea1575c9-a4e5-4748-9e1b-fbc37d7286e9::fde346d6-4531-4bec-9d35-3d1880382c89",
            "bbox": [
                1.002817646184104,
                43.386934556822496,
                1.840765797911517,
                43.704651862741805
            ],
            "thumbnail": "/api/v1/productTypes/SPOTArchive1.5Mono/products/DS_SPOT7_201607291038129_FR1_FR1_FR1_FR1_E001N44_01140?size=SMALL",
            "quicklooks": [
                {
                    "size": "MEDIUM",
                    "projection": "http://www.opengis.net/def/crs/EPSG/0/3857",
                    "image": "https://search.federated.geoapi-airbusds.com/api/v1/productTypes/SPOTArchive1.5Mono/products/DS_SPOT7_201607291038129_FR1_FR1_FR1_FR1_E001N44_01140?projection=EPSG:3857&size=MEDIUM"
                },
                {
                    "size": "MEDIUM",
                    "projection": "http://www.opengis.net/def/crs/EPSG/0/4326",
                    "image": "https://search.federated.geoapi-airbusds.com/api/v1/productTypes/SPOTArchive1.5Mono/products/DS_SPOT7_201607291038129_FR1_FR1_FR1_FR1_E001N44_01140?projection=EPSG:4326&size=MEDIUM"
                },
                {
                    "size": "LARGE",
                    "projection": null,
                    "image": "https://search.federated.geoapi-airbusds.com/api/v1/productTypes/SPOTArchive1.5Mono/products/DS_SPOT7_201607291038129_FR1_FR1_FR1_FR1_E001N44_01140?size=LARGE"
                },
                {
                    "size": "MEDIUM",
                    "projection": null,
                    "image": "https://search.federated.geoapi-airbusds.com/api/v1/productTypes/SPOTArchive1.5Mono/products/DS_SPOT7_201607291038129_FR1_FR1_FR1_FR1_E001N44_01140?size=MEDIUM"
                },
                {
                    "size": "SMALL",
                    "projection": null,
                    "image": "https://search.federated.geoapi-airbusds.com/api/v1/productTypes/SPOTArchive1.5Mono/products/DS_SPOT7_201607291038129_FR1_FR1_FR1_FR1_E001N44_01140?size=SMALL"
                }
            ]
        }
    ]
}

Request a Quicklook Image

To verify that the image is of the desired quality, you can request its associated quicklooks (under /features[]/quicklooks[]). The following command requests the LARGE and unprojected quicklook:

curl -X GET \
  "https://search.federated.geoapi-airbusds.com/api/v1/productTypes/SPOTArchive1.5Mono/products/DS_SPOT7_201607291038129_FR1_FR1_FR1_FR1_E001N44_01140?size=LARGE" \
  -H "Authorization: $MY_TOKEN" \
  -H "Cache-Control: no-cache"
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://search.federated.geoapi-airbusds.com/api/v1/productTypes/SPOTArchive1.5Mono/products/DS_SPOT7_201607291038129_FR1_FR1_FR1_FR1_E001N44_01140?size=LARGE",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer <access_token>",
    "Cache-Control": "no-cache"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
import requests

url = "https://search.federated.geoapi-airbusds.com/api/v1/productTypes/SPOTArchive1.5Mono/products/DS_SPOT7_201607291038129_FR1_FR1_FR1_FR1_E001N44_01140"

querystring = {"size":"LARGE"}

headers = {
    'Authorization': "Bearer <access_token>",
    'Cache-Control': "no-cache"
    }

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

The quicklook should look like the following image:

quicklook

Example Code

Here is the whole code to retrieve a bearer token, to use it for a search and then to download the associated quicklook:

#!/bin/sh

if [ "$#" -ne 1 ]; then
  echo "Usage: $0 YOUR_API_KEY" >&2
  exit 1
fi

# Pass your API KEY as first parameter of the command line
MY_API_KEY=$1

# Authentication request that returns the Bearer token. This token will be used for further requests.
curl -X POST \
  https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token \
  -H "Cache-Control: no-cache" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=api_key&client_id=IDP&apikey=$MY_API_KEY" \
  > AuthenticationReturn.json

# Get the IDP Token out of the JSON Result
MY_TOKEN=`cat AuthenticationReturn.json | jq '.access_token' | tr -d \"`

# Search for Segment reference using filters
curl -X POST \
  https://search.federated.geoapi-airbusds.com/api/v1/search \
  -H "Authorization: Bearer $MY_TOKEN" \
  -H "Cache-Control: no-cache" \
  -H "Content-Type: application/json" \
  -d '{
  "bbox": [
    1.18,
    43.52,
    1.25,
    43.56
  ],
  "constellation": [
    "SPOT"
  ],
  "acquisitionDate": "[2016-07-01,2016-07-31T23:59:59]",
  "incidenceAngle": "20]",
  "cloudCover": "10]",
  "count": 10,
  "startPage": 1
}' > SearchReturn.json

# Get the Endpoint to retrieve the Picture from the JSON Search Result
PICT_URL=`cat SearchReturn.json | jq '.features[0].quicklooks[] | select(.size == "LARGE") | .image' | tr -d \"`
echo $PICT_URL
echo $MY_TOKEN

# option -v : verbose to help diagnose any connection issue.
# option -O : keep original file name (-o would choose another output name)
# option -L : follow redirections, absolutely required to get the cached images.
curl -X GET $PICT_URL \
  -H "Authorization: Bearer $MY_TOKEN" \
  -H "Cache-Control: no-cache" \
  -O -L

Not yet available
import requests
import json

# API are accessed with an API key.
# Please refer to documentation if you need to get an API key.
apiKey=raw_input("Paste your API key: ")

# AUTHENTICATION ------------------------------------------------------------------------------------------------
# Build the Authentication Request, and run it.
urlAuth = "https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token"

payloadAuth = "grant_type=api_key&client_id=IDP&apikey="+apiKey
headersAuth = {
    'Content-Type': "application/x-www-form-urlencoded",
    'Cache-Control': "no-cache"
    }

responseAuth = requests.request("POST", urlAuth, data=payloadAuth, headers=headersAuth)
jsonAuth = json.loads(responseAuth.text)

# Local AuthenticationReturn.json file contains the JSON result of the Authentication Request
fAuth=open('./AuthenticationReturn.json', 'wt')
fAuth.write(json.dumps(jsonAuth, indent=4))
fAuth.close()

# The result of the authentication is a Bearer IDP token that will be used for authentication in the following requests.
idpToken=jsonAuth["access_token"]

# SEARCH FOR AN IMAGE WITHIN THE CATALOGUE, WITH PARAMETERS ----------------------------------------------------
# Build the Search Request, and run it
url = "https://search.federated.geoapi-airbusds.com/api/v1/search"

payload = "{\r\n  \"bbox\": [\r\n    1.18,\r\n    43.52,\r\n    1.25,\r\n    43.56\r\n  ],\r\n  \"constellation\": [\r\n    \"SPOT\"\r\n  ],\r\n  \"acquisitionDate\": \"[2016-07-01,2016-07-31T23:59:59]\",\r\n  \"incidenceAngle\": \"20]\",\r\n  \"cloudCover\": \"10]\",\r\n  \"count\": 10,\r\n  \"startPage\": 1\r\n}"
headers = {
    'Authorization': "Bearer "+idpToken,
    'Content-Type': "application/json",
    'Cache-Control': "no-cache"
    }

response = requests.request("POST", url, data=payload, headers=headers)

# Write down the JSON result into a local SearchReturn.json file to read it.
jsonResponse = json.loads(response.text)
# write the JSON result as a file
fsearch=open('./SearchReturn.json', 'wt')
fsearch.write(json.dumps(jsonResponse, indent=4))
fsearch.close()

# SEARCH FOR THE IMAGE FOUND IN RETURN -------------------------------------------------------------------------
# Parse the Result of the Search to find the Picture Download Endpoint.
for feature in jsonResponse["features"]:
    # This example returns one Segment only (This loop plays once).
    # But this Code would display all the LARGE images found by the Search Request.
    sourceId=feature["properties"]["sourceId"]
    imageId=feature["id"];
    for image in feature["quicklooks"]:
        # For all the formats of this Segment, find the LARGE one(s).
        if image["size"]=="LARGE":
            urlImage=image["image"]
            querystring = {"size":"LARGE"}
            headersImage = {
                'Authorization': "Bearer "+idpToken,
                'Cache-Control': "no-cache"
            }
            responseImage = requests.request("GET", urlImage, headers=headersImage)
            # The result is stored into a local JPG picture.
            with open('./Image_'+sourceId+'.jpg', 'wb') as f:
                f.write(responseImage.content)
                f.close()
                ftext=open('./Image_'+sourceId+'.json', 'wt')
                ftext.write(json.dumps(feature, indent=4))
                ftext.close()


Download in Shell Download in Python