Language
Mobile SDK Guide
  1. Search
    1. Presentation
    2. Searching the Living Library
    3. Searching Your Private Workspace
    4. Filtering
      1. Create-a-Complex-Filter
      2. Geographic Filters
      3. Resolution Filters
      4. Acquisition Date Filters
      5. Other filters
      6. Sort Results
    5. Results

Presentation

Note: To gain access to OneAtlas Data you need to be authenticated (see the dedicated Prerequisites section to get an API key)

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 service allows users to perform complex searches by filtering using different parameters and specifying geographic criteria.

Searching the Living Library

By default, a search is performed on all your authorized scopes. This includes the Living Library (which is a public workspace) and your own private workspace. You may perform a search in the Living Library by using its workspace ID defined in the OneAtlas class.


Here is example of searching images in the Living Library, from a given location:

// Search for images in the Living Library
SearchFilter filter = new SearchFilter.Builder()
        .setGeometry(new Point(43.0, 3.0))
        .build();
SearchSort sortBy = new SearchSort.Builder()
        .sortByAcquisitionDate(SortOrder.DESCENDING)
        .build();
// Get the first page with 10 items per page
OneAtlas.getInstance().getSearchService().openSearch(1, 10, filter, OneAtlas.LIVING_LIBRARY_WORKSPACE_ID, sortBy, page -> {
    // Handle your search results
    List<Feature> features = page.getItems();
}, exception -> {
    // Error management
});
val filter = SearchFilter.Builder()
        .setGeometry(Point(43.0, 3.0))
        .build()
val sortBy = SearchSort.Builder()
        .sortByAcquisitionDate(SortOrder.DESCENDING)
        .build()
// Get the first page with 10 items per page
OneAtlas.getInstance().searchService.openSearch(1, 10, filter, OneAtlas.LIVING_LIBRARY_WORKSPACE_ID, sortBy, { page ->
    // Handle your search results
    val features = page.items
}, { exception ->
    // Error management
})

Searching Your Private Workspace

In addition to the Living Library, any OneAtlas user has a private workspace which contains his products. In order to search his data, a user must retrieve his workspace ID using the getMe method of the Data service. Finally, searching for products in your private workspace simply consists in specifying the workspace ID in the search request.

// Get the user's workspace ID
OneAtlas.getInstance().getDataService().getMe(user -> {
    String workspaceId = user.getContract().getWorkspaceId();
}, exception -> {
    // Error management
});
...
// Search the user's workspace
OneAtlas.getInstance().getSearchService().openSearch(1, 10, null, workspaceId, null, page -> {
    // Handle your search results
    List<Feature> features = page.getItems();
}, exception -> {
    // Error management
});
// Get the users workspace ID
OneAtlas.getInstance().dataService.getMe({ user ->
    val workspaceId = user.contract.workspaceId
}, { exception ->
    // Error management
})
...
// Search the user's workspace
OneAtlas.getInstance().searchService.openSearch(1, 10, null, workspaceId, null, { page ->
    // Handle your search results
    val features = page.items
}, { exception ->
    // Error management
})

Filtering

Create a Complex Filter

This section shows how to enqueue several search criteria into an filter object.

In this sample we requested all images that:

  • intersects with a requested point (Lat:43°, Lon:3°) (you can also pass a rectangle or a polygon: check the geometry class)
  • with a resolution of 0.5m
  • with a max incidence angle of 10° (included)
  • with a max cloud cover of 20% (excluded)
SearchFilter complexFilter = new SearchFilter.Builder()
        .setGeometry(new Point(43.0, 3.0))
        .setRelation(Relation.INTERSECTS)
        .addConstellation(Constellation.PLEIADES)
        .setMaxResolution(0.5, true)
        .setMaxIncidenceAngle(10, true)
        .setMaxCloudCover(20, false)
        .build();
val complexFilter = SearchFilter.Builder()
        .setGeometry(Point(43.0, 3.0))
        .setRelation(Relation.INTERSECTS)
        .addConstellation(Constellation.PLEIADES)
        .setMaxResolution(0.5, true)
        .setMaxIncidenceAngle(10.0, true)
        .setMaxCloudCover(20.0, false)
        .build()

Geographic Filters

The Search API returns all images that intersect with a requested extent. The AOI can be a rectangle or a polygon: check the geometry class.


Below is an example to search for images within a polygon centered over Toulouse:

SearchFilter geographicFilter = new SearchFilter.Builder()
        .setGeometry(new Point(43.0, 3.0))
        .build();
val geographicFilter = SearchFilter.Builder()
        .setGeometry(Point(43.0, 3.0))
        .build()

All the coordinates are expressed as a longitude and latitude coordinates, in decimal degrees in EPSG:4326 (typical WGS84 coordinates as returned by a GPS receiver).

Resolution Filters

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

Field nameValueResolution
ConstellationPHR0.5m
ConstellationSPOT1.5m
SearchFilter contellationFilter = new SearchFilter.Builder()
        .addConstellation(Constellation.PLEIADES)
        .build();
val contellationFilter = SearchFilter.Builder()
        .addConstellation(Constellation.PLEIADES)
        .build()

Acquisition Date Filters

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 code searches for images which have an acquisition date that is less than 3 months from now:

Calendar c = Calendar.getInstance();
c.setTime(new Date());
c.add(Calendar.MONTH, -3);
SearchFilter dateFilter = new SearchFilter.Builder()
        .setMinAcquisitionDate(c.getTime(), true)
        .build();
val c = Calendar.getInstance()
c.time = Date()
c.add(Calendar.MONTH, -3)
val dateFilter = SearchFilter.Builder()
        .setMinAcquisitionDate(c.time, true)
        .build()

Other filters

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%:

SearchFilter cloudCoverFilter = new SearchFilter.Builder()
        .setMaxCloudCover(10, true)
        .build();
val cloudCoverFilter = SearchFilter.Builder()
        .setMaxCloudCover(10.0, true)
        .build()

The SDK also allows you to filter by incidence angle, in the same way.

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:

SearchSort sortBy = new SearchSort.Builder()
        .sortByIncidenceAngle(SortOrder.DESCENDING)
        .build();
val sortBy = SearchSort.Builder()
        .sortByIncidenceAngle(SortOrder.DESCENDING)
        .build()

Results

Each matching image is a product feature object (see the SDK reference).


A search response object contains features components composed by:

  • a unique identifier of the image product.
  • a quicklook URL in order to access to the quicklook.
  • a thumbnail URL in order to the access to the thumbnail.
  • a geometry representing the footprint of the image.
  • properties containing detailed metadata of the image product.

The most meaningful data for an image is displayed in the table below:

ContentDescription
parentIdCorresponds to the Datastrip identifier, a datastrip being an image downlinked during a pass of the satellite to a given ground station.
acquisitionDateCorresponds to the date when the image has been taken.
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.
incidenceAngleThis is the angle between the ground normal at image center and the satellite direction.