Python SDK API Reference

`Auth` ¶

Handle authentication information for use with Planet APIs.

`from_env(variable_name=None)` `staticmethod` ¶

Create authentication from environment variable.

Reads the PL_API_KEY environment variable

Parameters:

Name	Type	Description	Default
`variable_name`	`Optional[str]`	Alternate environment variable.	`None`

`from_file(filename=None)` `staticmethod` ¶

Create authentication from secret file.

The secret file is named .planet.json and is stored in the user directory. The file has a special format and should have been created with Auth.write().

Parameters:

Name	Type	Description	Default
`filename`	`Optional[Union[str, pathlib.Path]]`	Alternate path for the planet secret file.	`None`

`from_key(key)` `staticmethod` ¶

Obtain authentication from api key.

Parameters:

Name	Type	Description	Default
`key`	`str`	Planet API key	required

`from_login(email, password, base_url=None)` `staticmethod` ¶

Create authentication from login email and password.

Note: To keep your password secure, the use of getpass is recommended.

Parameters:

Name	Type	Description	Default
`email`	`str`	Planet account email address.	required
`password`	`str`	Planet account password.	required
`base_url`	`Optional[str]`	The base URL to use. Defaults to production authentication API base url.	`None`

`store(self, filename=None)` ¶

Store authentication information in secret file.

Parameters:

Name	Type	Description	Default
`filename`	`Optional[Union[str, pathlib.Path]]`	Alternate path for the planet secret file.	`None`

`Session (BaseSession)` ¶

Context manager for asynchronous communication with the Planet service.

The default behavior is to read authentication information stored in the secret file. This behavior can be overridden by providing an auth.Auth instance as an argument.

Examples:

>>> import asyncio
>>> from planet import Session
>>>
>>> async def main():
...     async with Session() as sess:
...         # communicate with services here
...         pass
...
>>> asyncio.run(main())

Examples:

>>> import async
>>> from planet import Auth, Session
>>>
>>> async def main():
...     auth = Auth.from_key('examplekey')
...     async with Session(auth=auth) as sess:
...         # communicate with services here
...         pass
...
>>> asyncio.run(main())

`init(self, auth=None)` `special` ¶

Initialize a Session.

Parameters:

Name	Type	Description	Default
`auth`	`Optional[AuthType]`	Planet server authentication.	`None`

`client(self, name, base_url=None)` ¶

Get a client by its module name.

Parameters:

Name	Type	Description	Default
`name`	`Literal['data', 'orders', 'subscriptions']`	one of 'data', 'orders', or 'subscriptions'.	required

Returns:

Type	Description
`object`	A client instance.

`request(self, method, url, json=None, params=None)` `async` ¶

Build a request and submit it with retry and limiting.

Parameters:

Name	Type	Description	Default
`method`	`str`	HTTP request method.	required
`url`	`str`	Location of the API endpoint.	required
`json`	`Optional[dict]`	JSON to send.	`None`
`params`	`Optional[dict]`	Values to send in the query string.	`None`

Returns:

Type	Description
`models.Response`	Server response.

Exceptions:

Type	Description
`planet.exceptions.APIException`	On API error.
`planet.exceptions.ClientError`	When retry limit is exceeded.

`stream(self, method, url)` ¶

Submit a request and get the response as a stream context manager.

Parameters:

Name	Type	Description	Default
`method`	`str`	HTTP request method.	required
`url`	`str`	Location of the API endpoint.	required

Returns:

Type	Description
`AsyncGenerator[models.StreamingResponse, None]`	Context manager providing the streaming response.

`OrdersClient` ¶

High-level asynchronous access to Planet's orders API.

Examples:

>>> import asyncio
>>> from planet import Session
>>>
>>> async def main():
...     async with Session() as sess:
...         cl = sess.client('orders')
...         # use client here
...
>>> asyncio.run(main())

`init(self, session, base_url=None)` `special` ¶

Parameters:

Name	Type	Description	Default
`session`	`Session`	Open session connected to server.	required
`base_url`	`Optional[str]`	The base URL to use. Defaults to production orders API base url.	`None`

`aggregated_order_stats(self)` `async` ¶

Get aggregated counts of active orders.

Returns:

Type	Description
`dict`	Aggregated order counts

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.

`cancel_order(self, order_id)` `async` ¶

Cancel a queued order.

Parameters:

Name	Type	Description	Default
`order_id`	`str`	The ID of the order	required

Returns:

Type	Description
`dict`	Results of the cancel request

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If order_id is not a valid UUID.
`planet.exceptions.APIError`	On API error.

`cancel_orders(self, order_ids=None)` `async` ¶

Cancel queued orders in bulk.

Parameters:

Name	Type	Description	Default
`order_ids`	`Optional[List[str]]`	The IDs of the orders. If empty or None, all orders in a pre-running state will be cancelled.	`None`

Returns:

Type	Description
`dict`	Results of the bulk cancel request

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If an entry in order_ids is not a valid UUID.
`planet.exceptions.APIError`	On API error.

`create_order(self, request)` `async` ¶

Create an order request.

Examples:

>>> import asyncio
>>> from planet import Session
>>> from planet.order_request import build_request, product
>>>
>>> async def main():
...     image_ids = ["20200925_161029_69_2223"]
...     request = build_request(
...         'test_order',
...         [product(image_ids, 'analytic_udm2', 'psscene')]
...     )
...     async with Session() as sess:
...         cl = sess.client('orders')
...         order = await cl.create_order(request)
...
>>> asyncio.run(main())

Parameters:

Name	Type	Description	Default
`request`	`dict`	order request definition	required

Returns:

Type	Description
`dict`	JSON description of the created order

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.

`download_asset(self, location, filename=None, directory=PosixPath('.'), overwrite=False, progress_bar=True)` `async` ¶

Download ordered asset.

Parameters:

Name	Type	Description	Default
`location`	`str`	Download location url including download token.	required
`filename`	`Optional[str]`	Custom name to assign to downloaded file.	`None`
`directory`	`Path`	Base directory for file download. This directory will be created if it does not already exist.	`PosixPath('.')`
`overwrite`	`bool`	Overwrite any existing files.	`False`
`progress_bar`	`bool`	Show progress bar during download.	`True`

Returns:

Type	Description
`Path`	Path to downloaded file.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.

`download_order(self, order_id, directory=PosixPath('.'), overwrite=False, progress_bar=False)` `async` ¶

Download all assets in an order.

Parameters:

Name	Type	Description	Default
`order_id`	`str`	The ID of the order.	required
`directory`	`Path`	Base directory for file download. This directory must already exist.	`PosixPath('.')`
`overwrite`	`bool`	Overwrite files if they already exist.	`False`
`progress_bar`	`bool`	Show progress bar during download.	`False`

Returns:

Type	Description
`List[pathlib.Path]`	Paths to downloaded files.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.
`planet.exceptions.ClientError`	If the order is not in a final state.

`get_order(self, order_id)` `async` ¶

Get order details by Order ID.

Parameters:

Name	Type	Description	Default
`order_id`	`str`	The ID of the order	required

Returns:

Type	Description
`dict`	JSON description of the order

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If order_id is not a valid UUID.
`planet.exceptions.APIError`	On API error.

`list_orders(self, state=None, limit=100)` ¶

Iterate over the list of stored orders.

Order descriptions are sorted by creation date with the last created order returned first.

Note

The name of this method is based on the API's method name. This method provides iteration over results, it does not get a single result description or return a list of descriptions.

Parameters:

Name	Type	Description	Default
`state`	`Optional[str]`	Filter orders to given state.	`None`
`limit`	`int`	Maximum number of results to return. When set to 0, no maximum is applied.	`100`

Yields:

Type	Description
`AsyncIterator[dict]`	Description of an order.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.
`planet.exceptions.ClientError`	If state is not valid.

`validate_checksum(directory, checksum)` `staticmethod` ¶

Validate checksums of downloaded files against order manifest.

For each file entry in the order manifest, the specified checksum given in the manifest file will be validated against the checksum calculated from the downloaded file.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	Path to order directory.	required
`checksum`	`str`	The type of checksum hash- 'MD5' or 'SHA256'.	required

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If a file is missing or if checksums do not match.

