earthdaily.earthdatastore.Auth

class earthdaily.earthdatastore.Auth(config=None, presign_urls=True, asset_proxy_enabled=False)

Bases: object

A client for interacting with the Earth Data Store API. By default, Earth Data Store will look for environment variables called EDS_AUTH_URL, EDS_SECRET and EDS_CLIENT_ID.

Parameters:

• config (str | dict, optional) – The path to the json file containing the Earth Data Store credentials, or a dict with those credentials.

• asset_proxy_enabled (bool, optional) – Use asset proxy URLs, by default False

Return type:

None.

Example

>>> eds = earthdaily.earthdatastore()
>>> collection = "venus-l2a"
>>> theia_location = "MEAD"
>>> max_cloud_cover = 20
>>> query = { "theia:location": {"eq": theia_location}, "eo:cloud_cover": {"lt": max_cloud_cover} }
>>> items = eds.search(collections=collection, query=query)
>>> print(len(items))
132

Methods

datacube	Create a datacube.
explore	Explore a collection, its properties and assets.
find_cloud_mask_items	Search the catalog for the ag_cloud_mask items matching the given items_collection.
from_credentials	Secondary Constructor. Try to read Earth Data Store credentials from multiple sources, in the following order: - from input credentials stored in a given JSON file - from input credentials stored in a given TOML file - from environement variables - from the $HOME/.earthdaily/credentials TOML file and a given profile - from the $HOME/.earthdaily/credentials TOML file and the "default" profile.
get_access_token	Retrieve an access token for interacting with the EarthDataStore API.
read_credentials	Try to read Earth Data Store credentials from multiple sources, in the following order:
read_credentials_from_environment	Read Earth Data Store credentials from environment variables.
read_credentials_from_ini	Read Earth Data Store credentials from a ini file.
read_credentials_from_json	Read Earth Data Store credentials from a JSON file.
read_credentials_from_toml	Read Earth Data Store credentials from a TOML file
search	A wrapper around the pystac client search method.

Attributes

client

Create an instance of pystac client from EarthDataSTore

property client: Client

Create an instance of pystac client from EarthDataSTore

Return type:

A Client instance for this Catalog.

datacube(collections, datetime=None, assets=None, intersects=None, bbox=None, mask_with=None, mask_statistics=False, clear_cover=None, prefer_alternate='download', search_kwargs={}, add_default_scale_factor=True, common_band_names=True, cross_calibration_collection=None, properties=False, groupby_date='mean', cloud_search_kwargs={}, **kwargs)

Create a datacube.

Parameters:

• collections (str | list) – If several collections, the first collection will be the reference collection (for spatial resolution).

• datetime (Either a single datetime or datetime range used to filter results.) –

  You may express a single datetime using a datetime.datetime instance, a RFC 3339-compliant timestamp, or a simple date string (see below). Instances of datetime.datetime may be either timezone aware or unaware. Timezone aware instances will be converted to a UTC timestamp before being passed to the endpoint. Timezone unaware instances are assumed to represent UTC timestamps. You may represent a datetime range using a "/" separated string as described in the spec, or a list, tuple, or iterator of 2 timestamps or datetime instances. For open-ended ranges, use either ".." ('2020-01-01:00:00:00Z/..', ['2020-01-01:00:00:00Z', '..']) or a value of None (['2020-01-01:00:00:00Z', None]).

  If using a simple date string, the datetime can be specified in YYYY-mm-dd format, optionally truncating to YYYY-mm or just YYYY. Simple date strings will be expanded to include the entire time period, for example:

  • 2017 expands to 2017-01-01T00:00:00Z/2017-12-31T23:59:59Z

  • 2017-06 expands to 2017-06-01T00:00:00Z/2017-06-30T23:59:59Z

  • 2017-06-10 expands to 2017-06-10T00:00:00Z/2017-06-10T23:59:59Z

  If used in a range, the end of the range expands to the end of that day/month/year, for example:

  • 2017/2018 expands to 2017-01-01T00:00:00Z/2018-12-31T23:59:59Z

  • 2017-06/2017-07 expands to 2017-06-01T00:00:00Z/2017-07-31T23:59:59Z

  • 2017-06-10/2017-06-11 expands to 2017-06-10T00:00:00Z/2017-06-11T23:59:59Z

• assets (None | list | dict, optional) – DESCRIPTION. The default is None.

• intersects ((gpd.GeoDataFrame, str(wkt), dict(json)), optional) – DESCRIPTION. The default is None.

• bbox (TYPE, optional) – DESCRIPTION. The default is None.

• mask_with ((None, str, list), optional) – “native” mask, or “ag_cloud_mask”, or [“ag_cloud_mask”,”native”], and so if ag_cloud_mask is not available, will switch to native. The default is None.

