Planet Data API

Tools for accessing (searching and downloading) datasets from Planet.

Note to use this module you need to have the planet API installed which can be used from pip:

` pip install planet `

Item Types

  • RSGIS_PLANET_ITEM_PSScene = 1

  • RSGIS_PLANET_ITEM_REOrthoTile = 2

  • RSGIS_PLANET_ITEM_REScene = 3

  • RSGIS_PLANET_ITEM_SkySatScene = 4

  • RSGIS_PLANET_ITEM_SkySatCollect = 5

  • RSGIS_PLANET_ITEM_SkySatVideo = 6

Asset Types

  • RSGIS_PLANET_ASSET_basic_analytic_4b = 1

  • RSGIS_PLANET_ASSET_basic_analytic_4b_rpc = 2

  • RSGIS_PLANET_ASSET_basic_analytic_4b_xml = 3

  • RSGIS_PLANET_ASSET_basic_analytic_8b = 4

  • RSGIS_PLANET_ASSET_basic_analytic_8b_xml = 5

  • RSGIS_PLANET_ASSET_basic_udm2 = 6

  • RSGIS_PLANET_ASSET_ortho_analytic_4b = 7

  • RSGIS_PLANET_ASSET_ortho_analytic_4b_sr = 8

  • RSGIS_PLANET_ASSET_ortho_analytic_4b_xml = 9

  • RSGIS_PLANET_ASSET_ortho_analytic_8b = 10

  • RSGIS_PLANET_ASSET_ortho_analytic_8b_sr = 11

  • RSGIS_PLANET_ASSET_ortho_analytic_8b_xml = 12

  • RSGIS_PLANET_ASSET_ortho_udm2 = 13

  • RSGIS_PLANET_ASSET_ortho_visual = 14

Bundle Types

  • RSGIS_PLANET_BUNDLE_analytic_udm2 = 1

  • RSGIS_PLANET_BUNDLE_analytic_3b_udm2 = 2

  • RSGIS_PLANET_BUNDLE_analytic_8b_udm2 = 3

  • RSGIS_PLANET_BUNDLE_visual = 4

  • RSGIS_PLANET_BUNDLE_basic_analytic_udm2 = 5

  • RSGIS_PLANET_BUNDLE_basic_analytic_8b_udm2 = 6

  • RSGIS_PLANET_BUNDLE_analytic_sr_udm2 = 7

  • RSGIS_PLANET_BUNDLE_analytic_8b_sr_udm2 = 8

rsgislib.dataaccess.planet_data_api.get_asset_type_str(asset_type: int) → str

A function to get the string representation of a given asset type. :param asset_type: RSGIS_PLANET_ASSET_* :return: string representation of a given asset type

rsgislib.dataaccess.planet_data_api.get_bundle_type_str(bundle_type: int) → str

A function to get the string representation of a given bundle type. :param bundle_type: RSGIS_PLANET_ASSET_* :return: string representation of a given bundle type

rsgislib.dataaccess.planet_data_api.get_item_type_str(item_type: int) → str

Get the string representation of a given item type (sensor).

Parameters:

item_type – RSGIS_PLANET_ITEM_* value

Returns:

string representation of a given item type

rsgislib.dataaccess.planet_data_api.planet_auth(username: str = None, password: str = None, api_key: str = None)

A function to authenticate with planet.

Parameters:

  • username – Your username for the planet. If RSGIS_PLANET_USER environmental variable is specified then username will read from there is None is passed (Default: None)

  • password – Your password for the Planet. If RSGIS_PLANET_PASS environmental variable is specified then password will read from there is None is passed (Default: None)

  • api_key – Your api key for Planet API. If RSGIS_PLANET_API_KEY then the api key will be read from there. Alternatively, the PL_API_KEY environment variable can be specified. (Default: None)

Returns:

returns a planet.Auth object

rsgislib.dataaccess.planet_data_api.run_cancel_planet_orders(planet_auth, order_ids: List[str] = None) → Dict

A function which the cancels planet orders.