`wait(self, order_id, state=None, delay=5, max_attempts=200, callback=None)` `async` ¶

Wait until order reaches desired state.

Returns the state of the order on the last poll.

This function polls the Orders API to determine the order state, with the specified delay between each polling attempt, until the order reaches a final state, or earlier state, if specified. If the maximum number of attempts is reached before polling is complete, an exception is raised. Setting 'max_attempts' to zero will result in no limit on the number of attempts.

Setting 'delay' to zero results in no delay between polling attempts. This will likely result in throttling by the Orders API, which has a rate limit of 10 requests per second. If many orders are being polled asynchronously, consider increasing the delay to avoid throttling.

By default, polling completes when the order reaches a final state. If 'state' is given, polling will complete when the specified earlier state is reached or passed.

Examples:

from planet.reporting import StateBar

with StateBar() as bar:
    await wait(order_id, callback=bar.update_state)

Parameters:

Name	Type	Description	Default
`order_id`	`str`	The ID of the order.	required
`state`	`Optional[str]`	State prior to a final state that will end polling.	`None`
`delay`	`int`	Time (in seconds) between polls.	`5`
`max_attempts`	`int`	Maximum number of polls. Set to zero for no limit.	`200`
`callback`	`Optional[Callable[[str], NoneType]]`	Function that handles state progress updates.	`None`

Returns State of the order.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.
`planet.exceptions.ClientError`	If order_id or state is not valid or if the maximum number of attempts is reached before the specified state or a final state is reached.

`order_request` ¶

Functionality for preparing order details for use in creating an order

`amazon_s3(aws_access_key_id, aws_secret_access_key, bucket, aws_region, path_prefix=None)` ¶

Amazon S3 Cloud configuration.

Parameters:

Name	Type	Description	Default
`aws_access_key_id`	`str`	S3 account access key.	required
`aws_secret_access_key`	`str`	S3 account secret key.	required
`bucket`	`str`	The name of the bucket that will receive the order output.	required
`aws_region`	`str`	The region where the bucket lives in AWS.	required
`path_prefix`	`Optional[str]`	Custom string to prepend to the files delivered to the bucket. A slash (/) character will be treated as a "folder". Any other characters will be added as a prefix to the files.	`None`

`azure_blob_storage(account, container, sas_token, storage_endpoint_suffix=None, path_prefix=None)` ¶

Azure Blob Storage configuration.

Parameters:

Name	Type	Description	Default
`account`	`str`	Azure account.	required
`container`	`str`	ABS container name.	required
`sas_token`	`str`	Shared-Access Signature token. Token should be specified without a leading '?'.	required
`storage_endpoint_suffix`	`Optional[str]`	Deliver order to a sovereign cloud.	`None`
`path_prefix`	`Optional[str]`	Custom string to prepend to the files delivered to the bucket. A slash (/) character will be treated as a "folder". Any other characters will be added as a prefix to the files.	`None`

`band_math_tool(b1, b2=None, b3=None, b4=None, b5=None, b6=None, b7=None, b8=None, b9=None, b10=None, b11=None, b12=None, b13=None, b14=None, b15=None, pixel_type='Auto')` ¶

Specify an Orders API band math tool.

The parameters of the bandmath tool define how each output band in the derivative product should be produced, referencing the product inputs’ original bands. Band math expressions may not reference neighboring pixels, as non-local operations are not supported. The tool can calculate up to 15 bands for an item. Input band parameters may not be skipped. For example, if the b4 parameter is provided, then b1, b2, and b3 parameters are also required.

For each band expression, the bandmath tool supports normal arithmetic operations and simple math operators offered in the Python numpy package. (For a list of supported mathematical functions, see Bandmath supported numpy math routines).

One bandmath imagery output file is produced for each product bundle, with output bands derived from the band math expressions. nodata pixels are processed with the band math equation. These files have “_bandmath” appended to their file names.

The tool passes through UDM, RPC, and XML files, and does not update values in these files.

Parameters:

Name	Type	Description	Default
`b1-b15`		An expression defining how the output band should be computed.	required
`pixel_type`	`str`	A value indicating what the output pixel type should be.	`'Auto'`

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If pixel_type is not valid.

`build_request(name, products, subscription_id=0, delivery=None, notifications=None, order_type=None, tools=None, stac=None)` ¶

Prepare an order request.

>>> from planet.order_request import (
...     build_request, product, toar_tool, reproject_tool, tile_tool)
...
>>> products = [
...     product(['20170614_113217_3163208_RapidEye-5'],
...             'analytic', 'REOrthoTile')])
... ]
...
>>> tools = [
...     toar_tool(scale_factor=10000),
...     reproject_tool(projection='WSG84', kernel='cubic'),
...     tile_tool(1232, origin_x=-180, origin_y=-90,
...               pixel_size=0.000027056277056,
...               name_template='C1232_30_30_{tilex:04d}_{tiley:04d}')
... ]
...
>>> order_request = build_request(
...     'test_order', products, tools)
...

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the order.	required
`products`	`List[dict]`	Product(s) from the Data API to order.	required
`subscription_id`	`int`	Apply this orders against this quota subscription.	`0`
`delivery`	`Optional[dict]`	Specify custom delivery handling.	`None`
`notifications`	`Optional[dict]`	Specify custom notifications handling.	`None`
`order_type`	`Optional[str]`	Accept a partial order, indicated by 'partial'.	`None`
`tools`	`Optional[List[dict]]`	Tools to apply to the products. Order defines the toolchain order of operatations.	`None`

Exceptions:

Type	Description
`planet.specs.SpecificationException`	If order_type is not a valid order type.

`clip_tool(aoi)` ¶

Create the API spec representation of a clip tool.

Examples:

aoi = {
    "type": "Polygon",
    "coordinates": [[
        [37.791595458984375, 14.84923123791421],
        [37.90214538574219, 14.84923123791421],
        [37.90214538574219, 14.945448293647944],
        [37.791595458984375, 14.945448293647944],
        [37.791595458984375, 14.84923123791421]
    ]]
  }
tool = clip_tool(aoi)

Parameters:

Name	Type	Description	Default
`aoi`	`dict`	clip GeoJSON, either Polygon or Multipolygon.	required

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If GeoJSON is not a valid polygon or multipolygon.

`composite_tool()` ¶

Create the API spec representation of a composite tool.

`coregister_tool(anchor_item)` ¶

Create the API spec representation of a coregister tool.

Parameters:

Name	Type	Description	Default
`anchor_item`	`str`	The item_id of the item to which all other items should be coregistered.	required

`delivery(archive_type=None, single_archive=False, archive_filename=None, cloud_config=None)` ¶

Order delivery configuration.

Examples:

amazon_s3_config = amazon_s3(
    'access_key',
    'secret_access_key',
    'bucket_name',
    'us-east-2',
    'folder1/prefix/'
)
delivery_config = delivery(
    archive_type='zip',
    single_archive=True,
    archive_filename='{{order_id}}.zip'
    cloud_config=amazon_s3_config
)

Parameters:

Name	Type	Description	Default
`archive_type`	`Optional[str]`	Archive order files. Only supports 'zip'.	`None`
`single_archive`	`Optional[bool]`	Archive all bundles together in a single file.	`False`
`archive_filename`	`Optional[str]`	Custom naming convention to use to name the archive file that is received. Uses the template variables {{name}} and {{order_id}}. e.g. "{{name}}_{{order_id}}.zip".	`None`
`cloud_config`	`Optional[Mapping]`	Cloud delivery configuration.	`None`

Exceptions:

Type	Description
`planet.specs.SpecificationException`	If archive_type is not valid.

`file_format_tool(file_format)` ¶

Create the API spec representation of a file format tool.

Parameters:

Name	Type	Description	Default
`file_format`	`str`	The format of the tool output. Either 'COG' or 'PL_NITF'.	required

Exceptions:

Type	Description
`planet.specs.SpecificationException`	If file_format is not one of 'COG' or 'PL_NITF'

`google_cloud_storage(bucket, credentials, path_prefix=None)` ¶

Google Cloud Storage configuration.

Parameters:

Name	Type	Description	Default
`bucket`	`str`	GCS bucket name.	required
`credentials`	`str`	JSON-string of service account for bucket.	required
`path_prefix`	`Optional[str]`	Custom string to prepend to the files delivered to the bucket. A slash (/) character will be treated as a "folder". Any other characters will be added as a prefix to the files.	`None`

`google_earth_engine(project, collection)` ¶

Google Earth Engine configuration.

Parameters:

Name	Type	Description	Default
`project`	`str`	GEE project name.	required
`collection`	`str`	GEE Image Collection name.	required

`harmonize_tool(target_sensor)` ¶

Create the API spec representation of a harmonize tool.

Parameters:

Name	Type	Description	Default
`target_sensor`	`str`	A value indicating to what sensor the input asset types should be calibrated.	required

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If target_sensor is not valid.

`notifications(email=None, webhook_url=None, webhook_per_order=None)` ¶

Notifications description for an order detail.

Parameters:

Name	Type	Description	Default
`email`	`Optional[bool]`	Enable email notifications for an order.	`None`
`webhook_url`	`Optional[str]`	URL for notification when the order is ready.	`None`
`webhook_per_order`	`Optional[bool]`	Request a single webhook call per order instead of one call per each delivered item.	`None`

`product(item_ids, product_bundle, item_type, fallback_bundle=None)` ¶

Product description for an order detail.

Parameters:

Name	Type	Description	Default
`item_ids`	`List[str]`	IDs of the catalog items to include in the order.	required
`product_bundle`	`str`	Set of asset types for the catalog items.	required
`item_type`	`str`	The class of spacecraft and processing characteristics for the catalog items.	required
`fallback_bundle`	`Optional[str]`	In case product_bundle not having all asset types available, which would result in failed delivery, try a fallback bundle	`None`

Exceptions:

Type	Description
`planet.specs.SpecificationException`	If bundle or fallback bundle are not valid bundles or if item_type is not valid for the given bundle or fallback bundle.

`reproject_tool(projection, resolution=None, kernel=None)` ¶

Create the API spec representation of a reproject tool.

Parameters:

Name	Type	Description	Default
`projection`	`str`	A coordinate system in the form EPSG:n. (ex. EPSG:4326 for WGS84, EPSG:32611 for UTM 11 North (WGS84), or EPSG:3857 for Web Mercator).	required
`resolution`	`Optional[float]`	The pixel width and height in the output file. The API default is the resolution of the input item. This value will be in meters unless the coordinate system is geographic (like EPSG:4326), then it will be a pixel size in decimal degrees.	`None`
`kernel`	`Optional[str]`	The resampling kernel used. The API default is "near". This parameter also supports "bilinear", "cubic", "cubicspline", "lanczos", "average" and "mode".	`None`

`tile_tool(tile_size, origin_x=None, origin_y=None, pixel_size=None, name_template=None, conformal_x_scaling=None)` ¶

Create the API spec representation of a reproject tool.

Parameters:

Name	Type	Description	Default
`tile_size`	`int`	Height and width of output tiles in pixels and lines (always square).	required
`origin_x`	`Optional[float]`	Tiling system x origin in projected coordinates. The API default is zero.	`None`
`origin_y`	`Optional[float]`	Tiling system y origin in projected coordinates. The API default is zero.	`None`
`pixel_size`	`Optional[float]`	Tiling system pixel size in projected coordinates. The API default is the pixel_size of input raster.	`None`
`name_template`	`Optional[str]`	A naming template for creating output tile filenames. The API default is "{tilex}_{tiley}.tif" resulting in filenames like 128_200.tif. The {tilex} and {tiley} parameters can be of the form {tilex:06d} to produce a fixed width field with leading zeros.	`None`

`toar_tool(scale_factor=None)` ¶

Create the API spec representation of a TOAR tool.

Parameters:

Name	Type	Description	Default
`scale_factor`	`Optional[int]`	Scale factor applied to convert 0.0 to 1.0 reflectance floating point values to a value that fits in 16bit integer pixels. The API default is 10000. Values over 65535 could result in high reflectances not fitting in 16bit integers.	`None`

`DataClient` ¶

High-level asynchronous access to Planet's data API.

Examples:

>>> import asyncio
>>> from planet import Session
>>>
>>> async def main():
...     async with Session() as sess:
...         cl = sess.client('data')
...         # use client here
...
>>> asyncio.run(main())

`init(self, session, base_url=None)` `special` ¶

Parameters:

Name	Type	Description	Default
`session`	`Session`	Open session connected to server.	required
`base_url`	`Optional[str]`	The base URL to use. Defaults to production data API base url.	`None`

`activate_asset(self, asset)` `async` ¶

Activate an item asset.

Parameters:

Name	Type	Description	Default
`asset`	`dict`	Description of the asset. Obtained from get_asset().	required

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.
`planet.exceptions.ClientError`	If asset description is not

`create_search(self, item_types, search_filter, name, enable_email=False)` `async` ¶

Create a new saved structured item search.

To filter to items you have access to download which are of standard (aka not test) quality, use the following:

>>> from planet import data_filter
>>> data_filter.and_filter([
...     data_filter.permission_filter(),
...     data_filter.std_quality_filter()
>>> ])

To avoid filtering out any imagery, supply a blank AndFilter, which can be created with data_filter.and_filter([]).

Parameters:

Name	Type	Description	Default
`item_types`	`List[str]`	The item types to include in the search.	required
`search_filter`	`dict`	Structured search criteria.	required
`name`	`str`	The name of the saved search.	required
`enable_email`	`bool`	Send a daily email when new results are added.	`False`

Returns:

Type	Description
`dict`	Description of the saved search.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.

`delete_search(self, search_id)` `async` ¶

Delete an existing saved search.

Parameters:

Name	Type	Description	Default
`search_id`	`str`	Saved search identifier.	required

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.

`download_asset(self, asset, filename=None, directory=PosixPath('.'), overwrite=False, progress_bar=True)` `async` ¶

Download an asset.

The asset must be active before it can be downloaded. This can be achieved with activate_asset() followed by wait_asset().

If overwrite is False and the file already exists, download will be skipped and the file path will be returned as usual.

Parameters:

Name	Type	Description	Default
`asset`	`dict`	Description of the asset. Obtained from get_asset() or wait_asset().	required
`filename`	`Optional[str]`	Custom name to assign to downloaded file.	`None`
`directory`	`Path`	Base directory for file download.	`PosixPath('.')`
`overwrite`	`bool`	Overwrite any existing files.	`False`
`progress_bar`	`bool`	Show progress bar during download.	`True`

Returns:

Type	Description
`Path`	Path to downloaded file.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.
`planet.exceptions.ClientError`	If asset is not active or asset

`get_asset(self, item_type_id, item_id, asset_type_id)` `async` ¶

Get an item asset description.

Parameters:

Name	Type	Description	Default
`item_type_id`	`str`	Item type identifier.	required
`item_id`	`str`	Item identifier.	required
`asset_type_id`	`str`	Asset type identifier.	required

Returns:

Type	Description
`dict`	Description of the asset.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.
`planet.exceptions.ClientError`	If asset type identifier is not

`get_search(self, search_id)` `async` ¶

Get a saved search by id.

Parameters:

Name	Type	Description	Default
`search_id`	`str`	Stored search identifier.	required

Returns:

Type	Description
`dict`	Saved search details.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.

`get_stats(self, item_types, search_filter, interval)` `async` ¶

Get item search statistics.

Parameters:

Name	Type	Description	Default
`item_types`	`List[str]`	The item types to include in the search.	required
`search_filter`	`dict`	Structured search criteria.	required
`interval`	`str`	The size of the histogram date buckets.	required

Returns:

Type	Description
`dict`	A full JSON description of the returned statistics result histogram.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.
`planet.exceptions.ClientError`	If interval is not valid.

`list_item_assets(self, item_type_id, item_id)` `async` ¶

List all assets available for an item.

An asset describes a product that can be derived from an item's source data, and can be used for various analytic, visual or other purposes. These are referred to as asset_types.

Parameters:

Name	Type	Description	Default
`item_type_id`	`str`	Item type identifier.	required
`item_id`	`str`	Item identifier.	required

