earthdaily.legacy.earthdatastore.Auth

class earthdaily.legacy.earthdatastore.Auth(api_requester, presign_urls=True, asset_proxy_enabled=False)[source]

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.
`search`	A wrapper around the pystac client search method.

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)[source]

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:

ds – DESCRIPTION.

Return type:

TYPE

explore(collection=None)[source]

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'],
 ...
}

find_cloud_mask_items(items_collection, cloudmask='ag_cloud_mask', **kwargs)[source]

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

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, deduplicate_items=True, **kwargs)[source]

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', ... , '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",
    ...
}