Language
In this Tutorial
  1. Search & Display image of the California wildfire
    1. Authenticate
    2. Search images
      1. Opensearch
      2. Quicklook
    3. Tiles
      1. WMTS
      2. One tile
      3. Large tiled image
      4. In time

Search & Display image of the California wildfire

Discover the full capabilities of OneAtlas through this tutorial which describes how to use the API to study the impact of wildfires in California. The 2018 wildfire season was the most destructive wildfire season ever recorded in California. Satellite imagery helps to measure the extent of the damage. Through this tutorial, you will discover how to search images in an area and stream the images over the weeks around the wildfires.

Authenticate

Before you can get started, you first need the key to open the door to our APIs! You can get your API Key by signing into your OneAtlas account and using our API Key Generator. Make sure to keep this safe, you will need this in the next step.

Don’t yet have a OneAtlas Account? Feel free to contact us via our main OneAtlas page.

Next you need to use the /auth/realms/IDP/protocol/openid-connect/token endpoint, replacing your API key which you have generated before.

r = requests.post('https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token',
                  headers={'Content-Type':'application/x-www-form-urlencoded'},
                  data={'apikey':<api_key>, 'grant_type':'api_key', 'client_id':'IDP'})

token = r.json()['access_token']

You will be provided with an access token:

{
    "access_token": "<access_token>",
    "expires_in": 3600,
    "refresh_expires_in": 0,
    "token_type": "bearer"
}

Search images

You have the possibility to search images using opensearch with custom parameters. The quicklook will enable you to display the image and see if this image corresponds to your needs.

Opensearch

Searching our Living Library is simple. All you need to do is call the /opensearch endpoint and provide parameters in compliance with OpenSearch standard. These parameters can include a bounding box, GeoJSON polygon, dates and more.


For more information about these filters, take a look at some examples in the Search Guide


In this tutorial, we will use some filters to search images :

  • Display of Pleiades images only
  • Display of images around our area of interest
  • acquisition dates around the wildfires
params = {
    'lat': 39.812939, 
    'lon': -121.402845,
    'format':'image/jp2',
    'constellation':'PHR',
    'acquisitionDate':'[2016,2019[',
    'sortBy':'acquisitionDate'
}

r = requests.get('https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch',
                 headers={'Content-Type':'application/json', 'Authorization':f'Bearer {<token>}'},
                 params=params)

r_search = r.json()

This will return 4 images according to your search parameters.

{
    "error":"false"
    "features" : [] #4 items
    "itemsPerPage":50
    "startIndex":0
    "totalResults":4
    "type":"FeatureCollection"
}

The first feature look like :