Parameters:

  • planet_auth – A planet.Auth object which can be created uing the rsgislib.dataccess.planet_data_api.planet_auth function.

  • order_ids – optional list of order IDs to be cancelled. If None (Default) then all are cancelled.

Returns:

Dictionary of orders

rsgislib.dataaccess.planet_data_api.run_create_planet_order(planet_auth, order_name: str, items: List[Dict], item_type: int, bundle_type: int, email_notification: bool = True) → Dict

A function which creates an order for a list of items

Parameters:

  • planet_auth – A planet.Auth object which can be created uing the rsgislib.dataccess.planet_data_api.planet_auth function.

  • order_name – A name for the new order.

  • items – A list of dictionaries containing the items to be created.

  • item_type – The type of item to be included in the order (RSGIS_PLANET_ITEM_*)

  • bundle_type – The bundle type for the order (RSGIS_PLANET_BUNDLE_*)

  • email_notification – Boolean specifying whether you will receive an email notification when the order is ready to download. (Default: True)

Returns:

dict of information for the created order (including the order id)

rsgislib.dataaccess.planet_data_api.run_download_and_validate_item(planet_auth, item_type: int, item_id: str, asset_type: int, out_file_path: str, overwrite: bool = False)

A function which can be used to download a single item from a planet

Parameters:

  • planet_auth – A planet.Auth object which can be created uing the rsgislib.dataccess.planet_data_api.planet_auth function.

  • item_type – The type of item to be downloaded (RSGIS_PLANET_ITEM_*)

  • item_id – The unique id for the item to be downloaded.

  • asset_type – The type of asset type to be downloaded (RSGIS_PLANET_ASSET_*)

  • out_file_path – The output file path to download the file to.

  • overwrite – Boolean to overwrite existing files if it exists.

rsgislib.dataaccess.planet_data_api.run_download_planet_order(planet_auth, order_id: str, out_file_path: str, overwrite: bool = False) → List

A function which downloads an order which has been processed and ready to download. If the order is not ready do download then an expection will be thrown.

Parameters:

  • planet_auth – A planet.Auth object which can be created uing the rsgislib.dataccess.planet_data_api.planet_auth function.

  • order_id – The order ID (not name) of the order to be downloaded.

  • out_file_path – the output directory where the order will be downloaded.

  • overwrite – Specify whether downloads should overwrite existing files. (Default = False)

Returns:

list of downloaded file paths.

rsgislib.dataaccess.planet_data_api.run_get_planet_orders(planet_auth) → List[Dict]

A function which gets a list of all the current planet orders.

Parameters:

planet_auth – A planet.Auth object which can be created uing the rsgislib.dataccess.planet_data_api.planet_auth function.

Returns:

List of orders

rsgislib.dataaccess.planet_data_api.run_search_planet_items(planet_auth, item_type: int, bbox: Tuple[float, float, float, float] | List[float], start_date: datetime = None, end_date: datetime = None, cloud_cover: float = None, sun_elevation_min: float = None, sun_elevation_max: float = None, view_angle_min: float = None, view_angle_max: float = None, max_n_rslts: int = 25) → List[Dict]

A function which searches the planet API to find scenes/items

Parameters:

  • planet_auth – A planet.Auth object which can be created uing the rsgislib.dataccess.planet_data_api.planet_auth function.

  • item_type – The type of item to be downloaded (RSGIS_PLANET_ITEM_*)

  • bbox – is a bbox (xMin, xMax, yMin, yMax) in EPSG:4326 defining the region of interest.

  • start_date – a datetime object representing the start date (i.e., earlier date)

  • end_date – a datetime object representing the end date (i.e., later date)

  • cloud_cover – value between 0-100 where scenes with cloud cover less than the threshold will be returned. If None (default) then ignored.

  • sun_elevation_min – the minimum solar elevation (in degrees). If None (default) then ignored.

  • sun_elevation_max – the maximum solar elevation (in degrees). If None (default) then ignored.

  • view_angle_min – the minimum view angle (in degrees). If None (default) then ignored.

  • view_angle_max – the maximum view angle (in degrees). If None (default) then ignored.

  • max_n_rslts – The maximum number of results to return.

Returns:

A list of dictionaries containing all scene items.