Planet SDK for Python
Project description
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).
Installation
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
or conda.
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 --pre command:
$ 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
forum.
Documentation
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 [docs](docs/) directory.
Quick Start
The Planet SDK includes both a Python API and a command-line interface (CLI) to make use of the following Planet APIs:
- orders
- data (mostly complete)
- subscriptions (in progress)
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: <youremail@domain.com>
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
item-type
to get the right type of image. And then be sure to specify a
bundle.
The most common ones are visual and analytic.
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 --max-attempts option.
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
User Guide
and the CLI Reference.
Authentication
Planet's APIs require an account for use. Sign up here or if you are developer try the developer trial.
Development
To contribute or develop with this library, see CONTRIBUTING.md.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file planet-2.0a3.tar.gz.
File metadata
- Download URL: planet-2.0a3.tar.gz
- Upload date:
- Size: 51.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.7.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | dc4cb41fc8a9cdd294a409aa43d34dda5cf74c8e84a4467a6b8c287a0d362831 |
|
| MD5 | 9ba33fa2fcd489a7556f88ef45e6d771 |
|
| BLAKE2b-256 | f86565a38de852fcbaa6ef41ef5e11db7300d1ac2e5790d451dfaceff0a6f82f |
Provenance
File details
Details for the file planet-2.0a3-py2.py3-none-any.whl.
File metadata
- Download URL: planet-2.0a3-py2.py3-none-any.whl
- Upload date:
- Size: 67.3 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.7.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 6a7b8817670886474951b99a65e9d9245f858143fb1ab6b00e670cc8835b79cc |
|
| MD5 | 2cb5497f03d3c030d2858d09a253edc1 |
|
| BLAKE2b-256 | 82c9faef41288e74847f35c7883aebea1a6a92af77b3ab3d3a46a7af7cfe0184 |