• mask_statistics (bool | int, optional) – DESCRIPTION. The default is False.

• clear_cover ((int, float), optional) – Percent of clear data above a field (from 0 to 100). The default is None.

• prefer_alternate ((str, False), optional) – Uses the alternate/download href instead of the default href. The default is “download”.

• search_kwargs (dict, optional) – DESCRIPTION. The default is {}.

• add_default_scale_factor (bool, optional) – DESCRIPTION. The default is True.

• common_band_names (TYPE, optional) – DESCRIPTION. The default is True.

• cross_calibration_collection ((None | str), optional) – DESCRIPTION. The default is None.

• properties ((bool | str | list), optional) – Retrieve properties per item. The default is False.

• **kwargs (TYPE) –

  DESCRIPTION. : TYPE

  DESCRIPTION.

Raises:

• ValueError – DESCRIPTION.

• Warning – DESCRIPTION.

Returns:

xr_datacube – DESCRIPTION.

Return type:

TYPE

explore(collection=None)

Explore a collection, its properties and assets. If not collection specified, returns the list of collections.

Parameters:

collection (str, optional.) – Collection name. The default is None.

Returns:

The list of collections, or a collection to explore using module StacCollectionExplorer.

Return type:

str|StacCollectionExplorer

Example

>>> eds = earthdaily.earthdatastore()
>>> collection = "venus-l2a"
>>> eds.explore(collection).item_properties
{'constellation': 'VENUS',
 'created': '2023-06-14T00:14:10.167450Z',
 'datetime': '2023-06-07T11:23:18.000000Z',
 'description': '',
 'eda:geometry_tags': ['RESOLVED_CLOCKWISE_POLYGON'],
 'eda:loose_validation_status': 'VALID',
 'eda:num_cols': 9106,
 'eda:num_rows': 11001,
 'eda:original_geometry': {'type': 'Polygon',
  'coordinates': [[[-16.684545516968, 16.109294891357],
    [-16.344039916992, 16.111709594727],
    [-16.341398239136, 15.714001655579],
    [-16.68123626709, 15.711649894714],
    [-16.684545516968, 16.109294891357]]]},
 'eda:product_type': 'REFLECTANCE',
 'eda:sensor_type': 'OPTICAL',
 'eda:source_created': '2023-06-13T18:47:27.000000Z',
 'eda:source_updated': '2023-06-13T20:22:35.000000Z',
 'eda:status': 'PUBLISHED',
 'eda:tracking_id': 'MutZbYe54RY7eP3iuAbtKb',
 'eda:unusable_cover': 0.0,
 'eda:water_cover': 0.0,
 'end_datetime': '2023-06-07T11:23:18.000000Z',
 'eo:bands': [{'name': 'B1',
   'common_name': 'coastal',
   'description': 'B1',
   'center_wavelength': 0.424},
  {'name': 'B2',
   'common_name': 'coastal',
   'description': 'B2',
   'center_wavelength': 0.447},
  {'name': 'B3',
   'common_name': 'blue',
   'description': 'B3',
   'center_wavelength': 0.492},
  {'name': 'B4',
   'common_name': 'green',
   'description': 'B4',
   'center_wavelength': 0.555},
  {'name': 'B5',
   'common_name': 'yellow',
   'description': 'B5',
   'center_wavelength': 0.62},
  {'name': 'B6',
   'common_name': 'yellow',
   'description': 'B6',
   'center_wavelength': 0.62},
  {'name': 'B7',
   'common_name': 'red',
   'description': 'B7',
   'center_wavelength': 0.666},
  {'name': 'B8',
   'common_name': 'rededge',
   'description': 'B8',
   'center_wavelength': 0.702},
  {'name': 'B9',
   'common_name': 'rededge',
   'description': 'B9',
   'center_wavelength': 0.741},
  {'name': 'B10',
   'common_name': 'rededge',
   'description': 'B10',
   'center_wavelength': 0.782},
  {'name': 'B11',
   'common_name': 'nir08',
   'description': 'B11',
   'center_wavelength': 0.861},
  {'name': 'B12',
   'common_name': 'nir09',
   'description': 'B12',
   'center_wavelength': 0.909}],
 'eo:cloud_cover': 0.0,
 'gsd': 4.0,
 'instruments': ['VENUS'],
 'license': 'CC-BY-NC-4.0',
 'mission': 'venus',
 'platform': 'VENUS',
 'processing:level': 'L2A',
 'proj:epsg': 32628,
 'providers': [{'name': 'Theia',
   'roles': ['licensor', 'producer', 'processor']},
  {'url': 'https://earthdaily.com',
   'name': 'EarthDaily Analytics',
   'roles': ['processor', 'host']}],
 'sat:absolute_orbit': 31453,
 'start_datetime': '2023-06-07T11:23:18.000000Z',
 'theia:location': 'STLOUIS',
 'theia:product_id': 'VENUS-XS_20230607-112318-000_L2A_STLOUIS_C_V3-1',
 'theia:product_version': '3.1',
 'theia:publication_date': '2023-06-13T18:08:10.205000Z',
 'theia:sensor_mode': 'XS',
 'theia:source_uuid': 'a29bfc89-8372-5e91-841c-b11cdb40bb14',
 'title': 'VENUS-XS_20230607-112318-000_L2A_STLOUIS_D',
 'updated': '2023-06-14T00:42:17.898993Z',
 'view:azimuth': 33.293623499999995,
 'view:incidence_angle': 14.6423245,
 'view:sun_azimuth': 69.8849963957,
 'view:sun_elevation': 65.0159541684}

