The EarthAI Catalog Query API

The Python API to Astraea's Earth OnDemand Catalog has 3 primary query functions:

collections() -> DataFrame
item_assets(c: collection) -> DataFrame
read_catalog(**query) -> GeoDataFrame

The ordering used above goes from most general to most specific. collections provides a list of the major datasets available in Earth OnDemand. assets describes the individual, discrete components of a data set, such as bands, metadata files, thumbnails, etc. Finally, read_catalog performs a spatiotemporal search over the catalog, delivering URIs to "assets" matching the query.

In the example below we will show examples of each of these. Further information can be found in the Earth OnDemand section of the EarthAI Users' Manual.

In [1]:

# Import the requisite module functions.
from earthai.earth_ondemand import *
import pandas as pd
# Turn off column truncation in Pandas.
pd.set_option('display.max_colwidth', -1)

The first query the available collections in Earth OnDemand and look at the schema to see the additional metadata available to us:

In [2]:

c = collections()
c.info()
display(c[['familyTitle', 'id', 'description']])

<class 'pandas.core.frame.DataFrame'>
RangeIndex: 11 entries, 0 to 10
Data columns (total 15 columns):
 #   Column           Non-Null Count  Dtype 
---  ------           --------------  ----- 
 0   allowed          11 non-null     bool  
 1   description      11 non-null     object
 2   familyId         11 non-null     object
 3   familyTitle      11 non-null     object
 4   id               11 non-null     object
 5   item_assets      11 non-null     object
 6   license          11 non-null     object
 7   presentable      11 non-null     bool  
 8   sortableFields   11 non-null     object
 9   stac_extensions  11 non-null     object
 10  stac_version     11 non-null     object
 11  title            11 non-null     object
 12  link             11 non-null     object
 13  spatial_extent   11 non-null     object
 14  temporal_extent  11 non-null     object
dtypes: bool(2), object(13)
memory usage: 1.3+ KB

	familyTitle	id	description
0	Landsat 8	landsat8_c2l1t1	Landsat 8 Collection 1 Tier 1 Precision Terrain from Landsat 8 Operational Land Imager (OLI) and Thermal Infrared Sensor (TIRS) data
1	MODIS	mcd43a4	MCD43A4: MODIS/Terra and Aqua Nadir BRDF-Adjusted Reflectance Daily L3 Global 500 m SIN Grid V006
2	MODIS	mod11a1	MOD11A1: MODIS/Terra Land Surface Temperature/Emissivity Daily L3 Global 1 km SIN Grid V006
3	MODIS	myd11a1	MYD11A1: MODIS/Aqua Land Surface Temperature/Emissivity Daily L3 Global 1 km SIN Grid V006
4	MODIS	mod13a1	MOD13A1: MODIS/Terra Vegetation Indices 16-Day L3 Global 500 m SIN Grid V006
5	MODIS	myd13a1	MYD13A1: MODIS/Aqua Vegetation Indices 16-Day L3 Global 500 m SIN Grid V006
6	Sentinel	sentinel2_l2a	Sentinel-2 Level-2A atmospherically corrected data
7	Sentinel	sentinel2_l1c	Sentinel-2 Level-1C top of atmosphere
8	NAIP	naip	National Agriculture Imagery Program aerial imagery
9	Maxar	maxar_open_data	Maxar Open Data
10	SpaceNet	spacenet7	SpaceNet 7 Imagery and Labels

Next, we'll take a look at the "assets" available in one of the collections, landsat8_c2l1t1.

In [3]:

item_assets('landsat8_c2l1t1')

Out[3]:

	asset_name	bundleable	eo_gsd	gsd	roles	title	type	collection_id	eo_bands_count	eo_bands_common_names