Returns:

Type	Description
`dict`	Descriptions of available assets as a dictionary with asset_type_id as keys and asset description as value.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.

`list_searches(self, sort='created desc', search_type='any', limit=100)` ¶

Iterate through list of searches available to the user.

Note

The name of this method is based on the API's method name. This method provides iteration over results, it does not get a single result description or return a list of descriptions.

Parameters:

Name	Type	Description	Default
`sort`	`str`	Field and direction to order results by.	`'created desc'`
`search_type`	`str`	Filter to specified search type.	`'any'`
`limit`	`int`	Maximum number of results to return. When set to 0, no maximum is applied.	`100`

Yields:

Type	Description
`AsyncIterator[dict]`	Description of a search.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.
`planet.exceptions.ClientError`	If sort or search_type are not valid.

`run_search(self, search_id, sort=None, limit=100)` ¶

Iterate over results from a saved search.

Note

The name of this method is based on the API's method name. This method provides iteration over results, it does not get a single result description or return a list of descriptions.

Parameters:

Name	Type	Description	Default
`search_id`	`str`	Stored search identifier.	required
`sort`	`Optional[str]`	Field and direction to order results by. Valid options are	`None`
`limit`	`int`	Maximum number of results to return. When set to 0, no maximum is applied.	`100`

Yields:

Type	Description
`AsyncIterator[dict]`	Description of an item.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.
`planet.exceptions.ClientError`	If search_id or sort is not valid.

`search(self, item_types, search_filter=None, name=None, sort=None, limit=100)` ¶

Iterate over results from a quick search.

Quick searches are saved for a short period of time (~month). The name parameter of the search defaults to the id of the generated search id if name is not specified.

Note

The name of this method is based on the API's method name. This method provides iteration over results, it does not get a single result description or return a list of descriptions.

Parameters:

Name	Type	Description	Default
`item_types`	`List[str]`	The item types to include in the search.	required
`search_filter`	`Optional[dict]`	Structured search criteria to apply. If None, no search criteria is applied.	`None`
`sort`	`Optional[str]`	Field and direction to order results by. Valid options are	`None`
`name`	`Optional[str]`	The name of the saved search.	`None`
`limit`	`int`	Maximum number of results to return. When set to 0, no maximum is applied.	`100`

Yields:

Type	Description
`AsyncIterator[dict]`	Description of an item.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.

`update_search(self, search_id, item_types, search_filter, name, enable_email=False)` `async` ¶

Update an existing saved search.

Parameters:

Name	Type	Description	Default
`search_id`	`str`	Saved search identifier.	required
`item_types`	`List[str]`	The item types to include in the search.	required
`search_filter`	`dict`	Structured search criteria.	required
`name`	`str`	The name of the saved search.	required
`enable_email`	`bool`	Send a daily email when new results are added.	`False`

Returns:

Type	Description
`dict`	Description of the saved search.

`validate_checksum(asset, filename)` `staticmethod` ¶

Validate checksum of downloaded file

Compares checksum calculated from the file against the value provided in the asset.

Parameters:

Name	Type	Description	Default
`asset`	`dict`	Description of the asset. Obtained from get_asset() or wait_asset().	required
`filename`	`Path`	Full path to downloaded file.	required

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If the file does not exist or if checksums do not match.

`wait_asset(self, asset, delay=5, max_attempts=200, callback=None)` `async` ¶

Wait for an item asset to be active.

Prior to waiting for the asset to be active, be sure to activate the asset with activate_asset().

Parameters:

Name	Type	Description	Default
`asset`	`dict`	Description of the asset. Obtained from get_asset().	required
`delay`	`int`	Time (in seconds) between polls.	`5`
`max_attempts`	`int`	Maximum number of polls. When set to 0, no limit is applied.	`200`
`callback`	`Optional[Callable[[str], NoneType]]`	Function that handles state progress updates.	`None`

Returns:

Type	Description
`Dict[Any, Any]`	Last received description of the asset.

Exceptions:

Type	Description
`planet.exceptions.APIError`	On API error.
`planet.exceptions.ClientError`	If asset_type_id is not valid or is not available or if the maximum number of attempts is reached before the asset is active.

`data_filter` ¶

Functionality for preparing a data search filter

`and_filter(nested_filters)` ¶

Create an AndFilter

The AndFilter can be used to limit results to items with properties or permissions which match all nested filters.

It is most commonly used as a top-level filter to ensure criteria across all field and permission filters are met.

Parameters:

Name	Type	Description	Default
`nested_filters`	`List[dict]`	Filters to AND together	required

`asset_filter(asset_types)` ¶

Create an AssetFilter

The AssetFilter can be used to search for items which have published a specified asset_type. This filter is commonly used to filter items by published asset types which:

May be published at delay after an item's first publish. analytic_sr, for instance, may be published up to 12 hours after an item first becomes available.
May not be available for the full catalog. udm2, for instance, is only available globally through July 2018.

Filters to all items which include any of the listed asset types. An AndFilter can be used to filter items by multiple asset types.

Parameters:

Name	Type	Description	Default
`asset_types`	`List[str]`	List of the names of the asset type to filter on.	required

`date_range_filter(field_name, gt=None, lt=None, gte=None, lte=None)` ¶

Create a DateRangeFilter

The DateRangeFilter can be used to search on any property with a timestamp such as acquired or published.

One or more of the conditional parameters gt, lt, gte, lte must be specified. Conditionals are combined in a logical AND, so only items that match all specified conditionals are returned.

Parameters:

Name	Type	Description	Default
`field_name`	`str`	Name of field to filter on.	required
`gt`	`Optional[datetime.datetime]`	Filter to field timestamp later than this datetime.	`None`
`lt`	`Optional[datetime.datetime]`	Filter to field timestamp earlier than this datetime.	`None`
`gte`	`Optional[datetime.datetime]`	Filter to field timestamp at or later than this datetime.	`None`
`lte`	`Optional[datetime.datetime]`	Filter to field timestamp at or earlier than this datetime.	`None`

Exceptions:

Type	Description
`exceptions.PlanetError`	If no conditional parameter is specified.

`empty_filter()` ¶

Create an Empty filter for bypassing search filtering.

`geometry_filter(geom)` ¶

Create a GeometryFilter

The GeometryFilter can be used to search for items with a footprint geometry which intersects with the specified geometry.

In cases where a GeoJSON Feature or FeatureCollection are provided, the GeoJSON geometry will be extracted and used in the filter definition.

The filter's configuration supports Point, MultiPoint, LineString, MultiLineString, Polygon, and MultiPolygon GeoJSON object. For best results, the geometry should meet OpenGIS Simple Features Interface Specification requirements. If an invalid GeoJSON object is supplied, the API will automatically attempt to correct the geometry and return matching search results.

Parameters:

Name	Type	Description	Default
`geom`	`dict`	GeoJSON describing the filter geometry, feature, or feature collection.	required

`not_filter(nested_filter)` ¶

Create a NotFilter

The NotFilter can be used to match items with properties or permissions which do not match the nested filter.

This filter only supports a single nested filter. Multiple NotFilters can be nested within an AndFilter to filter across multiple fields or permission values.

Parameters:

Name	Type	Description	Default
`nested_filter`	`dict`	Filter to NOT	required

`number_in_filter(field_name, values)` ¶

Create a NumberInFilter

The NumberInFilter can be used to search for items with numerical poperties. It is useful for matching fields such as gsd.

Parameters:

Name	Type	Description	Default
`field_name`	`str`	Name of field to filter on.	required
`values`	`List[float]`	List of numbers to filter on.	required

`or_filter(nested_filters)` ¶

Create an OrFilter

The OrFilter can be used to match items with properties or permissions which match at least one of the nested filters.

Parameters:

Name	Type	Description	Default
`nested_filters`	`List[dict]`	Filters to OR together	required

`permission_filter()` ¶

Create a PermissionFilter

The PermissionFilter limits results to items that a user has permission to download.

`range_filter(field_name, gt=None, lt=None, gte=None, lte=None)` ¶

Create a RangeFilter

The RangeFilter can be used to search for items with numerical properties. It is useful for matching fields that have a continuous range of values such as cloud_cover or view_angle.