{
    "_links": {
        "delete": {
            "href": "https://workspaces.foundation.api.oneatlas.airbus.com/api/v1/workspaces/0e33eb50-3404-48ad-b835-b0b4b72a5625/items/0b714827-923b-4eb7-9946-914870670927",
            "name": "Delete",
            "type": "HTTP"
        },
        "imagesGetBuffer": [
            {
                "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/images/7ebe5ba4-fafd-4b91-ae11-04c637dffa25/buffer",
                "name": "panchromatic",
                "resourceId": "7ebe5ba4-fafd-4b91-ae11-04c637dffa25",
                "type": "getBuffer"
            },
            {
                "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/images/9d594bc8-a632-4cdc-a619-d99636fb57a9/buffer",
                "name": "multispectral",
                "resourceId": "9d594bc8-a632-4cdc-a619-d99636fb57a9",
                "type": "getBuffer"
            }
        ],
        "imagesMetadata": [
            {
                "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/images/7ebe5ba4-fafd-4b91-ae11-04c637dffa25/metadata",
                "name": "panchromatic",
                "resourceId": "7ebe5ba4-fafd-4b91-ae11-04c637dffa25",
                "type": "application/geo+json"
            },
            {
                "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/images/9d594bc8-a632-4cdc-a619-d99636fb57a9/metadata",
                "name": "multispectral",
                "resourceId": "9d594bc8-a632-4cdc-a619-d99636fb57a9",
                "type": "application/geo+json"
            }
        ],
        "imagesWcs": [
            {
                "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/images/7ebe5ba4-fafd-4b91-ae11-04c637dffa25/wcs",
                "name": "panchromatic",
                "resourceId": "7ebe5ba4-fafd-4b91-ae11-04c637dffa25",
                "type": "WCS"
            },
            {
                "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/images/9d594bc8-a632-4cdc-a619-d99636fb57a9/wcs",
                "name": "multispectral",
                "resourceId": "9d594bc8-a632-4cdc-a619-d99636fb57a9",
                "type": "WCS"
            }
        ],
        "imagesWms": [
            {
                "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/images/7ebe5ba4-fafd-4b91-ae11-04c637dffa25/wms",
                "name": "panchromatic",
                "resourceId": "7ebe5ba4-fafd-4b91-ae11-04c637dffa25",
                "type": "WMS"
            },
            {
                "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/images/9d594bc8-a632-4cdc-a619-d99636fb57a9/wms",
                "name": "multispectral",
                "resourceId": "9d594bc8-a632-4cdc-a619-d99636fb57a9",
                "type": "WMS"
            }
        ],
        "imagesWmts": [
            {
                "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/images/7ebe5ba4-fafd-4b91-ae11-04c637dffa25/wmts",
                "name": "panchromatic",
                "resourceId": "7ebe5ba4-fafd-4b91-ae11-04c637dffa25",
                "type": "WMTS"
            },
            {
                "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/images/9d594bc8-a632-4cdc-a619-d99636fb57a9/wmts",
                "name": "multispectral",
                "resourceId": "9d594bc8-a632-4cdc-a619-d99636fb57a9",
                "type": "WMTS"
            }
        ],
        "quicklook": {
            "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/quicklook",
            "name": "QuickLook",
            "type": "HTTP"
        },
        "thumbnail": {
            "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/thumbnail",
            "name": "Thumbnail",
            "type": "HTTP"
        },
        "wms": {
            "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/wms",
            "name": "WMS",
            "type": "WMS"
        },
        "wmts": {
            "href": "https://access.foundation.api.oneatlas.airbus.com/api/v1/items/0b714827-923b-4eb7-9946-914870670927/wmts",
            "name": "WMTS",
            "type": "WMTS"
        }
    },
    "geometry": {
        "coordinates": [
            [
                [
                    -121.6342241121392,
                    40.01729501639826
                ],
                [
                    -121.377538588148,
                    40.02948027141388
                ],
                [
                    -121.3791205074043,
                    39.6738373702358
                ],
                [
                    -121.6348867556071,
                    39.66054199225062
                ],
                [
                    -121.6342241121392,
                    40.01729501639826
                ]
            ]
        ],
        "type": "Polygon"
    },
    "properties": {
        "acquisitionDate": "2016-12-21T19:03:33.306Z",
        "acquisitionIdentifier": "DS_PHR1B_201612211903333_FR1_PX_W122N39_0621_02996",
        "acquisitionStation": "FR1",
        "archivingCenter": "FR1",
        "azimuthAngle": 179.9848966869066,
        "cloudCover": 0.75,
        "commercialReference": "SO18006327",
        "constellation": "PHR",
        "correlationId": "71f71a8d-8504-42d4-bb9f-3f03c9d84f07",
        "dataUri": "gs://tcifg-idp-prod-datastore-data-pilot-nearline/R_PHR2016_Q4_10_176_SO18006327-76-01_DS_PHR1B_201612211903333_FR1_PX_W122N39_0621_02996.zip",
        "expirationDate": "2020-02-23T02:25:38.73542233Z",
        "format": "image/jp2",
        "id": "0b714827-923b-4eb7-9946-914870670927",
        "illuminationAzimuthAngle": 164.4056179808057,
        "illuminationElevationAngle": 25.293884733098,
        "incidenceAngle": 24.3188992240007,
        "incidenceAngleAcrossTrack": 6.536331698767763,
        "incidenceAngleAlongTrack": -23.61245854581714,
        "organisationName": "AIRBUS DS GEO",
        "parentIdentifier": "DS_PHR1B_201612211903333_FR1_PX_W122N39_0621_02996",
        "platform": "PHR1B",
        "processingCenter": "FCMUGC",
        "processingDate": "2018-03-18T08:14:04.812",
        "processingLevel": "SENSOR",
        "processorName": "DRS-MM V2.5vV2.5",
        "productCategory": "image",
        "productType": "bundle",
        "productionStatus": "IN_CLOUD",
        "publicationDate": "2019-02-23T02:25:38.73542233Z",
        "qualified": false,
        "resolution": 0.5,
        "sensorType": "OPTICAL",
        "snowCover": 99.86,
        "sourceIdentifier": "DS_PHR1B_201612211902573_FR1_PX_W122N39_0621_02992",
        "spectralRange": "VISIBLE",
        "title": "DS_PHR1B_201612211902573_FR1_PX_W122N39_0621_02992",
        "workspaceId": "0e33eb50-3404-48ad-b835-b0b4b72a5625",
        "workspaceName": "public",
        "workspaceTitle": "Public"
    },
    "rights": {
        "browse": {},
        "wms": {},
        "wmts": {}
    },
    "type": "Feature"
}

