Documentation for Granules

DataGranules is the class earthaccess uses to query CMR at the granule level.

Bases: GranuleQuery

A Granule oriented client for NASA CMR.

Api

https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html

bounding_box(lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)

Filter by granules that overlap a bounding box. Must be used in combination with a collection filtering parameter such as short_name or entry_title.

Parameters:

Name	Type	Description	Default
lower_left_lon	FloatLike	lower left longitude of the box	required
lower_left_lat	FloatLike	lower left latitude of the box	required
upper_right_lon	FloatLike	upper right longitude of the box	required
upper_right_lat	FloatLike	upper right latitude of the box	required

Returns:

Type	Description
Self	self

Raises:

Type	Description
ValueError	A coordinate could not be converted to a float.

cloud_cover(min_cover=0, max_cover=100)

Filter by the percentage of cloud cover present in the granule.

Parameters:

Name	Type	Description	Default
min_cover	Optional[FloatLike]	minimum percentage of cloud cover	0
max_cover	Optional[FloatLike]	maximum percentage of cloud cover	100

Returns:

Type	Description
Self	self

Raises:

Type	Description
ValueError	min_cover or max_cover is not convertible to a float, or min_cover is greater than max_cover.

cloud_hosted(cloud_hosted=True)

Only match granules that are hosted in the cloud. This is valid for public collections and when using the short_name parameter. Concept-Id is unambiguous.

Tip

Cloud-hosted collections can be public or restricted. Restricted collections will not be matched using this parameter.

Parameters:

Name	Type	Description	Default
cloud_hosted	bool	If True, obtain only granules from cloud-hosted collections.	True

Returns:

Type	Description
Self	self

Raises:

Type	Description
TypeError	cloud_hosted is not of type bool.

daac(daac_short_name)

Only match collections for a given DAAC. Default to on-prem collections for the DAAC.

Parameters:

Name	Type	Description	Default
daac_short_name	str	a DAAC shortname, e.g. NSIDC, PODAAC, GESDISC	required

Returns:

Type	Description
Self	self

data_center(data_center_name)

An alias for the daac method.

Parameters:

Name	Type	Description	Default
data_center_name	String	DAAC shortname, e.g. NSIDC, PODAAC, GESDISC	required

Returns:

Type	Description
Self	self

day_night_flag(day_night_flag)

Filter by period of the day the granule was collected during.

Parameters:

Name	Type	Description	Default
day_night_flag	str	"day", "night", or "unspecified"	required

Returns:

Type	Description
Self	self

Raises:

Type	Description
TypeError	day_night_flag is not of type str.
ValueError	day_night_flag is not one of "day", "night", or "unspecified".

debug(debug=True)

If True, prints the actual query to CMR, notice that the pagination happens in the headers.

Parameters:

Name	Type	Description	Default
debug	bool	If True, print the CMR query.	True

Returns:

Type	Description
Self	self

doi(doi)

Search data granules by DOI.

Tip

Not all datasets have an associated DOI, internally if a DOI is found earthaccess will grab the concept_id for the query to CMR.

Parameters:

Name	Type	Description	Default
doi	str	DOI of a dataset, e.g. 10.5067/AQR50-3Q7CS	required

Returns:

Type	Description
Self	self

Raises:

Type	Description
RuntimeError	The CMR query to get the collection for the DOI fails.

downloadable(downloadable=True)

Only match granules that are available for download. The inverse of this method is online_only.

Parameters:

Name	Type	Description	Default
downloadable	bool	If True, obtain only granules that are downloadable.	True

Returns:

Type	Description
Self	self

Raises:

Type	Description
TypeError	downloadable is not of type bool.

get(limit=2000)

Get all the collections (datasets) that match with our current parameters up to some limit, even if spanning multiple pages.

Tip

The default page size is 2000, we need to be careful with the request size because all the JSON elements will be loaded into memory. This is more of an issue with granules than collections as they can be potentially millions of them.

Parameters:

Name	Type	Description	Default
limit	int	The number of results to return.	2000

Returns:

Type	Description
List[DataGranule]	Query results as a (possibly empty) list of DataGranules instances.

Raises:

Type	Description
RuntimeError	The CMR query failed.

granule_name(granule_name)

Find granules matching either granule ur or producer granule id, queries using the readable_granule_name metadata field.

Tip

We can use wildcards on a granule name to further refine our search, e.g. MODGRNLD.*.daily.*.

Parameters:

Name	Type	Description	Default
granule_name	str	granule name (accepts wildcards)	required

Returns:

Type	Description
Self	self

Raises:

Type	Description
TypeError	if granule_name is not of type str

hits()

Returns the number of hits the current query will return.

This is done by making a lightweight query to CMR and inspecting the returned headers.

Returns:

Type	Description
int	The number of results reported by the CMR.

Raises:

Type	Description
RuntimeError	The CMR query failed.

instrument(instrument)

Filter by the instrument associated with the granule.

Parameters:

Name	Type	Description	Default
instrument	str	name of the instrument	required

Returns:

Type	Description
Self	self

Raises:

Type	Description
ValueError	instrument is not a non-empty string.

line(coordinates)

Filter by granules that overlap a series of connected points. Must be used in combination with a collection filtering parameter such as short_name or entry_title.

Parameters:

Name	Type	Description	Default
coordinates	Sequence[PointLike]	a list of (lon, lat) tuples	required

Returns:

Type	Description
Self	self

Raises:

Type	Description
ValueError	coordinates is not a sequence of at least 2 coordinate pairs, or a coordinate could not be converted to a float.

online_only(online_only=True)

Only match granules that are listed online and not available for download. The inverse of this method is downloadable.

Parameters:

Name	Type	Description	Default
online_only	bool	If True, obtain only granules that are online (not downloadable)	True

Returns:

Type	Description
Self	self

Raises:

Type	Description
TypeError	online_only is not of type bool.

orbit_number(orbit1, orbit2=None)

Filter by the orbit number the granule was acquired during. Either a single orbit can be targeted or a range of orbits.

Parameter

Returns:

Type	Description
Self	self

parameters(**kwargs)

Provide query parameters as keyword arguments. The keyword needs to match the name of the method, and the value should either be the value or a tuple of values.

Example

query = DataCollections.parameters(
    short_name="AST_L1T",
    temporal=("2015-01","2015-02"),
    point=(42.5, -101.25)
)

Returns:

Type	Description
Self	self

Raises:

Type	Description
ValueError	The name of a keyword argument is not the name of a method.
TypeError	The value of a keyword argument is not an argument or tuple of arguments matching the number and type(s) of the method's parameters.

platform(platform)

Filter by the satellite platform the granule came from.

Parameters:

Name	Type	Description	Default
platform	str	name of the satellite	required

Returns:

Type	Description
Self	self

Raises:

Type	Description
ValueError	platform is not a non-empty string.

point(lon, lat)

Filter by granules that include a geographic point.

Parameters:

Name	Type	Description	Default
lon	FloatLike	longitude of geographic point	required
lat	FloatLike	latitude of geographic point	required

Returns:

Type	Description
Self	self

Raises:

Type	Description
ValueError	lon or lat cannot be converted to a float.

polygon(coordinates)

Filter by granules that overlap a polygonal area. Must be used in combination with a collection filtering parameter such as short_name or entry_title.

Parameters:

Name	Type	Description	Default
coordinates	Sequence[PointLike]	list of (lon, lat) tuples	required

Returns:

Type	Description
Self	self

Raises:

Type	Description
ValueError	coordinates is not a sequence of at least 4 coordinate pairs, any of the coordinates cannot be converted to a float, or the first and last coordinate pairs are not equal.

provider(provider)

Only match collections from a given provider.

A NASA datacenter or DAAC can have one or more providers. For example, PODAAC is a data center or DAAC, PODAAC is the default provider for on-prem data, and POCLOUD is the PODAAC provider for their data in the cloud.

Parameters:

Name	Type	Description	Default
provider	str	a provider code for any DAAC, e.g. POCLOUD, NSIDC_CPRD, etc.	required

Returns:

Type	Description
Self	self

short_name(short_name)

Filter by short name (aka product or collection name).

Parameters:

Name	Type	Description	Default
short_name	str	name of a collection	required

Returns:

Type	Description
Self	self

temporal(date_from=None, date_to=None, exclude_boundary=False)

Filter by an open or closed date range. Dates can be provided as date objects or ISO 8601 strings. Multiple ranges can be provided by successive method calls.

Tip

Giving either datetime.date(YYYY, MM, DD) or "YYYY-MM-DD" as the date_to parameter includes that entire day (i.e. the time is set to 23:59:59). Using datetime.datetime(YYYY, MM, DD) is different, because datetime.datetime objects have 00:00:00 as their built-in default.

Parameters:

Name	Type	Description	Default
date_from	Optional[Union[str, date, datetime]]	start of temporal range	None
date_to	Optional[Union[str, date, datetime]]	end of temporal range	None
exclude_boundary	bool	whether to exclude the date_from and date_to in the matched range	False

Returns:

Type	Description
Self	self

Raises:

Type	Description
ValueError	date_from or date_to is a non-None value that is neither a datetime object nor a string that can be parsed as a datetime object; or date_from and date_to are both datetime objects (or parsable as such) and date_from is after date_to.

version(version)

Filter by version. Note that CMR defines this as a string. For example, MODIS version 6 products must be searched for with "006".

Parameters:

Name	Type	Description	Default
version	str	version string	required

Returns:

Type	Description
Self	self