One or more of the conditional parameters gt, lt, gte, lte must be specified. Conditionals are combined in a logical AND, so only items that match all specified conditionals are returned.

Parameters:

Name	Type	Description	Default
`field_name`	`str`	Name of field to filter on.	required
`gt`	`Optional[float]`	Filter to field value greater than this number.	`None`
`lt`	`Optional[float]`	Filter to field value less than this number.	`None`
`gte`	`Optional[float]`	Filter to field value greater than or equal to this number.	`None`
`lte`	`Optional[float]`	Filter to field value less than or equal to this number.	`None`

Exceptions:

Type	Description
`exceptions.PlanetError`	If no conditional parameter is specified.

`std_quality_filter()` ¶

Create a filter for standard-quality items.

This is a custom filter which filters to items that are categorized as standard quality.

`string_in_filter(field_name, values)` ¶

Create a StringInFilter

The StringInFilter can be used to search for items with string properties such as instrument or quality_category. Boolean properties such as ground_control are also supported with the StringInFilter.

Filters to items with the given field matching any of the values.

Parameters:

Name	Type	Description	Default
`field_name`	`str`	Name of field to filter on.	required
`values`	`List[str]`	List of strings to filter on.	required

`update_filter(field_name, gt=None, lt=None, gte=None, lte=None)` ¶

Create an UpdateFilter

The UpdateFilter can be used to filter items by changes to a specified metadata field value made after a specified date, due to a republishing event. This feature allows you identify items which may have been republished with improvements or fixes, enabling you to keep your internal catalogs up-to-date and make more informed redownload decisions. The filter works for all items published on or after April 10, 2020.

One or more of the conditional parameters gt or gte must be specified. Conditionals are combined in a logical AND, so only items that match all specified conditionals are returned.

Parameters:

Name	Type	Description	Default
`field_name`	`str`	Name of field to filter on.	required
`gt`	`Optional[float]`	Filter to changes to field metadata after this datetime.	`None`
`gte`	`Optional[float]`	Filter to changes to field metadata at or after this datetime.	`None`

Exceptions:

Type	Description
`exceptions.PlanetError`	If no conditional parameter is specified.

`SubscriptionsClient` ¶

A Planet Subscriptions Service API 1.0.0 client.