Quicklook

We will now display the first result of our research by requesting its quicklook.

feature = r_search['features'][-1]

r = requests.get(feature['_links']['quicklook']['href'],
                 headers={'Authorization':f'Bearer {token}'})

quicklook = load_image(r)

save_and_display_image(quicklook, 'quicklook.jpg')

QuickLook

Tiles

Our search APIs allow you to receive mapping tiles in both WMS and WMTS streaming formats.
Consult our View service guide to learn more about the WMTS streaming format.

WMTS

The example below shows a WMTS request.
This will return the GetCapabilities XML file for the image you wish to stream.
We have to extract the template to request tiles.

r = requests.get(feature['_links']['wmts']['href'],
                 headers={'Authorization':f'Bearer {token}'})

xml = extract_xml(r)

template = extract_template(xml)

print_wmts(xml)

One tile

We will now display one tile. You will need to enter the following WMTS parameters:

  • style
  • projection (tile matrix set) : here we choose WebMercator projection EPSG:3857
  • zoom (tile matrix)
  • column & row
  • Get the tile column & row with our converter

Python users can access this with the mercantile library:

# Basic parameters
style = 'rgb'
projection = 'EPSG3857' # WebMercator projection EPSG:3857
zoom = 14 # around 10m resolution

# Get col & row match lon & lat & zoom according to the WebMercator projection
origin = mercantile.tile(params['lon'], params['lat'], zoom)
col = origin.x
row = origin.y

# Format the wmts template
formatted_template = format_template(template, style, projection, zoom, col, row)

# Request the tile using it
r = requests.get(formatted_template,
                 headers={'Authorization':f'Bearer {token}'})

tile = load_image(r)
save_and_display_image(tile, 'tile.jpg')

Tile

Large tiled image

It is possible to request n*n tiles to build a large tiled image.

n_tiles = 2 # large image = n*n tiles

large_tile = build_large_tile(token, template, zoom, origin, n_tiles)

save_and_display_image(large_tile, 'large_tile.jpg')

LargeTile

In time

Finally, we can build a gif to have a sweet time comparison.

features = r_search['features']

request_images_and_build_gif(token, features, zoom, origin, n_tiles, 'in_time')

display_saved_image('in_time.gif')

The gif quality has been reduced for the web display.

InTime

We want to hear from you. If you require assistance, please contact the support by clicking on Contact Us.
See the whole code on GitHub.