find_cloud_mask_items(items_collection, cloudmask='ag_cloud_mask', **kwargs)

Search the catalog for the ag_cloud_mask items matching the given items_collection. The ag_cloud_mask items are searched in the ag_cloud_mask_collection_id collection using the ag_cloud_mask_item_id properties of the items.

Parameters:

items_collection (pystac.ItemCollection) – The items to find corresponding ag cloud mask items for.

Returns:

The filtered item collection.

Return type:

pystac.ItemCollection

classmethod from_credentials(json_path=None, toml_path=None, profile=None, presign_urls=True, asset_proxy_enabled=False)

Secondary Constructor. Try to read Earth Data Store credentials from multiple sources, in the following order:

• from input credentials stored in a given JSON file

• from input credentials stored in a given TOML file

• from environement variables

• from the $HOME/.earthdaily/credentials TOML file and a given profile

• from the $HOME/.earthdaily/credentials TOML file and the “default” profile

Parameters:

• path (Path, optional) – The path to the TOML file containing the Earth Data Store credentials. Uses “$HOME/.earthdaily/credentials” by default.

• profile (profile, optional) – Name of the profile to use in the TOML file. Uses “default” by default.

• asset_proxy_enabled (bool, optional) – Use asset proxy URLs, by default False

Returns:

A Auth instance

Return type:

Auth

get_access_token(config=None)

Retrieve an access token for interacting with the EarthDataStore API.

By default, the method will look for environment variables: EDS_AUTH_URL, EDS_SECRET, and EDS_CLIENT_ID. Alternatively, a configuration object or dictionary can be passed to override these values.

Parameters:

config (EarthDataStoreConfig, optional) – A configuration object containing the Earth Data Store credentials.

Returns:

The access token for authenticating with the Earth Data Store API.

Return type:

str

classmethod read_credentials(json_path=None, toml_path=None, profile=None)

Try to read Earth Data Store credentials from multiple sources, in the following order:

• from input credentials stored in a given JSON file

• from input credentials stored in a given TOML file

• from environement variables

• from the $HOME/.earthdaily/credentials TOML file and a given profile

• from the $HOME/.earthdaily/credentials TOML file and the “default” profile

Parameters:

• path (Path, optional) – The path to the TOML file containing the Earth Data Store credentials. Uses “$HOME/.earthdaily/credentials” by default.

• profile (profile, optional) – Name of the profile to use in the TOML file. Uses “default” by default.

Returns:

Dictionary containing credentials

Return type:

dict

classmethod read_credentials_from_environment()

Read Earth Data Store credentials from environment variables.

Returns:

Dictionary containing credentials

Return type:

dict

classmethod read_credentials_from_ini(profile='default')

Read Earth Data Store credentials from a ini file.

Parameters:

ini_path (Path) – The path to the INI file containing the Earth Data Store credentials.

Returns:

Dictionary containing credentials

Return type:

dict

classmethod read_credentials_from_json(json_path)

Read Earth Data Store credentials from a JSON file.

Parameters:

json_path (Path) – The path to the JSON file containing the Earth Data Store credentials.

Returns:

Dictionary containing credentials

Return type:

dict

classmethod read_credentials_from_toml(toml_path=None, profile=None)

Read Earth Data Store credentials from a TOML file

Parameters:

• toml_path (Path, optional) – The path to the TOML file containing the Earth Data Store credentials.

• profile (profile, optional) – Name of the profile to use in the TOML file

Returns:

Dictionary containing credentials

Return type:

dict

search(collections, intersects=None, bbox=None, post_query=None, prefer_alternate=None, add_default_scale_factor=False, assets=None, raise_no_items=True, batch_days='auto', n_jobs=-1, **kwargs)

A wrapper around the pystac client search method. Add some features to enhance experience.

Parameters:

• collections (str | list) – Collection(s) to search. It is recommended to only search one collection at a time.

• intersects (gpd.GeoDataFrame, optional) – If provided, the results will contain only intersecting items. The default is None.

