By: Jennifer Reiber Kyle on February 16 2023
The second version of the Planet SDK for Python is in Beta! Install it as a package. Add it to your Conda environment. Install it from the source. And let us know what you think.
Introduction¶
We are excited to announce the Beta release of version two of our Planet SDK for Python! The Planet SDK (Software Development Kit) for Python is a Python package developed and maintained by the Developer Relations team at Planet. It is version two of what was previously known as the Planet Python Client and works with Python 3.7+. Version two is currently in development and has long been in the works. The beta version has been released and we’re pleased to introduce you to it. This blog post provides an introduction to the Planet SDK for Python and is the first in a blog series which will cover specific aspects of the SDK in more detail.
The Planet SDK for Python is a Python package developed and maintained by the Developer Relations team at Planet. It is version two of what was previously known as the Planet Python Client and it works with Python 3.7+. Currently, it is in development and the beta version has just been released. This blog post provides an introduction to the Planet SDK for Python and is the first in a blog series which will cover specific aspects of the SDK in more detail.
The Planet SDK for Python interfaces with the Planet APIs and has two parts: a Python client library and a command-line interface (CLI). It is free and open source (maintained on github) and available for use by anyone with a Planet API key. It allows developers to automate their tasks and workflows and enables integration with existing processes using Python and more accessible API interactions via the CLI.
In addition to providing Python and CLI interfaces for API endpoints, the SDK also simplifies tasks such as managing paged results, polling for when a resource is ready, and downloading resources. Additionally, it is optimized for fast and reliable http communication. The Python library speeds up complex and bulk operations through asynchronous communication with the servers. The CLI, on the other hand, is designed to fit into complex workflows with piping. These three functionalities will be covered in depth in future posts in this series.
Improvements over version one include a first-class, full-functionality Python library and optimized, robust communication with the servers.
CLI Usage¶
The CLI is designed to be simple enough to allow for quick interactions with the Planet APIs while also being suitable for inclusion in complex workflows. It supports JSON/GeoJSON as inputs and outputs, which can be provided and handled as files or standard input/output. Here, we demonstrate using the CLI to create and download an order with the Orders API.
Creating an order from an order request that has been saved in a file is pretty simple:
planet orders create order_request.json
The output of this command is the description of the created order. The order id from the description can be used to wait and download the order.
Waiting for the order to be ready and downloading the order is achieved with:
planet orders wait 65df4eb0-e416-4243-a4d2-38afcf382c30 \
&& planet orders download 65df4eb0-e416-4243-a4d2-38afcf382c30
Additionally, the CLI provides support for creating order requests. These requests can be saved as a file or piped directly into the command for creating the order:
planet orders request --item-type PSScene \
--bundle analytic_sr_udm2 \
--name 'Two Item Order' \
20220605_124027_64_242b,20220605_124025_34_242b \
| planet orders create -
See the CLI documentation for more examples and a code example for how to search the Data API for a PSScene item id for use in defining the order.
Python Library Usage¶
Planet’s Python library provides optimized and robust communication with the Planet servers. To provide lightning-fast communication in bulk operations, this library is asynchronous. Asynchronous support was added to the Python standard library in version 3.7. Our Python library documentation provides coding examples specifically geared toward the use of the SDK asynchronously. The Python asyncio module documentation is also a great resource.
Here, we demonstrate using the Python library to create and download an order with a defined order request:
import asyncio
from planet import reporting, Session, OrdersClient
request = {
"name": "Two Item Order",
"products": [
{
"item_ids": [
"20220605_124027_64_242b",
"20220605_124025_34_242b"
],
"item_type": "PSScene",
"product_bundle": "analytic_sr_udm2"
}
],
"metadata": {
"stac": {}
}
}
# use "async def" to create an async coroutine
async def create_poll_and_download():
async with Session() as sess:
cl = OrdersClient(sess)
with reporting.StateBar(state='creating') as bar:
# create order via Orders client
# use "await" to run a coroutine
order = await cl.create_order(request)
bar.update(state='created', order_id=order['id'])
# poll...poll...poll...
await cl.wait(order['id'], callback=bar.update_state)
# The order completed. Yay! Now download the files
await cl.download_order(order['id'])
# run the entire coroutine in the event loop
asyncio.run(create_poll_and_download())
The Python library also provides support for creating an order request with the order_request module:
from planet import order_request
item_ids = ["20220605_124027_64_242b", "20220605_124025_34_242b"]
products = [
order_request.product(item_ids, "analytic_sr_udm2", "PSScene")
]
tools = [
order_request.reproject_tool(projection="EPSG:4326", kernel="cubic")
]
request = order_request.build_request(
"Two Item Order, reprojected", products=products, tools=tools)
See the Python library documentation for more examples and a code example for how to search the Data API for the PSScene item ids used in defining the order.
Next Steps¶
Check it out for yourself! Get instructions on how to install the Planet SDK for Python, learn more about the package, and get plenty of code examples at https://planet-sdk-for-python-v2.readthedocs.io. Browse the source code and track progress at https://github.com/planetlabs/planet-client-python. Check out our Resources Page of Jupyter Notebooks for help getting started. Our Jupyter Notebooks include: Get started guides for Planet API Python Client, Order API & Planet SDK, the Analysis Ready Data Tutorial Part 1: Introduction and Best Practices, and the Analysis Ready Data Tutorial Part 2. Chat with us about any ideas or issues at https://community.planet.com/developers-55. Follow us on twitter @planetdevs.
