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. |
update_subscription(self, subscription_id, request)
async
¶
Update (edit) a Subscription.
Args subscription_id (str): id of the subscription to update. request (dict): subscription content for update.
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.
amazon_s3(aws_access_key_id, aws_secret_access_key, bucket, aws_region)
¶
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 |
azure_blob_storage(account, container, sas_token, storage_endpoint_suffix=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 |
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, notifications=None, tools=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 |
Mapping |
A delivery mechanism e.g. GCS, AWS, Azure, or OCS. |
required |
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 |
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")
subscription_request = build_request(
"test_subscription", source=source, delivery=delivery
)
```
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[typing_extensions.Literal['preview', 'standard', 'finalized']]] |
A sequence of one or more of the values "preview", "standard", or "finalized". |
None |
time_range_type |
Optional[typing_extensions.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. |
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)
¶
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 |
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)
¶
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 |
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 |
typing_extensions.Literal['biomass_proxy', 'land_surface_temperature', 'soil_water_content', 'vegetation_optical_depth'] |
one of "biomass_proxy", "land_surface_temperature", "soil_water_content", or "vegetation_optical_depth". |
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. |
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)
¶
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