The methods of this class forward request parameters to the operations described in the Planet Subscriptions Service API 1.0.0 (https://api.planet.com/subscriptions/v1/spec) using HTTP 1.1.

The methods generally return or yield Python dicts with the same structure as the JSON messages used by the service API. Many of the exceptions raised by this class are categorized by HTTP client (4xx) or server (5xx) errors. This client's level of abstraction is low.

High-level asynchronous access to Planet's subscriptions API:

Examples:

>>> import asyncio
>>> from planet import Session
>>>
>>> async def main():
...     async with Session() as sess:
...         cl = sess.client('subscriptions')
...         # use client here
...
>>> asyncio.run(main())

`init(self, session, base_url=None)` `special` ¶

Parameters:

Name	Type	Description	Default
`session`	`Session`	Open session connected to server.	required
`base_url`	`Optional[str]`	The base URL to use. Defaults to production subscriptions API base url.	`None`

`cancel_subscription(self, subscription_id)` `async` ¶

Cancel a Subscription.

Parameters:

Name	Type	Description	Default
`subscription_id`	`str`	id of subscription to cancel.	required

Returns:

Type	Description
`None`	None

Exceptions:

Type	Description
`APIError`	on an API server error.
`ClientError`	on a client error.

`create_subscription(self, request)` `async` ¶

Create a Subscription.

Parameters:

Name	Type	Description	Default
`request`	`dict`	description of a subscription.	required

Returns:

Type	Description
`dict`	description of created subscription.

Exceptions:

Type	Description
`APIError`	on an API server error.
`ClientError`	on a client error.

`get_results(self, subscription_id, status=None, limit=100)` ¶

Iterate over results of a Subscription.

Notes

The name of this method is based on the API's method name. This method provides iteration over results, it does not get a single result description or return a list of descriptions.

Parameters:

Name	Type	Description	Default
`subscription_id`	`str`	id of a subscription.	required
`status`	`Set[str]`	pass result with status in this set, filter out results with status not in this set.	`None`
`limit`	`int`	limit the number of subscriptions in the results.	`100`
`TODO`		created, updated, completed, user_id	required

Yields:

Type	Description
`dict`	description of a subscription results.

Exceptions:

Type	Description
`APIError`	on an API server error.
`ClientError`	on a client error.

`get_results_csv(self, subscription_id, status=None, limit=100)` ¶

Iterate over rows of results CSV for a Subscription.

Parameters:

Name	Type	Description	Default
`subscription_id`	`str`	id of a subscription.	required
`status`	`Set[str]`	pass result with status in this set, filter out results with status not in this set.	`None`
`TODO`		created, updated, completed, user_id	required

Yields:

Type	Description
`str`	a row from a CSV file.

Exceptions:

Type	Description
`APIError`	on an API server error.
`ClientError`	on a client error.

`get_subscription(self, subscription_id)` `async` ¶

Get a description of a Subscription.

Parameters:

Name	Type	Description	Default
`subscription_id`	`str`	id of a subscription.	required

Returns:

Type	Description
`dict`	description of the subscription.

Exceptions:

Type	Description
`APIError`	on an API server error.
`ClientError`	on a client error.

`list_subscriptions(self, status=None, limit=100)` ¶

Iterate over list of account subscriptions with optional filtering.

Note

The name of this method is based on the API's method name. This method provides iteration over subcriptions, it does not return a list.

Parameters:

Name	Type	Description	Default
`status`	`Set[str]`	pass subscriptions with status in this set, filter out subscriptions with status not in this set.	`None`
`limit`	`int`	limit the number of subscriptions in the results.	`100`
`TODO`		user_id	required

Yields:

Type	Description
`dict`	a description of a subscription.

Exceptions:

Type	Description
`APIError`	on an API server error.
`ClientError`	on a client error.

`patch_subscription(self, subscription_id, request)` `async` ¶

Update (edit) a Subscription via PATCH.

Args subscription_id (str): id of the subscription to update. request (dict): subscription content for update, only attributes to update are required.

Returns:

Type	Description
`dict`	description of the updated subscription.

Exceptions:

Type	Description
`APIError`	on an API server error.
`ClientError`	on a client error.

`update_subscription(self, subscription_id, request)` `async` ¶

Update (edit) a Subscription via PUT.

Args subscription_id (str): id of the subscription to update. request (dict): subscription content for update, full payload is required.

Returns:

Type	Description
`dict`	description of the updated subscription.

Exceptions:

Type	Description
`APIError`	on an API server error.
`ClientError`	on a client error.

`subscription_request` ¶

Functionality for preparing subscription requests.

`FilterValue` `dataclass` ¶

Represents a filter value with optional greater than or equal to (gte) and less than or equal to (lte) constraints.

Attributes:

Name	Type	Description
`gte`	`Optional[float]`	The minimum threshold value for the filter.
`lte`	`Optional[float]`	The maximum threshold value for the filter.

`amazon_s3(aws_access_key_id, aws_secret_access_key, bucket, aws_region, path_prefix=None)` ¶

Delivery to Amazon S3.

Parameters:

Name	Type	Description	Default
`aws_access_key_id`	`str`	S3 account access key.	required
`aws_secret_access_key`	`str`	S3 account secret key.	required
`bucket`	`str`	The name of the bucket that will receive the order output.	required
`aws_region`	`str`	The region where the bucket lives in AWS.	required
`path_prefix`	`Optional[str]`	Path prefix for deliveries.	`None`

`azure_blob_storage(account, container, sas_token, storage_endpoint_suffix=None, path_prefix=None)` ¶

Delivery to Azure Blob Storage.

Parameters:

Name	Type	Description	Default
`account`	`str`	Azure account.	required
`container`	`str`	ABS container name.	required
`sas_token`	`str`	Shared-Access Signature token. Token should be specified without a leading '?'.	required
`storage_endpoint_suffix`	`Optional[str]`	Deliver order to a sovereign cloud. The default is "core.windows.net".	`None`
`path_prefix`	`Optional[str]`	Path prefix for deliveries.	`None`

`band_math_tool(b1, b2=None, b3=None, b4=None, b5=None, b6=None, b7=None, b8=None, b9=None, b10=None, b11=None, b12=None, b13=None, b14=None, b15=None, pixel_type='Auto')` ¶

Specify a subscriptions API band math tool.

The parameters of the bandmath tool define how each output band in the derivative product should be produced, referencing the product inputs’ original bands. Band math expressions may not reference neighboring pixels, as non-local operations are not supported. The tool can calculate up to 15 bands for an item. Input band parameters may not be skipped. For example, if the b4 parameter is provided, then b1, b2, and b3 parameters are also required.

For each band expression, the bandmath tool supports normal arithmetic operations and simple math operators offered in the Python numpy package. (For a list of supported mathematical functions, see Bandmath supported numpy math routines).

One bandmath imagery output file is produced for each product bundle, with output bands derived from the band math expressions. nodata pixels are processed with the band math equation. These files have “_bandmath” appended to their file names.

The tool passes through UDM, RPC, and XML files, and does not update values in these files.

Parameters:

Name	Type	Description	Default
`b1-b15`		An expression defining how the output band should be computed.	required
`pixel_type`	`str`	A value indicating what the output pixel type should be.	`'Auto'`

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If pixel_type is not valid.

`build_request(name, source, delivery=None, notifications=None, tools=None, hosting=None, collection_id=None, clip_to_source=False)` ¶

Construct a Subscriptions API request.

The return value can be passed to planet.clients.subscriptions.SubscriptionsClient.create_subscription.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the subscription.	required
`source`	`Mapping`	A source for the subscription, i.e. catalog.	required
`delivery`	`Optional[Mapping]`	A delivery mechanism e.g. GCS, AWS, Azure, or OCS.	`None`
`notifications`	`Optional[Mapping]`	Specify notifications via email/webhook.	`None`
`tools`	`Optional[List[Mapping]]`	Tools to apply to the products. The order of operation is determined by the service.	`None`
`hosting`	`Union[Mapping, str]`	A hosting destination e.g. Sentinel Hub.	`None`
`clip_to_source`	`Optional[bool]`	whether to clip to the source geometry or not (the default). If True a clip configuration will be added to the list of requested tools unless an existing clip tool exists. NOTE: Not all data layers support clipping, please consult the Product reference before using this option. NOTE: the next version of the Subscription API will remove the clip tool option and always clip to the source geometry. Thus this is a preview of the next API version's default behavior.	`False`

Returns:

Type	Description
`dict`	a representation of a Subscriptions API request for a new subscription.

Exceptions:

Type	Description
`ClientError`	when a valid Subscriptions API request can't be constructed.

Examples:

```python from datetime import datetime from planet.subscription_request import build_request, catalog_source, amazon_s3

geom = {
    "coordinates": [
        [
            [139.5648193359375, 35.42374884923695],
            [140.1031494140625, 35.42374884923695],
            [140.1031494140625, 35.77102915686019],
            [139.5648193359375, 35.77102915686019],
            [139.5648193359375, 35.42374884923695],
        ]
    ],
    "type": "Polygon",
}

source = catalog_source(["PSScene"], ["ortho_analytic_4b"], geom, datetime(2021, 3, 1))

delivery = amazon_s3(ACCESS_KEY_ID, SECRET_ACCESS_KEY, "test", "us-east-1")

hosting = sentinel_hub("2716077c-191e-4e47-9e3f-01c9c429f88d")

subscription_request = build_request(
    "test_subscription", source=source, delivery=delivery, hosting=hosting
)
```

`catalog_source(item_types, asset_types, geometry, start_time, filter=None, end_time=None, rrule=None, publishing_stages=None, time_range_type=None)` ¶

Construct a Catalog subscription source.

The return value can be passed to planet.subscription_request.build_request.

Parameters:

Name	Type	Description	Default
`item_types`	`List[str]`	The class of spacecraft and processing level of the subscription's matching items, e.g. PSScene.	required
`asset_types`	`List[str]`	The data products which will be delivered for all subscription matching items. An item will only match and deliver if all specified asset types are published for that item.	required
`geometry`	`Mapping`	The area of interest of the subscription that will be used to determine matches.	required
`start_time`	`datetime`	The start time of the subscription. This time can be in the past or future.	required
`filter`	`Optional[Mapping]`	The filter criteria based on item-level metadata.	`None`
`end_time`	`Optional[datetime.datetime]`	The end time of the subscription. This time can be in the past or future, and must be after the start_time.	`None`
`rrule`	`Optional[str]`	The recurrence rule, given in iCalendar RFC 5545 format. Only monthly recurrences are supported at this time.	`None`
`publishing_stages`	`Optional[Sequence[Literal['preview', 'standard', 'finalized']]]`	A sequence of one or more of the values "preview", "standard", or "finalized".	`None`
`time_range_type`	`Optional[Literal['acquired', 'published']]`	"acquired" (new in 2.1.0) or "published".	`None`

Returns:

Type	Description
`dict`	a representation of a subscription source.

Exceptions:

Type	Description
`ClientError`	if a source can not be configured.

Examples:

source = catalog_source(
    ["PSScene"],
    ["ortho_analytic_4b"],
    geometry={
        "type": "Polygon",
        "coordinates": [
            [
                [37.791595458984375, 14.84923123791421],
                [37.90214538574219, 14.84923123791421],
                [37.90214538574219, 14.945448293647944],
                [37.791595458984375, 14.945448293647944],
                [37.791595458984375, 14.84923123791421],
            ]
        ],
    },
    start_time=datetime(2021, 3, 1),
    publishing_stages=["standard"],
    time_range_type="acquired",
)

request = build_request("Standard PSScene Ortho Analytic", source=source, delivery={})

`clip_tool(aoi)` ¶

Specify a subscriptions API clip tool.

Imagery and udm files will be clipped to your area of interest. nodata pixels will be preserved. Xml file attributes “filename”, “numRows”, “numColumns” and “footprint” will be updated based on the clip results.

The clipped output files will have “_clip” appended to their file names. If the clip aoi is so large that full scenes may be delivered without any clipping, those files will not have “_clip” appended to their file name.

Parameters:

Name	Type	Description	Default
`aoi`	`Mapping`	GeoJSON polygon or multipolygon defining the clip area, with up to 500 vertices. The minimum geographic area of any polygon or internal ring is one square meter.	required

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If aoi is not a valid polygon or multipolygon.

`cloud_filter_tool(clear_percent=None, cloud_percent=None, shadow_percent=None, heavy_haze_percent=None, light_haze_percent=None, snow_ice_percent=None)` ¶

Specify a subscriptions API cloud_filter tool.

The cloud_filter tool filters imagery after the clip tool has run and certain metadata values have been updated to pertain to the clip AOI. This tool offers a more detailed filtering of cloudy imagery than what can be achieved using only catalog source filters. For instance, you might want to receive only images that, after clipping, have a cloud_percent value of less than or equal to 25%.

Parameters:

Name	Type	Description	Default
`clear_percent`	`Optional[planet.subscription_request.FilterValue]`	Filters for images based on the percentage of clear sky.	`None`
`cloud_percent`	`Optional[planet.subscription_request.FilterValue]`	Filters for images based on the percentage of cloud cover.	`None`
`shadow_percent`	`Optional[planet.subscription_request.FilterValue]`	Filters for images based on the percentage of shadow cover.	`None`
`heavy_haze_percent`	`Optional[planet.subscription_request.FilterValue]`	Filters for images based on the percentage of heavy haze cover.	`None`
`light_haze_percent`	`Optional[planet.subscription_request.FilterValue]`	Filters for images based on the percentage of light haze cover.	`None`
`snow_ice_percent`	`Optional[planet.subscription_request.FilterValue]`	Filters for images based on the percentage of snow or ice cover.	`None`

`file_format_tool(file_format)` ¶

Specify a subscriptions API file format tool.

Parameters:

Name	Type	Description	Default
`file_format`	`str`	The format of the tool output. Either "COG" or "PL_NITF".	required

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If file_format is not valid.

`google_cloud_storage(credentials, bucket, path_prefix=None)` ¶

Delivery to Google Cloud Storage.

Parameters:

Name	Type	Description	Default
`credentials`	`str`	JSON-string of service account for bucket.	required
`bucket`	`str`	GCS bucket name.	required
`path_prefix`	`Optional[str]`	Path prefix for deliveries.	`None`

`harmonize_tool(target_sensor)` ¶

Specify a subscriptions API harmonize tool.

Each sensor value transforms items captured by a defined set of instrument IDs. Items which have not been captured by that defined set of instrument IDs are unaffected by (passed through) the harmonization operation.

Parameters:

Name	Type	Description	Default
`target_sensor`	`str`	A value indicating to what sensor the input asset types should be calibrated.	required

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If target_sensor is not valid.

`notifications(url, topics)` ¶

Specify a subscriptions API notification.

Webhook notifications proactively notify you when a subscription matches and delivers an item so you have confidence that you have all the expected imagery.

Parameters:

Name	Type	Description	Default
`url`	`str`	location of webhook/callback where you expect to receive updates.	required
`topics`	`List[str]`	Event types that you can choose to be notified about.	required

`oracle_cloud_storage(customer_access_key_id, customer_secret_key, bucket, region, namespace, path_prefix=None)` ¶

Delivery to Oracle Cloud Storage.

Parameters:

Name	Type	Description	Default
`customer_access_key_id`	`str`	Customer Secret Key credentials.	required
`customer_secret_key`	`str`	Customer Secret Key credentials.	required
`bucket`	`str`	The name of the bucket that will receive the order output.	required
`region`	`str`	The region where the bucket lives in Oracle.	required
`namespace`	`str`	Object Storage namespace name.	required
`path_prefix`	`Optional[str]`	Path prefix for deliveries.	`None`

`planetary_variable_source(var_type, var_id, geometry, start_time, end_time=None)` ¶

Construct a Planetary Variable subscription source.

Planetary Variables come in 4 types and are further subdivided within these types. See Subscribing to Planetary Variables for details.

The return value can be passed to planet.subscription_request.build_request.

Note: this function does not validate variable types and ids.

Parameters:

Name	Type	Description	Default
`var_type`	`Literal['analysis_ready_ps', 'biomass_proxy', 'land_surface_temperature', 'soil_water_content', 'vegetation_optical_depth', 'forest_carbon_diligence_30m', 'field_boundaries_sentinel_2_p1m']`	one of "analysis_ready_ps", "biomass_proxy", "land_surface_temperature", "soil_water_content", "vegetation_optical_depth", "forest_carbon_diligence_30m, or field_boundaries_sentinel_2_p1m".	required
`var_id`	`str`	a value such as "SWC-AMSR2-C_V1.0_100" for soil water content derived from AMSR2 C band.	required
`geometry`	`Mapping`	The area of interest of the subscription that will be used to determine matches.	required
`start_time`	`datetime`	The start time of the subscription. This time can be in the past or future.	required
`end_time`	`Optional[datetime.datetime]`	The end time of the subscription. This time can be in the past or future, and must be after the start_time.	`None`

Returns:

Type	Description
`dict`	a representation of a subscription source.

Exceptions:

Type	Description
`ClientError`	if a source can not be configured.

Examples:

pv_source = planetary_variables_source(
    "soil_water_content",
    "SWC-AMSR2-C_V1.0_100",
    geometry={
        "type": "Polygon",
        "coordinates": [
            [
                [37.791595458984375, 14.84923123791421],
                [37.90214538574219, 14.84923123791421],
                [37.90214538574219, 14.945448293647944],
                [37.791595458984375, 14.945448293647944],
                [37.791595458984375, 14.84923123791421],
            ]
        ],
    },
    start_time=datetime(2021, 3, 1),
)

request = build_request(
    "soil_water_subscription",
    source=pv_source,
    delivery={},
)

`reproject_tool(projection, resolution=None, kernel='near')` ¶

Specify a subscriptions API reproject tool.

Parameters:

Name	Type	Description	Default
`projection`	`str`	A coordinate system in the form EPSG:n (for example, EPSG:4326 for WGS84, EPSG:32611 for UTM 11 North (WGS84), or EPSG:3857 for Web Mercator). Well known text CRS values are also supported (for example, WGS84).	required
`resolution`	`Optional[float]`	The pixel width and height in the output file. If not provided, the default is the resolution of the input item. This value is in meters unless the coordinate system is geographic (such as EPSG:4326), in which case, it is pixel size in decimal degrees.	`None`
`kernel`	`str`	The resampling kernel used. UDM files always use "near".	`'near'`

Exceptions:

Type	Description
`planet.exceptions.ClientError`	If kernel is not valid.

`sentinel_hub(collection_id)` ¶

Specify a Sentinel Hub hosting destination.

Requires the user to have a Sentinel Hub account linked with their Planet account. Subscriptions API will create a new collection to deliver data to if collection_id is omitted from the request.

Parameters:

Name	Type	Description	Default
`collection_id`	`Optional[str]`	Sentinel Hub collection	required

`toar_tool(scale_factor=10000)` ¶

Specify a subscriptions API reproject tool.

The toar tool supports the analytic asset type for PSScene, PSOrthoTile, and REOrthoTile item types. In addition to the analytic asset, the corresponding XML metadata asset type is required.

Parameters:

Name	Type	Description	Default
`scale_factor`	`int`	Scale factor applied to convert 0.0 to 1.0 reflectance floating point values to a value that fits in 16bit integer pixels. The API default is 10000. Values over 65535 could result in high reflectances not fitting in 16bit integers.	`10000`

`reporting` ¶

Functionality for reporting progress.

`AssetStatusBar (ProgressBar)` ¶

Bar reporter of asset status.

`init(self, item_type, item_id, asset_type, disable=False)` `special` ¶

Initialize the object.

`open_bar(self)` ¶

Initialize and start the progress bar.

`ProgressBar` ¶

Abstract base class for progress bar reporters.

`open_bar(self)` ¶

Initialize and start the progress bar.

`StateBar (ProgressBar)` ¶

Bar reporter of order state.

Examples:

from planet import reporting

with reporting.StateBar(state='creating') as bar:
    bar.update(state='created', order_id='oid')
    ...

`init(self, order_id=None, state=None, disable=False)` `special` ¶

Initialize the object.

Parameters:

Name	Type	Description	Default
`order_id`	`Optional[str]`	Id of the order.	`None`
`state`	`Optional[str]`	State of the order.	`None`

`open_bar(self)` ¶

Initialize and start the progress bar.

`update_state(self, state)` ¶

Simple function to be used as a callback for state reporting

Python SDK API Reference

Auth ¶

from_env(variable_name=None) staticmethod ¶

from_file(filename=None) staticmethod ¶

from_key(key) staticmethod ¶

from_login(email, password, base_url=None) staticmethod ¶

store(self, filename=None) ¶

Session (BaseSession) ¶

__init__(self, auth=None) special ¶

client(self, name, base_url=None) ¶

request(self, method, url, json=None, params=None) async ¶

stream(self, method, url) ¶

OrdersClient ¶

__init__(self, session, base_url=None) special ¶

aggregated_order_stats(self) async ¶

cancel_order(self, order_id) async ¶

cancel_orders(self, order_ids=None) async ¶

create_order(self, request) async ¶

download_asset(self, location, filename=None, directory=PosixPath('.'), overwrite=False, progress_bar=True) async ¶

download_order(self, order_id, directory=PosixPath('.'), overwrite=False, progress_bar=False) async ¶

get_order(self, order_id) async ¶

list_orders(self, state=None, limit=100) ¶

validate_checksum(directory, checksum) staticmethod ¶

wait(self, order_id, state=None, delay=5, max_attempts=200, callback=None) async ¶

order_request ¶

amazon_s3(aws_access_key_id, aws_secret_access_key, bucket, aws_region, path_prefix=None) ¶

azure_blob_storage(account, container, sas_token, storage_endpoint_suffix=None, path_prefix=None) ¶

band_math_tool(b1, b2=None, b3=None, b4=None, b5=None, b6=None, b7=None, b8=None, b9=None, b10=None, b11=None, b12=None, b13=None, b14=None, b15=None, pixel_type='Auto') ¶

build_request(name, products, subscription_id=0, delivery=None, notifications=None, order_type=None, tools=None, stac=None) ¶

clip_tool(aoi) ¶

composite_tool() ¶

coregister_tool(anchor_item) ¶

delivery(archive_type=None, single_archive=False, archive_filename=None, cloud_config=None) ¶

file_format_tool(file_format) ¶

google_cloud_storage(bucket, credentials, path_prefix=None) ¶

google_earth_engine(project, collection) ¶

harmonize_tool(target_sensor) ¶

notifications(email=None, webhook_url=None, webhook_per_order=None) ¶

product(item_ids, product_bundle, item_type, fallback_bundle=None) ¶

reproject_tool(projection, resolution=None, kernel=None) ¶

tile_tool(tile_size, origin_x=None, origin_y=None, pixel_size=None, name_template=None, conformal_x_scaling=None) ¶

toar_tool(scale_factor=None) ¶

DataClient ¶

__init__(self, session, base_url=None) special ¶

activate_asset(self, asset) async ¶

create_search(self, item_types, search_filter, name, enable_email=False) async ¶

delete_search(self, search_id) async ¶

download_asset(self, asset, filename=None, directory=PosixPath('.'), overwrite=False, progress_bar=True) async ¶

get_asset(self, item_type_id, item_id, asset_type_id) async ¶

get_search(self, search_id) async ¶

get_stats(self, item_types, search_filter, interval) async ¶

list_item_assets(self, item_type_id, item_id) async ¶

list_searches(self, sort='created desc', search_type='any', limit=100) ¶

run_search(self, search_id, sort=None, limit=100) ¶

search(self, item_types, search_filter=None, name=None, sort=None, limit=100) ¶

update_search(self, search_id, item_types, search_filter, name, enable_email=False) async ¶

validate_checksum(asset, filename) staticmethod ¶

wait_asset(self, asset, delay=5, max_attempts=200, callback=None) async ¶

data_filter ¶

and_filter(nested_filters) ¶

asset_filter(asset_types) ¶

date_range_filter(field_name, gt=None, lt=None, gte=None, lte=None) ¶

empty_filter() ¶

geometry_filter(geom) ¶

not_filter(nested_filter) ¶

number_in_filter(field_name, values) ¶

or_filter(nested_filters) ¶

permission_filter() ¶

range_filter(field_name, gt=None, lt=None, gte=None, lte=None) ¶

std_quality_filter() ¶

string_in_filter(field_name, values) ¶

update_filter(field_name, gt=None, lt=None, gte=None, lte=None) ¶

SubscriptionsClient ¶

__init__(self, session, base_url=None) special ¶

cancel_subscription(self, subscription_id) async ¶

create_subscription(self, request) async ¶

get_results(self, subscription_id, status=None, limit=100) ¶

get_results_csv(self, subscription_id, status=None, limit=100) ¶

get_subscription(self, subscription_id) async ¶

list_subscriptions(self, status=None, limit=100) ¶

`Auth` ¶

`from_env(variable_name=None)` `staticmethod` ¶

`from_file(filename=None)` `staticmethod` ¶

`from_key(key)` `staticmethod` ¶

`from_login(email, password, base_url=None)` `staticmethod` ¶

`store(self, filename=None)` ¶

`Session (BaseSession)` ¶

`init(self, auth=None)` `special` ¶

`client(self, name, base_url=None)` ¶

`request(self, method, url, json=None, params=None)` `async` ¶

`stream(self, method, url)` ¶

`OrdersClient` ¶

`init(self, session, base_url=None)` `special` ¶

`aggregated_order_stats(self)` `async` ¶

`cancel_order(self, order_id)` `async` ¶

`cancel_orders(self, order_ids=None)` `async` ¶

`create_order(self, request)` `async` ¶

`download_asset(self, location, filename=None, directory=PosixPath('.'), overwrite=False, progress_bar=True)` `async` ¶

`download_order(self, order_id, directory=PosixPath('.'), overwrite=False, progress_bar=False)` `async` ¶

`get_order(self, order_id)` `async` ¶

`list_orders(self, state=None, limit=100)` ¶

`validate_checksum(directory, checksum)` `staticmethod` ¶

`wait(self, order_id, state=None, delay=5, max_attempts=200, callback=None)` `async` ¶

`order_request` ¶

`amazon_s3(aws_access_key_id, aws_secret_access_key, bucket, aws_region, path_prefix=None)` ¶

`azure_blob_storage(account, container, sas_token, storage_endpoint_suffix=None, path_prefix=None)` ¶

`band_math_tool(b1, b2=None, b3=None, b4=None, b5=None, b6=None, b7=None, b8=None, b9=None, b10=None, b11=None, b12=None, b13=None, b14=None, b15=None, pixel_type='Auto')` ¶

`build_request(name, products, subscription_id=0, delivery=None, notifications=None, order_type=None, tools=None, stac=None)` ¶

`clip_tool(aoi)` ¶

`composite_tool()` ¶

`coregister_tool(anchor_item)` ¶

`delivery(archive_type=None, single_archive=False, archive_filename=None, cloud_config=None)` ¶

`file_format_tool(file_format)` ¶

`google_cloud_storage(bucket, credentials, path_prefix=None)` ¶

`google_earth_engine(project, collection)` ¶

`harmonize_tool(target_sensor)` ¶

`notifications(email=None, webhook_url=None, webhook_per_order=None)` ¶

`product(item_ids, product_bundle, item_type, fallback_bundle=None)` ¶

`reproject_tool(projection, resolution=None, kernel=None)` ¶

`tile_tool(tile_size, origin_x=None, origin_y=None, pixel_size=None, name_template=None, conformal_x_scaling=None)` ¶

`toar_tool(scale_factor=None)` ¶

`DataClient` ¶

`init(self, session, base_url=None)` `special` ¶

`activate_asset(self, asset)` `async` ¶

`create_search(self, item_types, search_filter, name, enable_email=False)` `async` ¶

`delete_search(self, search_id)` `async` ¶

`download_asset(self, asset, filename=None, directory=PosixPath('.'), overwrite=False, progress_bar=True)` `async` ¶

`get_asset(self, item_type_id, item_id, asset_type_id)` `async` ¶

`get_search(self, search_id)` `async` ¶

`get_stats(self, item_types, search_filter, interval)` `async` ¶

`list_item_assets(self, item_type_id, item_id)` `async` ¶

`list_searches(self, sort='created desc', search_type='any', limit=100)` ¶

`run_search(self, search_id, sort=None, limit=100)` ¶

`search(self, item_types, search_filter=None, name=None, sort=None, limit=100)` ¶

`update_search(self, search_id, item_types, search_filter, name, enable_email=False)` `async` ¶

`validate_checksum(asset, filename)` `staticmethod` ¶

`wait_asset(self, asset, delay=5, max_attempts=200, callback=None)` `async` ¶

`data_filter` ¶

`and_filter(nested_filters)` ¶

`asset_filter(asset_types)` ¶

`date_range_filter(field_name, gt=None, lt=None, gte=None, lte=None)` ¶

`empty_filter()` ¶

`geometry_filter(geom)` ¶

`not_filter(nested_filter)` ¶

`number_in_filter(field_name, values)` ¶

`or_filter(nested_filters)` ¶

`permission_filter()` ¶

`range_filter(field_name, gt=None, lt=None, gte=None, lte=None)` ¶

`std_quality_filter()` ¶

`string_in_filter(field_name, values)` ¶

`update_filter(field_name, gt=None, lt=None, gte=None, lte=None)` ¶

`SubscriptionsClient` ¶

`init(self, session, base_url=None)` `special` ¶

`cancel_subscription(self, subscription_id)` `async` ¶

`create_subscription(self, request)` `async` ¶

`get_results(self, subscription_id, status=None, limit=100)` ¶

`get_results_csv(self, subscription_id, status=None, limit=100)` ¶

`get_subscription(self, subscription_id)` `async` ¶

`list_subscriptions(self, status=None, limit=100)` ¶

`patch_subscription(self, subscription_id, request)` `async` ¶