Planet SDK for Python
Planet Software Development Kit (SDK) for Python.
Versions and Stability
The default branch (main) of this repo is for the Planet SDK for Python, a complete rewrite and upgrade from the original Planet Python Client. If you are looking for the source code to that library see the v1 branch.
The Planet SDK for Python is in 'pre-release' stages, working towards an initial release around July. Active development is tracked in the Planet SDK for Python Project. The initial release will support Orders, Data and Subscription API's in the command-line interface, with corresponding Python libraries. After the initial July release there will be additional work to support the remaining Planet API's (analytics, basemaps and tasking).
There are two options for installation: installing from PyPi or installing from source.
Be aware that using either route will by default update your
planet command-line and
python library to v2, so you will no longer be able to use v1. As v2 is in a pre-release
stage, with not all functionality implemented, we strongly recommend installing it in a
virtual environment - either venv
If you've never worked with either then check out our getting started with venv and Planet
SDK. For anyone planning to contribute to the SDK the instructuctions
are a bit different, see the testing section of CONTRIBUTING.md.
Both installation routes use pip, Python's package installer.
The --user flag is highly recommended for those new to pip.
The Planet SDK for Python requires Python 3.7+.
Installing from PyPi
This route is recommended for most users.
To get version 2 of the Planet SDK you just use pip with the
$ pip install planet --pre
If you've already got a v1 on your command-line you may need to use
--upgrade as well:
$ pip install --upgrade planet --pre
Installing from source
This option enables you to get all the latest changes, but things might also be a bit less stable. To install you must clone the planet-client-python repository to your local computer. After you have the repo local just navigate to the root directory, where this readme lives.
Then you can install locally with pip:
$ pip install .
Confirming its working
After installation you should be able to use the command-line interface. Just type
planet into the command-line and the usage and options should appear. To confirm that
it's v2 run
planet --version and it should report 2.0a1 or above. If it doesn't
work don't hesitate to ask for help in the discussions
Documentation is currently hosted online
It should be considered 'in progress', with many updates to come. It can also
be built and hosted locally (see CONTRIBUTING.md) or can be
read from source in the
The Planet SDK includes both a Python API and a command-line interface (CLI) to make use of the following Planet APIs:
This quickstart focuses on getting started with the CLI to place an order. For information on the Python API see the documentation
After you've installed the client, as explained in the installation section below, you first must initialize the client with your Planet username and password:
$ planet auth init Email: <firstname.lastname@example.org> Password: Initialized
The email address and password you use should be the same as your login to
Planet Explorer. The
auth init command
will automatically get your API key and store it locally.
Now that you're initialized let's start with creating an order request with the Orders API:
$ planet orders request --name my-first-order --id <scene-ids> \ --item-type PSScene --bundle visual > my_order.json
You should supply a unique name after
--name for each new order, to help
you identify the order. The
--id is one or more scene ids (separated by
commas). These can be obtained from the data API, and you can also grab them
from any search in Planet Explorer. Just be sure the scene id matches the
to get the right type of image. And then be sure to specify a
The most common ones are
Next, you may create an order with the Orders API:
$ planet orders create my_order.json
This will give you an order response JSON as shown in the 'example response' in
the Order API docs. You may also pipe the
request command to the
create command to avoid the creation of a request.json file:
$ planet orders request -name my-first-order --id <scene-ids> \ --item-type PSScene --bundle visual | planet orders create -
You can grab the
id from that response, which will look something like
dfdf3088-73a2-478c-a8f6-1bad1c09fa09. You can then use that order-id in a
single command to wait for the order and download it when you are ready:
$ planet orders wait <order-id> && planet orders download <order-id>
This usually takes at least a few minutes, and can be longer if it is a large request
(lots of items or big items like SkySatCollect). The default
wait will last about
15 minutes, but can easily be extended with the
You can also just wait to download until the order is fulfilled. To check on its status just use:
$ planet orders get <id>
And then use
planet download <id> when the order is ready.
There are many more options in the command-line interface. One of the best ways
to explore is to just use
--help after any command to see the options. There is
also lots of good information in the docs, in the
and the CLI Reference.
To contribute or develop with this library, see CONTRIBUTING.md.