Language
OneAtlas Data Guide
  1. Search
    1. Prerequisites
    2. Endpoint
    3. Search Scope
    4. Geographic Filters
    5. Field Filters
    6. Sort Results
    7. Paginate Results
    8. Results

Search

Our OneAtlas Data Living Library includes nearly all daily acquisitions of Pléiades (50cm) imagery since the end of 2017. An extensive archive over North America, Europe, Asia and Middle East is also included going back 2 years. The search APIs allows users to express complex searches my filtering different parameters and specifying geographic criteria.

Prerequisites

If you haven’t already, see our Authentication Guide for information on how to acquire and use an API key and generate tokens to access to our endpoints.

Endpoint

The OneAtlas Data search API is compliant with the OpenSearch specification. The official specification documentation can be used as a reference: http://www.opensearch.org/.


API Endpointhttps://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch
REST verbGET / POST
AuthenticationBearer access token
API ReferenceOrdering API

Here are some example of searches with the Search API, more details can be found here.

Search Scope

A search scope defines the resources included in your search. By default, a search is performed within a public scope. It means that the workspace in which images are searched is public and accessible to any OneAtlas user.


In addition to this public workspace, any OneAtlas user has a private workspace which contains product that belongs to the user.


For example, here below is an example of searching images in the public workspace:

curl -X GET \
  'https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json'
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
url = "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch"

headers = {
    'authorization': "Bearer <access_token>",
    'content-type': "application/json",
    'cache-control': "no-cache",
    }

response = requests.request("GET", url, headers=headers, verify=False)

print(response.text)

In addition, to proceed to a search in a private workspace, a user must retrieve first its workspaceId. To do so, the /me endpoint should be used:

curl  --silent -k -X GET -H " Authorization: Bearer <access_token>" \
  -H "Cache-Control: no-cache" \
  "https://data.api.oneatlas.airbus.com/api/v1/me"  | python -m json.tool |grep workspace | cut -d "\"" -f4

Example of id returned:

a20d890b-901c-4028-b7c3-f4efca2720e3

Finally, searching for products in your private workspace simply consists of adding a search criteria of your workspaceId. Below is an example of a call:

curl -X GET \
  'https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?workspaceid=a20d890b-901c-4028-b7c3-f4efca2720e3' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
vvar data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?workspaceid=a20d890b-901c-4028-b7c3-f4efca2720e3");
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");

xhr.send(data);
import requests

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

querystring = {"workspaceid":"a20d890b-901c-4028-b7c3-f4efca2720e3"}

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

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

print(response.text)

Geographic Filters

The search API returns all images that intersect with a requested extent. The extent could be a circle, a bounding box or a polygon described using the WKT (Well Know Text) standard.

Search with a Circle

Below is an example to search for images within a circular area measuring 1000 meters in diameter centered over Toulouse:

curl -X GET \
  'https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?lat=43.60426&lon=1.44367&radius=1000' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?lat=43.60426&lon=1.44367&radius=1000");
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");

xhr.send(data);
uimport requests

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

querystring = {"lat":"43.60426","lon":"1.44367","radius":"1000"}

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

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

print(response.text)

The center of the circle is expressed as a longitude and latitude coordinates, in decimal degrees in EPSG:4326 (typical WGS84 coordinates as returned by a GPS receiver). The request also includes a “radius” parameter that specifies the search radius.

Search Within a Bounding Box

The search could be performed within a bounding box. The box is defined by “west, south, east, north” coordinates of longitude, latitude, in a EPSG:4326 decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner.


Here below is an example to search for images within a bounding box over San Francisco (-122.537,37.595,122.303,37.807).

curl -X GET -H "Authorization: Bearer <access_token>" \
   -H "Cache-Control: no-cache" \
   "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?bbox=-122.537,37.595,-122.303,37.807"
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?bbox=-122.537,37.595,-122.303,37.807");
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");

xhr.send(data);
import requests

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

querystring = {"bbox":"-122.537,37.595,-122.303,37.807"}

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

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

print(response.text)

Search Within a Polygon