• bbox (TYPE, optional) – If provided, the results will contain only intersecting items. The default is None.

• post_query (TYPE, optional) – STAC-like filters applied on retrieved items. The default is None.

• prefer_alternate (TYPE, optional) – Prefer alternate links when available. The default is None.

• **kwargs (TYPE) – Keyword arguments passed to the pystac client search method.

Returns:

items_collection – The filtered STAC items.

Return type:

ItemCollection

Example

>>> items = eds.search(collections='sentinel-2-l2a',bbox=[1,43,1,43],datetime='2017')
>>> len(items)
27
>>> print(items[0].id)
S2A_31TCH_20170126_0_L2A
>>> print(items[0].assets.keys())
dict_keys(['aot', 'nir', 'red', 'scl', 'wvp', 'blue', 'green', 'nir08', 'nir09',
           'swir16', 'swir22', 'visual', 'aot-jp2', 'coastal', 'nir-jp2',
           'red-jp2', 'scl-jp2', 'wvp-jp2', 'blue-jp2', 'rededge1', 'rededge2',
           'rededge3', 'green-jp2', 'nir08-jp2', 'nir09-jp2', 'thumbnail',
           'swir16-jp2', 'swir22-jp2', 'visual-jp2', 'coastal-jp2',
           'rededge1-jp2', 'rededge2-jp2', 'rededge3-jp2', 'granule_metadata',
           'tileinfo_metadata'])
>>> print(items[0].properties)
{
    "created": "2020-09-01T04:59:33.629000Z",
    "updated": "2022-11-08T13:08:57.661605Z",
    "platform": "sentinel-2a",
    "grid:code": "MGRS-31TCH",
    "proj:epsg": 32631,
    "instruments": ["msi"],
    "s2:sequence": "0",
    "constellation": "sentinel-2",
    "mgrs:utm_zone": 31,
    "s2:granule_id": "S2A_OPER_MSI_L2A_TL_SHIT_20190506T054613_A008342_T31TCH_N00.01",
    "eo:cloud_cover": 26.518754,
    "s2:datatake_id": "GS2A_20170126T105321_008342_N00.01",
    "s2:product_uri": "S2A_MSIL2A_20170126T105321_N0001_R051_T31TCH_20190506T054611.SAFE",
    "s2:datastrip_id": "S2A_OPER_MSI_L2A_DS_SHIT_20190506T054613_S20170126T105612_N00.01",
    "s2:product_type": "S2MSI2A",
    "mgrs:grid_square": "CH",
    "s2:datatake_type": "INS-NOBS",
    "view:sun_azimuth": 161.807489888479,
    "eda:geometry_tags": ["RESOLVED_CLOCKWISE_POLYGON"],
    "mgrs:latitude_band": "T",
    "s2:generation_time": "2019-05-06T05:46:11.879Z",
    "view:sun_elevation": 26.561907592092602,
    "earthsearch:s3_path": "s3://sentinel-cogs/sentinel-s2-l2a-cogs/31/T/CH/2017/1/S2A_31TCH_20170126_0_L2A",
    "processing:software": {"sentinel2-to-stac": "0.1.0"},
    "s2:water_percentage": 0.697285,
    "eda:original_geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [0.5332306381710475, 43.32623760511659],
                [1.887065663431107, 43.347431265475954],
                [1.9046784554725638, 42.35884880571144],
                [0.5722310999779479, 42.3383710796791],
                [0.5332306381710475, 43.32623760511659],
            ]
        ],
    },
    "earthsearch:payload_id": "roda-sentinel2/workflow-sentinel2-to-stac/80f56ba6349cf8e21c1424491f1589c2",
    "s2:processing_baseline": "00.01",
    "s2:snow_ice_percentage": 23.041981,
    "s2:vegetation_percentage": 15.52531,
    "s2:thin_cirrus_percentage": 0.563798,
    "s2:cloud_shadow_percentage": 4.039595,
    "s2:nodata_pixel_percentage": 0.000723,
    "s2:unclassified_percentage": 9.891956,
    "s2:dark_features_percentage": 15.112966,
    "s2:not_vegetated_percentage": 5.172154,
    "earthsearch:boa_offset_applied": False,
    "s2:degraded_msi_data_percentage": 0.0,
    "s2:high_proba_clouds_percentage": 18.044451,
    "s2:reflectance_conversion_factor": 1.03230935243016,
    "s2:medium_proba_clouds_percentage": 7.910506,
    "s2:saturated_defective_pixel_percentage": 0.0,
    "eda:tracking_id": "eZbRVxsbEGdWLKXDK2i9Ve",
    "eda:status": "PUBLISHED",
    "datetime": "2017-01-26T10:56:12.238000Z",
    "eda:loose_validation_status": "VALID",
    "eda:ag_cloud_mask_available": False,
}