eodal.downloader.planet_scope.client module

Class for interacting with PlanetScope’s Data and Order URL for checking available mapper, placing orders and downloading data.

Make sure to have a Planet-account and to have exported your valid API key as environmental variable. You can find your API following this link: https://www.planet.com/account/#/user-settings

Under Linux you can set your API key by running:

export PLANET_API_KEY = "<your-planet-api-key>"

Copyright (C) 2022 Samuel Wildhaber with some modifications by Lukas Valentin Graf

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class eodal.downloader.planet_scope.client.PlanetAPIClient(request: Dict[str, Any] | None = {}, features: List[Dict[str, Any]] | None = [{}], session: Session | None = None)[source]

Bases: object

eodal Planet-API client.

Attrib request:

query parameters to pass to Planet-API (e.g., date and dataset filters)

Attrib features:

features returned from Planet API (i.e., found Planet-Scope mapper)

Attrib session:

(authenticated) session object to interact with the Planet-API without re-sensing the API key for every single request

__init__(request: Dict[str, Any] | None = {}, features: List[Dict[str, Any]] | None = [{}], session: Session | None = None)[source]

Class constructor method

Parameters:

  • request – query parameters to pass to Planet-API (e.g., date and dataset filters)

  • features – features returned from Planet API (i.e., found Planet-Scope mapper)

  • session – (authenticated) session object to interact with the Planet-API without re-sensing the API key for every single request

authenticate(url: str) → None[source]

Authentication for using the Planet (orders) API

Parameters:

url – API end-point for testing authentication

check_order_status(order_url: str, loop: bool | None = False, sleep_time: int | None = 10, max_iter: int | None = 1000)[source]

Checks the order status of a placed order (authenticated session required).

Parameters:

  • order_url – URL of the placed order

  • loop – if False makes a single query about the order status (default). If True re-runs the query every xx seconds (10 by default) until a maximum of yy iterations (1000 by default) is reached or the order status is one of ‘success’, ‘failed’ or ‘partial’

  • sleep_time – time to sleep between repeated requests in seconds. Ignored if loop is False (default behavior)

  • max_iter – maximum number of iterations in case of repeated requests. Ignored if loop is set to False.

static date_to_planet_dt(date_to_convert: date) → str[source]

Converts datetime.date to format required by Planet API

Parameters:

date_to_convert – date to convert

Returns:

string in time format required by Planet

download_order(download_dir: Path, order_name: str | None = '', order_url: str | None = '') → None[source]

Download data from an order. Order must be activated!

Parameters:

  • download_dir – directory where to download the Planet mapper to. Each scene is stored in a own sub-directory named by its ID to make the archive structure comparable to Sentinel-2 and the single assets (files) are placed within that sub-directory.

  • order_name – name of the order to search for. Ignored if an order_url is provided

  • order_url – URL of an order. If provided, order_name is ignored.

property features: List[Dict[str, Any]]
get_orders() → DataFrame[source]

Returns all available orders in a convenient pandas.DataFrame

Returns:

DataFrame with all orders available

place_order(order_name: str, product_bundle: str | None = 'analytic_8b_sr_udm2', processing_tools: List[Dict[str, Any]] | None = None) → str[source]

Places (activates) an order. Only activated orders can be downloaded once they are available.

Important

To place an order you must have already queried the quick-search API to retrieve available item_ids!

Parameters:
Returns:

URL of the placed order

classmethod query_planet_api(start_date: date, end_date: date, bounding_box: Path | GeoDataFrame, instrument: str | None = 'PSB.SD', item_type: str | None = 'PSScene', cloud_cover_threshold: int | None = 100)[source]

Queries the Planet API to retrieve available datasets (no download, no order placement).

Parameters:

  • start_date – start date of the queried time period (inclusive)

  • end_date – end date of the queried time period (inclusive)

  • bounding_box – file with vector feature(s) or GeoDataFrame with 1:N features. The bounding box encompassing all features is taken.

  • instument – instrument (satelitte platform) from which to download data. PSB.SD (Planet Super Dove) by default.

  • item_type – Planet product item type. PSScene by default.

  • cloud_cover_threshold – cloudy pixel percentage threshold (0-100%) for filtering too cloudy mapper

Returns:

`PlanetAPIClient object’

static quicksearch(session: Session, request_data: Dict[str, Any]) → Response[source]

Queries the Planet Data API based on user-defined request.

This returns available datasets but does not place a order!

Parameters:

  • session – authenticated session object

  • request_data – search request in format required by Planet Data and Orders API

Returns:

Response object whose json attribute contains the features found

property request: Dict[str, Any]
property session: Session