The search could be performed within a polygon. This polygon must be defined according the WKT (Well Known Text) norm. This norm is design to define geographic areas using a simple textual formalism. The norm specification could be found on Wikipedia or directly on the OGC web site.


Here below is an example to search for images over Gibraltar:

gibraltar

curl -X GET \
  'https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?relation=intersects&geometry=POLYGON%28%28-5.350972006554837%2036.10903284026139,-5.368052313561666%2036.15274102495853,-5.330715964074367%2036.153122194644425,-5.343590567345846%20036.1086861277239,-5.350972006554837%2036.10903284026139%29%29' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?relation=intersects&geometry=POLYGON%28%28-5.350972006554837%2036.10903284026139,-5.368052313561666%2036.15274102495853,-5.330715964074367%2036.153122194644425,-5.343590567345846%20036.1086861277239,-5.350972006554837%2036.10903284026139%29%29");
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");

xhr.send(data);
uimport requests

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

querystring = {"relation":"intersects","geometry":"POLYGON%28%28-5.350972006554837%2036.10903284026139,-5.368052313561666%2036.15274102495853,-5.330715964074367%2036.153122194644425,-5.343590567345846%20036.1086861277239,-5.350972006554837%2036.10903284026139%29%29"}

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

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

print(response.text)

Field Filters

By utilizing multiple fields, complex criteria can be expressed across, with a variety of conditions. All field filters require a field name and a filter-specific value.

Filter per Image Resolution

You can use the constellation field value to filter by image resolution:

Field nameValueResolution
constellationPHR0.5m
SPOT1.5m
curl -X GET \
  'https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?constellation=PHR' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?constellation=PHR");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
url = "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch"

querystring = {"constellation":"PHR"}

headers = {
    'authorization': "Bearer <access_token>",
    'cache-control': "no-cache",
    }

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

print(response.text)

Filter per Acquisition Date

In addition to a filter per image resolution, you may want to filter per acquisition date. To do so, an interval defined by a starting date and an ending date should be specified. For example, the following request searches for images which have an acquisition date between the 20 April 2018 and 04 June 2018:

curl -X GET \
  'https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?acquisitionDate=[2018-04-20T00:00:00.000Z,2018-06-04T00:00:00.000Z]' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?acquisitionDate=[2018-04-20T00:00:00.000Z,2018-06-04T00:00:00.000Z]");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
url = "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch"

querystring = {"[2018-04-20T00:00:00.000Z,2018-06-04T00:00:00.000Z]":""}

headers = {
    'authorization': "Bearer <access_token>",
    'cache-control': "no-cache",
    }

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

print(response.text)

Filter per Cloud Coverage

The images added to the OneAtlas living library do not contain more than 30% of clouds. If you need to filter images to select only images having less that 10% of cloud you can use the field cloudCover and provide the expected interval. For example, the following request filters images having a cloud coverage lower that 10%:

curl -X GET -H 'Authorization: Bearer <access_token>' \
    -H "Cache-Control: no-cache" \
    "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?cloudCover=[0,10]"
Not available.
url = "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch"

querystring = {"cloudCover":"[0,10]"}

headers = {
    'authorization': "Bearer <access_token>",
    'cache-control': "no-cache",
    }

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

print(response.text)

Sort Results

By default, the search results are sorted per acquisition date (newest data is displayed first) and per cloud coverage (less cloudy images are displayed first). For specific needs, you can specify your own sort criteria. For example, the following request sorts the search results per incidenceAngle:

curl -X GET \
  'https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?sortBy=incidenceAngle' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?sortBy=incidenceAngle");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
url = "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch"

querystring = {"sortBy":"incidenceAngle"}

headers = {
    'authorization': "Bearer <access_token>",
    'cache-control': "no-cache",
    }

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

print(response.text)

In the above example, the incidenceAngle value request for a ranking from the lowest value to the highest, while the -incidenceAngle would provide the reverse result.

Paginate Results

The Living Library is updated on a daily basis and the number of images contained is huge. To access to your complete set of results, the search results are paginated. By default, a page contains up to 500 results. For example, the following request displays the for page 3, 100 results being contained in each page:

curl -X GET \
  'https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?itemsPerPage=100&startPage=3' \
  -H 'authorization: Bearer <access_token>' \
  -H 'cache-control: no-cache' \
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?itemsPerPage=100&startPage=3");
xhr.setRequestHeader("authorization", "Bearer <access_token>");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
url = "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch"

querystring = {"itemsPerPage":"100","startPage":"3"}

headers = {
    'authorization': "Bearer <access_token>",
    'cache-control': "no-cache",
    }

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

print(response.text)

Results

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

{
    "error": false,
    "features": [
        {
            "_links": {
                "delete": {
                    "href": "https://workspaces.oneatlas.private.geoapi-airbusds.com/api/v1/workspaces/0e33eb50-3404-48ad-b835-b0b4b72a5625/types/satellite_imagery/items/70cbe91b-1d33-4b1d-8575-2e411f4408e4",
                    "name": "Delete",
                    "type": "HTTP"
                },
                "imagesMetadata": [
                    {
                        "href": "https://view.oneatlas.geoapi-airbusds.com/api/v1/items/70cbe91b-1d33-4b1d-8575-2e411f4408e4/images/a38b4622-d9d6-4961-a15c-62f855e91f10/metadata",
                        "name": "multispectral",
                        "type": "application/geo+json"
                    },
                    {
                        "href": "https://view.oneatlas.geoapi-airbusds.com/api/v1/items/70cbe91b-1d33-4b1d-8575-2e411f4408e4/images/3b2999d9-2c06-4825-a286-45d676af0bdb/metadata",
                        "name": "panchromatic",
                        "type": "application/geo+json"
                    }
                ],
                "quicklook": {
                    "href": "https://view.oneatlas.geoapi-airbusds.com/api/v1/items/70cbe91b-1d33-4b1d-8575-2e411f4408e4/quicklook",
                    "name": "QuickLook",
                    "type": "HTTP"
                },
                "thumbnail": {
                    "href": "https://view.oneatlas.geoapi-airbusds.com/api/v1/items/70cbe91b-1d33-4b1d-8575-2e411f4408e4/thumbnail",
                    "name": "Thumbnail",
                    "type": "HTTP"
                },
                "wms": {
                    "href": "https://view.oneatlas.geoapi-airbusds.com/api/v1/items/70cbe91b-1d33-4b1d-8575-2e411f4408e4/wms",
                    "name": "WMS",
                    "type": "WMS"
                },
                "wmts": {
                    "href": "https://view.oneatlas.geoapi-airbusds.com/api/v1/items/70cbe91b-1d33-4b1d-8575-2e411f4408e4/wmts",
                    "name": "WMTS",
                    "type": "WMTS"
                }
            },
            "geometry": {
                "coordinates": [
                    [
                        [
                            80.64854048827965,
                            6.541075965707175
                        ],
                        [
                            80.86133469061163,
                            6.51243303769058
                        ],
                        [
                            80.86017240007504,
                            6.149419244953507
                        ],
                        [
                            80.64909009043556,
                            6.17490578111541
                        ],
                        [
                            80.64854048827965,
                            6.541075965707175
                        ]
                    ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "acquisitionDate": "2017-03-17T05:02:55.931Z",
                "acquisitionStation": "SE1",
                "archivingCenter": "FR1",
                "azimuthAngle": 179.9660145824179,
                "cloudCover": 8.15,
                "commercialReference": "SO18002850",
                "constellation": "PHR",
                "correlationId": "7e97fbc6-0835-4d2c-bbd0-3c9aa462bd52",
                "expirationDate": "2019-09-24T07:08:57.763103426Z",
                "format": "image/jp2",
                "id": "70cbe91b-1d33-4b1d-8575-2e411f4408e4",
                "illuminationAzimuthAngle": 105.4970996586585,
                "illuminationElevationAngle": 63.11566784992497,
                "incidenceAngle": 29.33247674644869,
                "incidenceAngleAcrossTrack": 16.79868544706851,
                "incidenceAngleAlongTrack": 25.35789980293259,
                "organisationName": "AIRBUS DS GEO",
                "parentIdentifier": "DS_PHR1B_201703170502559_FR1_PX_E080N06_1009_02963",
                "platform": "PHR1B",
                "processingCenter": "FCMUGC",
                "processingDate": "2018-02-14T10:18:57.468",
                "processingLevel": "SENSOR",
                "processorName": "DRS-MM V2.5vV2.5",
                "productCategory": "image",
                "productType": "bundle",
                "productionStatus": "IN_CLOUD",
                "publicationDate": "2018-09-24T07:08:57.763103426Z",
                "qualified": false,
                "resolution": 0.5,
                "sensorType": "OPTICAL",
                "snowCover": 0,
                "sourceIdentifier": "DS_PHR1B_201703170502189_FR1_PX_E080N06_1009_02959",
                "spectralRange": "VISIBLE",
                "title": "DS_PHR1B_201703170502189_FR1_PX_E080N06_1009_02959",
                "workspaceId": "0e33eb50-3404-48ad-b835-b0b4b72a5625",
                "workspaceName": "public",
                "workspaceTitle": "Public"
            },
            "rights": {
                "browse": {
                    "privileges": [
                        {
                            "filter": {
                                "workspaceId": "0e33eb50-3404-48ad-b835-b0b4b72a5625"
                            },
                            "id": "88875703-87b4-4b3e-a59d-8d9d602a4a5d",
                            "subscriptionId": "849a5574-f0f4-491d-896e-383311baf8ff"
                        },
                        {
                            "filter": {
                                "workspaceId": "0e33eb50-3404-48ad-b835-b0b4b72a5625"
                            },
                            "id": "a913caba-2fbe-4fd0-b038-5e114d9bd43e"
                        }
                    ]
                },
                "wms": {
                    "privileges": [
                        {
                            "filter": {
                                "workspaceId": "0e33eb50-3404-48ad-b835-b0b4b72a5625"
                            },
                            "id": "31408907-fd80-4067-a56c-3ccaf27bdabe",
                            "subscriptionId": "2f620fa8-18dd-4608-8e31-e4ea76a81210"
                        }
                    ]
                },
                "wmts": {
                    "privileges": [
                        {
                            "filter": {
                                "workspaceId": "0e33eb50-3404-48ad-b835-b0b4b72a5625"
                            },
                            "id": "31408907-fd80-4067-a56c-3ccaf27bdabe",
                            "subscriptionId": "2f620fa8-18dd-4608-8e31-e4ea76a81210"
                        }
                    ]
                }
            },
            "type": "Feature"
        },
        ...

A search response body contains the following components for each feature:

  • _links : Contains all the endpoints to access to the imagery in full resolution (using OGC protocols) or to access to the quicklooks.
  • geometry : Represents the footprint of the image. It’s a GeoJSON Polygon in WGS84 coordinates that represents the geographic area that was acquired by the satellite.
  • rights : Contains information regarding your authorization rights.
  • properties : Contains detailed metadata of the image. The most meaningful data is displayed in the table below.
Field nameDescription
idUnique identifier of the image in the catalog
parentIdentifierCorresponds to the Datastrip identifier, a datastrip being a portion of image downlinked during a pass of the satellite to a given ground station
acquisitionDateCorresponds to he acquisition date of the image
cloudCoverCorrespond to the average cloud coverage of an image, 0 meaning that the image is cloud free and 100 that the image is totally cloudy
snowCoverCorresponds to the average snow coverage of an image, 0 meaning that the image is snow free and 100 that the image is totally snowy
constellationName of the constellation, in the case of OneAtlas Data this value could be equal to SPOT of PHR
platformName of the satellite, in the case of OneAtlas Data, this value could be equal to SPOT6, SPOT7, PHR1A or PHR1B
incidenceAngleThe incidence angle is the angle from the target point of view. It represents the angle between the ground normal and look direction from the satellite, combining the pitch and roll angles.
resolutionThis corresponds to the satellite used. 0.5 for Pleiades and 1.5 for SPOT.