planetsca.search

This module contains functions to search for image products via the Planet API.

search.combine_filters(filters: List[dict], combine_with: Literal['and', 'or'] = 'and') → dict

Combine two or more filters with either an AND, or an OR operator

Parameters:

• filters (List[dict]) – list of filters to combine with AND

• combine_with (Literal['and', 'or']) – specify whether to combine filters with an AND, or an OR operator (defaults to AND)

Returns:

filter – combined filters for the Planet API

Return type:

dict

search.get_filter(filter: dict, filter_type: Literal['GeometryFilter', 'DateRangeFilter', 'RangeFilter', 'AndFilter', 'OrFilter'])

Return an individual filter from a dictionary containing multiple Planet API search filters created with search_filters.combine_filters()

Parameters:

• filter (dict) – Filter dict

• filter_type (Literal["GeometryFilter", "DateRangeFilter", "RangeFilter", "AndFilter", "OrFilter"]) – Specify which sub-filter we want to return

Returns:

sub_filter – sub-filter within the larger filter dict

Return type:

dict

search.make_cloud_cover_filter(lte: float, gte: float = 0) → dict

Make a cloud cover filter dictionary for the Planet API

Parameters:

• lte (float) – cloud cover less than or equal to

• gte (float) – cloud cover greater than or equal to value, defaults to 0

Returns:

cloud_cover_filter – dictionary cloud cover filter for the Planet API

Return type:

dict

search.make_date_range_filter(start_date: str, end_date: str) → dict

Make a date range filter dictionary for the Planet API

Parameters:

• start_date (str) – start date (UTC) in the format ‘YYYY-mm-ddTHH:MM:SSZ’ (e.g. ‘2023-07-25T00:00:00Z’)

• end_date (str) – end date (UTC) in the format ‘YYYY-mm-ddTHH:MM:SSZ’ (e.g. ‘2023-07-25T00:00:00Z’)

Returns:

date_range_filter – dictionary date range filter for the Planet API

Return type:

dict

search.make_domain_geometry_from_bounds(bounds: List[float])

Make a shapely geometry polygon from from longitude and latitude bounds (a rectangular area)

Parameters:

bounds (list[float]) – longitude and latitude coordinates of the area, in the order [minLon, minLat, maxLon, maxLat]

Returns:

• geo_json_geometry (dict) – a geojson-like dictionary

• domain_geometry (shapely.geometry.polygon.Polygon) – shaply geometry polygon defined by these bounds

search.make_geometry_filter_from_bounds(bounds: List[float]) → dict

Make a geometry filter dictionary for the Planet API from longitude and latitude bounds (a rectangular search area)

Parameters:

bounds (list[float]) – longitude and latitude coordinates of the area, in the order [minLon, minLat, maxLon, maxLat]

Returns:

• geometry_filter (dict) – dictionary geometry filter for the Planet API

• geometry (shapely.geometry.polygon.Polygon) – shaply geometry polygon defined by these bounds

search.make_geometry_filter_from_geojson(geojson_filepath: str) → dict

Make a geometry filter dictionary for the Planet API from a geojson file path

Parameters:

geojson_filepath (str) – Path to the geojson file to be turned into a filter

Returns:

geometry_filter – dictionary geometry filter for the Planet API

Return type:

dict

search.response_to_gdf(response: Response, filter: dict)

Creates geodataframe of image IDs and other information from a Planet API response

Parameters:

• response (requests.Response) – Response object from the Planet API containing information about images that matched search criteria

• filter (dict) – Dictionary containing data filter information

Returns:

gdf – GeoDataFrame containing information about the Planet images returned by the search

Return type:

geopandas.geodataframe.GeoDataFrame

search.search(api_key: str, filter: dict, item_type: str = 'PSScene') → GeoDataFrame

Sends a request to the Planet API to find if data is available

Parameters:

• api_key (str) – Planet API key

• filter (dict) – Dictionary containing data filter information

• item_type (str) – Class of spacecraft and/or processing level of an item, defaults to PSScene. See https://developers.planet.com/docs/apis/data/items-assets/

Returns:

gdf – GeoDataFrame containing information about the Planet images returned by the search

Return type:

geopandas.geodataframe.GeoDataFrame