SearchResult

SearchResult#

The SearchResult class provides a convenient way to handle and manipulate search results obtained from the EODAG API. It offers various methods to filter, transform, and interact with the search results, making it easier to work with geospatial data in different formats.

Constructor#

SearchResult(products[, number_matched, ...])

An object representing a collection of EOProduct resulting from a search.

Pagination#

SearchResult.next_page([update])

Retrieve and iterate over the next pages of search results, if available.

Crunch#

Use one of the following filter_* methods to filter search results using advanced criteria. These methods simplify crunch plugins usage.

Or manually run crunch() to apply a given eodag.plugins.crunch.base.Crunch plugin.

`SearchResult.filter_date`([start, end])	Filter products by date.
`SearchResult.filter_latest_intersect`(geometry)	Filter latest products (the ones with a the highest start date) that intersect search extent.
`SearchResult.filter_latest_by_name`(name_pattern)	Filter Search results to get only the latest product, based on the name of the product.
`SearchResult.filter_overlap`(geometry[, ...])	Filter products, retaining only those that are overlapping with the search_extent.
`SearchResult.filter_property`([operator])	Filter products, retaining only those whose property match criteria.
`SearchResult.filter_online`()	Filter to only keep online products.
`SearchResult.crunch`(cruncher, **search_params)	Do some crunching with the underlying EO products.

Conversion#

`SearchResult.from_dict`(feature_collection[, dag])	Builds an `SearchResult` object from its representation as geojson
`SearchResult.from_pystac`(item_collection[, dag])	Builds an `SearchResult` object from a pystac ItemCollection
`SearchResult.as_dict`([skip_invalid])	GeoJSON representation of SearchResult
`SearchResult.as_pystac_object`([skip_invalid])	Pystac ItemCollection representation of SearchResult
`SearchResult.as_shapely_geometry_object`([...])	`shapely.GeometryCollection` representation of SearchResult
`SearchResult.as_wkt_object`([skip_invalid])	WKT representation of SearchResult

Interface#

SearchResult.__geo_interface__

Implements the geo-interface protocol.

class eodag.api.search_result.SearchResult(products, number_matched=None, errors=None, search_params=None, next_page_token=None, next_page_token_key=None, raise_errors=False)[source]#

An object representing a collection of EOProduct resulting from a search.

Parameters:

products (list[EOProduct]) – A list of products resulting from a search
number_matched (int | None, default: None) – (optional) the estimated total number of matching results
errors (list[tuple[str, Exception]] | None, default: None) – (optional) stored errors encountered during the search. Tuple of (provider name, exception)
search_params (dict[str, Any] | None, default: None) – (optional) search parameters stored to use in pagination
next_page_token (str | None, default: None) – (optional) next page token value to use in pagination
next_page_token_key (str | None, default: None) – (optional) next page token key to use in pagination
raise_errors (bool | None, default: False) – (optional) whether to raise errors encountered during the search

Variables:

data – List of products
number_matched – Estimated total number of matching results

property __geo_interface__: dict[str, Any]#

Implements the geo-interface protocol.

See https://gist.github.com/sgillies/2217756

as_dict(skip_invalid=True)[source]#

GeoJSON representation of SearchResult

Parameters:: skip_invalid (bool, default: True) – Whether to skip properties whose values are not valid according to the STAC specification.
Return type:: dict[str, Any]
Returns:: The representation of a SearchResult as a Python dict

as_pystac_object(skip_invalid=True)[source]#

Pystac ItemCollection representation of SearchResult

Parameters:: skip_invalid (bool, default: True) – Whether to skip properties whose values are not valid according to the STAC specification.
Return type:: ItemCollection
Returns:: The representation of a SearchResult as a pystac.ItemCollection

as_shapely_geometry_object(skip_invalid=True)[source]#

shapely.GeometryCollection representation of SearchResult

Parameters:: skip_invalid (bool, default: True) – Whether to skip properties whose values are not valid according to the STAC specification.
Return type:: GeometryCollection
Returns:: The representation of a SearchResult as a shapely.GeometryCollection

as_wkt_object(skip_invalid=True)[source]#

WKT representation of SearchResult

