Upgrade from Version 1 to Version 2
The Planet SDK for Python is Version 2 of what was previously referred to as the Planet API client. This V2 is a major update of the V1 SDK. As such, there are major structural changes to how it operates. However, many aspects are still quite similar to V1. Follow this migration guide to upgrade an application developed with V1 of the SDK to V2 with minimal fuss.
Imports¶
The V2 SDK has a flatter code structure. Everything of note previously found under planet.api
is now available from the planet
module. So, import planet
should give you everything you need.
If you are migrating from V1, and are using the Data API filter builder (from planet.api import filters
), we do recommend also including from planet import data_filter as filters
in your imports for an easy migration from the old filter module to the new one.
Authentication¶
If you have your API key stored in the PL_API_KEY
environment variable you will be automatically authenticated to the V2 API, similar to how V1 worked. For other methods for authenticating against the V2 SDK, check out Authenticate with the Planet server.
Session for all communication¶
In Version 2, sessions are used to manage all communication with the Planet APIs. This provides for multiple asynchronous connections. For each API, there is a specific client object. This client manages polling and downloading, along with any other capabilities provided by the API.
Each client now requires a Session
object, which stores connection information and authentication and manages an HTTP connection pool.
The best way of doing this is wrapping any code that invokes a client class in a block like so:
from planet import OrdersClient, Session
async with Session() as session:
client = OrdersClient(session)
result = await client.create_order(order)
# Process result
You will see this usage in the project’s tests and in the planet.cli
package. As a convenience, you may also get a service client instance from a
session’s client()
method.
async with Session() as session:
client = session.client('orders')
result = await client.create_order(order)
# Process result
For more information about Session, refer to the Python SDK User Guide.
Asynchronous Methods¶
With the V1 client, all communication was synchronous. Asynchronous bulk support was provided with the downloader
module. There was no built-in support for polling when an order was ready to download or tracking when an order was downloaded.
In V2, all *Client
methods (for example, DataClient().search
, OrderClient().create_order
) are asynchronous. Any functions that call such methods must include async
in their definition. To invoke asynchronous methods from synchronous code, you can wrap the async method calls in asyncio.run()
. The following is an example of using async with session.
import asyncio
from datetime import datetime
from planet import Session
from planet import data_filter as filters
async def do_search():
async with Session() as session:
client = session.client('data')
date_filter = filters.date_range_filter('acquired', gte=datetime.fromisoformat("2022-11-18"), lte=datetime.fromisoformat("2022-11-21"))
cloud_filter = filters.range_filter('cloud_cover', lte=0.1)
download_filter = filters.permission_filter()
return [item async for item in client.search(["PSScene"], filters.and_filter([date_filter, cloud_filter, download_filter]))]
items = asyncio.run(do_search())
For more details on interacting with the asynchronous portions of the SDK, refer to the Python SDK User Guide.
Data API¶
The Data API portion of SDK V2 is quite similar to V1, although some filters have been renamed for consistency (also reference the note on imports):
date_range
todate_range_filter
geom_filter
togeometry_filter
and_filter
andor_filter
now takes a list of filters instead of multiple arguments, so just wrap the contents in[]
permissions_filter
is now split intopermissions_filter
andasset_filter
, reflecting a recent change in API structure. If you were using this previously, you’ll want to convert the oldpermissions_filter
into anasset_filter
(this also involves changing the filter values, e.g.assets.ortho_analytic_8b_sr:download
will becomeortho_analytic_8b_sr
) and adding an emptypermissions_filter
.
filters.build_seach_request
no longer exists, and has instead been integrated into the replacement for client.quick_seach
. For example:
planet.api.ClientV1().quick_search(filters.build_search_request(all_filters, ["PSScene"]))
Is now
async with Session() as session:
items = [i async for i in session.client('data').search(["PSScene"], all_filters)]
Orders API¶
The Orders API capabilities in V1 were quite primitive, but those that did exist have been retained in much the same form; ClientV1().create_order
becomes OrdersClient(session).create_order
. (As with the DataClient
, you must also use async
and Session
with OrdersClient
.)
Additionally, there is now also an order builder in planet.order_request
, similar to the preexisting search filter builder. For more details on this, refer to the Creating an Order.