0	B5	True	30.0	30.0	[data]	Band 5 - Near Infrared (NIR) - 851-879nm (30m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	nir
1	thumb_large	True	NaN	NaN	[overview, preview]	Thumbnail - Large	image/jpeg	landsat8_c2l1t1	NaN	NaN
2	B6	True	30.0	30.0	[data]	Band 6 - Shortwave Infrared (SWIR) 1 - 1566-1651nm (30m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	swir16
3	B3	True	30.0	30.0	[data]	Band 3 - Green - 533-590nm (30m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	green
4	B2	True	30.0	30.0	[data]	Band 2 - Blue - 452-512nm (30m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	blue
5	BQA	True	30.0	30.0	[qa]	Band QA	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	NaN	NaN
6	B4	True	30.0	30.0	[data]	Band 4 - Red - 636-673nm (30m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	red
7	B1	True	30.0	30.0	[data]	Band 1 - Ultra Blue (coastal/aerosol) - 435-451nm (30m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	coastal
8	B11	True	30.0	30.0	[data]	Band 11 - Thermal Infrared (TIRS) 2 - 11500-12510nm (30m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	lwir12
9	MTL	True	NaN	NaN	[metadata]	Product Metadata	text/plain	landsat8_c2l1t1	NaN	NaN
10	thumb_small	True	NaN	NaN	[thumbnail]	Thumbnail - Small	image/jpeg	landsat8_c2l1t1	NaN	NaN
11	B9	True	30.0	30.0	[data]	Band 9 - Cirrus - 1363-1384nm (30m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	cirrus
12	B7	True	30.0	30.0	[data]	Band 7 - Shortwave Infrared (SWIR) 2 - 2107-2294nm (30m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	swir22
13	B10	True	30.0	30.0	[data]	Band 10 - Thermal Infrared (TIRS) 1 - 10600-11190nm (30m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	lwir11
14	B8	True	15.0	15.0	[data]	Band 8 - Panchromatic - 503-676nm (15m)	image/tiff; application=geotiff; profile=cloud-optimized	landsat8_c2l1t1	1.0	pan
15	ANG	True	NaN	NaN	[metadata]	Angle Coefficient Metadata	text/plain	landsat8_c2l1t1	NaN	NaN

Now that we know what assets are available in the landsat8_c2l1t1 collection, we can perform our query and select the specific bands we care about. For example, if we want "red" and "nir" for computing NDVI, we'll select bands B4 (red) and B5 (NIR).

There are two different approaches to performing our search. The first is to perform a "code based query" in Python:

In [4]:

search_results1 = read_catalog(
    collections='landsat8_c2l1t1', 
    geo=[
        -122.5456,
        37.602333,
        -122.339630,
        37.82193606
    ],
    max_cloud_cover=10,
    start_datetime='2020-01-01',
    end_datetime='2020-04-25'
)

search_results1[['B4', 'B5']]

Out[4]:

	B4	B5
0	https://landsat-pds.s3.us-west-2.amazonaws.com/c1/L8/044/034/LC08_L1TP_044034_20200302_20200314_01_T1/LC08_L1TP_044034_20200302_20200314_01_T1_B4.TIF	https://landsat-pds.s3.us-west-2.amazonaws.com/c1/L8/044/034/LC08_L1TP_044034_20200302_20200314_01_T1/LC08_L1TP_044034_20200302_20200314_01_T1_B5.TIF
1	https://landsat-pds.s3.us-west-2.amazonaws.com/c1/L8/044/034/LC08_L1TP_044034_20200403_20200410_01_T1/LC08_L1TP_044034_20200403_20200410_01_T1_B4.TIF	https://landsat-pds.s3.us-west-2.amazonaws.com/c1/L8/044/034/LC08_L1TP_044034_20200403_20200410_01_T1/LC08_L1TP_044034_20200403_20200410_01_T1_B5.TIF

The second approach is to use the %%eod magic, which allows you to use a web-based query exported from the Earth OnDemand web application.

In [5]:

%%eod --name search_results2
{
    "collections": [
        "landsat8_c2l1t1"
    ],
    "geo": [
        -122.5456,
        37.602333,
        -122.339630,
        37.82193606
    ],
    "max_cloud_cover": 10,
    "start_datetime": "2020-01-01T00:00:00.000Z",
    "end_datetime": "2020-04-25T00:00:00.000Z"
}

Out[5]:

Query returned 2 results, stored as a GeoDataFrame in 'search_results2'

search_results2 metadata

<class 'geopandas.geodataframe.GeoDataFrame'>
RangeIndex: 2 entries, 0 to 1
Data columns (total 52 columns):
 #   Column                              Non-Null Count  Dtype              
---  ------                              --------------  -----              
 0   eod_collection_attribution          2 non-null      object             
 1   eod_collection_display_name         2 non-null      object             
 2   eod_collection_family               2 non-null      object             
 3   eod_collection_family_display_name  2 non-null      object             
 4   eod_epsg4326_geometry_simplified    2 non-null      object             
 5   eod_grid_id                         2 non-null      object             
 6   eod_item_attribution                2 non-null      object             
 7   eod_item_family                     2 non-null      object             
 8   created                             2 non-null      object             
 9   datetime                            2 non-null      datetime64[ns, UTC]
 10  eo_cloud_cover                      2 non-null      float64            
 11  eo_constellation                    2 non-null      object             
 12  eo_epsg                             2 non-null      int64              
 13  eo_gsd                              2 non-null      float64            
 14  eo_instrument                       2 non-null      object             
 15  eo_platform                         2 non-null      object             
 16  gsd                                 2 non-null      float64            
 17  license                             2 non-null      object             
 18  proj_crs                            2 non-null      object             
 19  proj_epsg                           2 non-null      int64              
 20  proj_geometry                       2 non-null      object             
 21  updated                             2 non-null      object             
 22  B5                                  2 non-null      object             
 23  thumb_large                         2 non-null      object             
 24  B6                                  2 non-null      object             
 25  B3                                  2 non-null      object             
 26  B2                                  2 non-null      object             
 27  BQA                                 2 non-null      object             
 28  B4                                  2 non-null      object             
 29  B1                                  2 non-null      object             
 30  B11                                 2 non-null      object             
 31  MTL                                 2 non-null      object             
 32  thumb_small                         2 non-null      object             
 33  B9                                  2 non-null      object             
 34  B7                                  2 non-null      object             
 35  B10                                 2 non-null      object             
 36  B8                                  2 non-null      object             
 37  ANG                                 2 non-null      object             
 38  self_link                           2 non-null      object             
 39  preview_link                        2 non-null      object             
 40  bundle_link                         2 non-null      object             
 41  fullres_link                        2 non-null      object             
 42  maplayer_link                       2 non-null      object             
 43  maplayer-zxy_link                   2 non-null      object             
 44  leaflet_link                        2 non-null      object             
 45  statistics_link                     2 non-null      object             
 46  tileinfo_link                       2 non-null      object             
 47  esri-tile-layer_link                2 non-null      object             
 48  license_link                        2 non-null      object             
 49  collection                          2 non-null      object             
 50  geometry                            2 non-null      geometry           
 51  id                                  2 non-null      object             
dtypes: datetime64[ns, UTC](1), float64(3), geometry(1), int64(2), object(45)
memory usage: 960.0+ bytes

In [6]:

search_results2[['B4', 'B5']]

Out[6]:

	B4	B5
0	https://landsat-pds.s3.us-west-2.amazonaws.com/c1/L8/044/034/LC08_L1TP_044034_20200302_20200314_01_T1/LC08_L1TP_044034_20200302_20200314_01_T1_B4.TIF	https://landsat-pds.s3.us-west-2.amazonaws.com/c1/L8/044/034/LC08_L1TP_044034_20200302_20200314_01_T1/LC08_L1TP_044034_20200302_20200314_01_T1_B5.TIF
1	https://landsat-pds.s3.us-west-2.amazonaws.com/c1/L8/044/034/LC08_L1TP_044034_20200403_20200410_01_T1/LC08_L1TP_044034_20200403_20200410_01_T1_B4.TIF	https://landsat-pds.s3.us-west-2.amazonaws.com/c1/L8/044/034/LC08_L1TP_044034_20200403_20200410_01_T1/LC08_L1TP_044034_20200403_20200410_01_T1_B5.TIF

eai-catalog-query-api.ipynb
50 KB Download

EarthAI Platform Support Portal

Comments

EarthAI Platform Support Portal

Related articles