Parameters:: skip_invalid (bool, default: True) – Whether to skip properties whose values are not valid according to the STAC specification.
Return type:: str
Returns:: The representation of a SearchResult as a WKT string

crunch(cruncher, **search_params)[source]#

Do some crunching with the underlying EO products.

Parameters:

cruncher (Crunch) – The plugin instance to use to work on the products
search_params (Any) – The criteria that have been used to produce this result

Return type:

SearchResult

Returns:

The result of the application of the crunching method to the EO products

filter_date(start=None, end=None)[source]#

Filter products by date.

Allows to filter out products that are older than a start date (optional) or more recent than an end date (optional).

Applies FilterDate crunch.

Parameters:

start (str | None, default: None) – start sensing time in iso format
end (str | None, default: None) – end sensing time in iso format

Return type:

SearchResult

Returns:

The result of the application of the crunching method to the EO products

filter_latest_by_name(name_pattern)[source]#

Filter Search results to get only the latest product, based on the name of the product.

Applies FilterLatestByName crunch.

Parameters:: name_pattern (str) – 6 digits product name pattern (tile id)
Return type:: SearchResult
Returns:: The result of the application of the crunching method to the EO products

filter_latest_intersect(geometry)[source]#

Filter latest products (the ones with a the highest start date) that intersect search extent.

Applies FilterLatestIntersect crunch.

Parameters:: geometry (dict[str, Any] | BaseGeometry | Any) – geometry used as search extent.
Return type:: SearchResult
Returns:: The result of the application of the crunching method to the EO products

filter_online()[source]#

Filter to only keep online products.

Applies FilterProperty crunch for order:status == succeeded.

Return type:: SearchResult
Returns:: The result of the application of the crunching method to the EO products

filter_overlap(geometry, minimum_overlap=0, contains=False, intersects=False, within=False)[source]#

Filter products, retaining only those that are overlapping with the search_extent.

Applies FilterOverlap crunch.

Parameters:

geometry (Any) – geometry used as search extent
minimum_overlap (int, default: 0) – minimal overlap percentage
contains (bool, default: False) – True if product geometry contains the search area
intersects (bool, default: False) – True if product geometry intersects the search area
within (bool, default: False) – True if product geometry is within the search area

Return type:

SearchResult

Returns:

The result of the application of the crunching method to the EO products

filter_property(operator='eq', **search_property)[source]#

Filter products, retaining only those whose property match criteria.

Applies FilterProperty crunch.

Parameters:

operator (str, default: 'eq') – Operator used for filtering (one of operator functions lt,le,eq,ne,ge,...)
search_property (Any) – property key from product.properties, associated to its filter value

Return type:

SearchResult

classmethod from_dict(feature_collection, dag=None)[source]#

Builds an SearchResult object from its representation as geojson

Parameters:

feature_collection (dict[str, Any]) – A collection representing a search result.
dag (EODataAccessGateway | None, default: None) – (optional) The EODataAccessGateway instance to use for registering the products.

Return type:

SearchResult

Returns:

An eodag representation of a search result

classmethod from_pystac(item_collection, dag=None)[source]#

Builds an SearchResult object from a pystac ItemCollection

Parameters:

item_collection (ItemCollection) – The pystac.ItemCollection containing the metadata of the products.
dag (EODataAccessGateway | None, default: None) – (optional) The EODataAccessGateway instance to use for registering the products.

Return type:

SearchResult

Returns:

An eodag representation of a search result

next_page(update=True)[source]#

Retrieve and iterate over the next pages of search results, if available.

This method uses the current search parameters and next page token to request additional results from the provider. If update is True, the current SearchResult instance is updated with new products and pagination information as pages are fetched.

Parameters:: update (bool, default: True) – If True, update the current SearchResult with new results.
Return type:: Iterator[SearchResult]
Returns:: An iterator yielding SearchResult objects for each subsequent page.

Example:

>>> first_page = SearchResult([])  # result of a search
>>> for new_results in first_page.next_page():
...     continue  # do something with new_results

SearchResult

Contents

SearchResult#

Constructor#

Pagination#

Crunch#

Conversion#

Interface#