earthdata

The SlideRule Python API earthdata.py is used to access the indexing services provided institutions that maintain Earth science datasets (for example, NASA’s EarthData Common Metadata Repository, and USGS’s The National Map). From Python, the module can be imported via:

from sliderule import earthdata

set_max_resources

sliderule.earthdata.set_max_resources(max_resources)[source]

Sets the maximum allowed number of resources to be processed in one request. This is mainly provided as a sanity check for the user.

Parameters:

max_resources (int) – the maximum number of resources that are allowed to be processed in a single request

Examples

>>> from sliderule import icesat2
>>> earthdata.set_max_resources(1000)

cmr

sliderule.earthdata.cmr(short_name=None, version=None, polygon=None, time_start='2018-01-01T00:00:00Z', time_end='2025-09-17T12:23:59Z', return_metadata=False, name_filter=None)[source]

Query the NASA Common Metadata Repository (CMR) for a list of data within temporal and spatial parameters

Parameters:

  • short_name (str) – dataset short name as defined in the NASA CMR Directory

  • version (str) – dataset version string, leave as None to get latest support version

  • polygon (list) – either a single list of longitude,latitude in counter-clockwise order with first and last point matching, defining region of interest (see polygons), or a list of such lists when the region includes more than one polygon

  • time_start (str) – starting time for query in format <year>-<month>-<day>T<hour>:<minute>:<second>Z

  • time_end (str) – ending time for query in format <year>-<month>-<day>T<hour>:<minute>:<second>Z

  • return_metadata (bool) – flag indicating whether metadata associated with the query is returned back to the user

  • name_filter (str) – filter to apply to resources returned by query

Returns:

files (granules) for the dataset fitting the spatial and temporal parameters

Return type:

list

Examples

>>> from sliderule import earthdata
>>> region = [ {"lon": -108.3435200747503, "lat": 38.89102961045247},
...            {"lon": -107.7677425431139, "lat": 38.90611184543033},
...            {"lon": -107.7818591266989, "lat": 39.26613714985466},
...            {"lon": -108.3605610678553, "lat": 39.25086131372244},
...            {"lon": -108.3435200747503, "lat": 38.89102961045247} ]
>>> granules = earthdata.cmr(short_name='ATL06', polygon=region)
>>> granules
['ATL03_20181017222812_02950102_003_01.h5', 'ATL03_20181110092841_06530106_003_01.h5', ... 'ATL03_20201111102237_07370902_003_01.h5']

stac

sliderule.earthdata.stac(short_name=None, collections=None, polygon=None, time_start='2018-01-01T00:00:00Z', time_end='2025-09-17T12:23:59Z', as_str=True)[source]

Perform a STAC query of the NASA Common Metadata Repository (CMR) catalog for a list of data within temporal and spatial parameters

Parameters:

  • short_name (str) –

    dataset short name as defined in the NASA CMR Directory

  • collections (list) – list of dataset collections as specified by CMR, leave as None to use defaults

  • polygon (list) –

    either a single list of longitude,latitude in counter-clockwise order with first and last point matching, defining region of interest (see polygons), or a list of such lists when the region includes more than one polygon

  • time_start (str) – starting time for query in format <year>-<month>-<day>T<hour>:<minute>:<second>Z

  • time_end (str) – ending time for query in format <year>-<month>-<day>T<hour>:<minute>:<second>Z

  • as_str (bool) – whether to return geojson as a dictionary or string

Returns:

geojson of the feature set returned by the query {

”type”: “FeatureCollection”, “features”: [

{

“type”: “Feature”, “id”: “<id>”, “geometry”: {

”type”: “Polygon”, “coordinates”: [..]

}, “properties”: {

”datetime”: “YYYY-MM-DDTHH:MM:SS.SSSZ”, “start_datetime”: “YYYY-MM-DDTHH:MM:SS.SSSZ”, “end_datetime”: “YYYY-MM-DDTHH:MM:SS.SSSZ”, “<tag>”: “<url>”, ..

}

], “stac_version”: “<version>” “context”: {

”returned”: <returned>, “limit”: <limit>, “matched”: <matched>

}

}

Return type:

str

Examples

>>> from sliderule import earthdata
>>> region = [ {"lon": -108.3435200747503, "lat": 38.89102961045247},
...            {"lon": -107.7677425431139, "lat": 38.90611184543033},
...            {"lon": -107.7818591266989, "lat": 39.26613714985466},
...            {"lon": -108.3605610678553, "lat": 39.25086131372244},
...            {"lon": -108.3435200747503, "lat": 38.89102961045247} ]
>>> geojson = earthdata.stac(short_name='HLS', polygon=region)

tnm

sliderule.earthdata.tnm(short_name, polygon=None, time_start=None, time_end='2025-09-17', as_str=True)[source]

Query USGS National Map API for a list of data within temporal and spatial parameters. See https://apps.nationalmap.gov/help/documents/TNMAccessAPIDocumentation/TNMAccessAPIDocumentation.pdf for more details on the API.

Parameters:

  • short_name (str) – dataset name

  • polygon (list) –

    a single list of longitude,latitude in counter-clockwise order with first and last point matching, defining region of interest (see polygons)

  • time_start (str) – starting time for query in format <year>-<month>-<day>

  • time_end (str) – ending time for query in format <year>-<month>-<day>

Returns:

geojson of resources intersecting area of interest

Return type:

dict

Examples

>>> from sliderule import earthdata
>>> region = [ {"lon": -108.3435200747503, "lat": 38.89102961045247},
...            {"lon": -107.7677425431139, "lat": 38.90611184543033},
...            {"lon": -107.7818591266989, "lat": 39.26613714985466},
...            {"lon": -108.3605610678553, "lat": 39.25086131372244},
...            {"lon": -108.3435200747503, "lat": 38.89102961045247} ]
>>> geojson = earthdata.tnm(short_name='Digital Elevation Model (DEM) 1 meter', polygon=region)
>>> geojson
{'type': 'FeatureCollection', 'features': [{'type': 'Feature', 'id': '5eaa4a0582cefae35a21ee8c', 'geometry': {'type': 'Polygon'...