Skip to content

Commit 837b24d

Browse files
stephenhillierstephenhillier
authored
Merge pull request #1087 from planetlabs/steve/sdk-docs
refactor sdk and cli guides
2 parents b58146a + 97b93ca commit 837b24d

File tree

6 files changed

+806
-716
lines changed

6 files changed

+806
-716
lines changed

‎docs/cli/cli-guide.md‎

Lines changed: 123 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,127 @@ with numerous samples to get you started.
2323
geospatial CLI command-line tools and shows you how to use them in conjunction
2424
with Planet’s tools.
2525

26-
## CLI Set-up
26+
## Step 1: Install Python 3.9+ and a virtual environment
2727

28-
Getting your CLI set up with your Planet account is covered in the
29-
[Quick Start Guide](../get-started/quick-start-guide.md), so be sure
30-
to do that before going into any of the next sections.
28+
This is a Python package, so you’ll need to install Python (version 3.9 or greater), and set up and install a virtual environment.
29+
30+
Yes. Even if you’re not writing code—and only using the "no code" CLI part of the Planet SDK for Python—you’re using Python to communicate with the Planet Labs PBC servers. If you need help with Python install and setting up a virtual environment, read [Virtual Environments and the Planet SDK for Python](../get-started/venv-tutorial.md).
31+
32+
## Step 2: Install the Planet SDK for Python
33+
34+
Install the Planet SDK for Python using [pip](https://pip.pypa.io):
35+
36+
```console
37+
$ pip install planet
38+
```
39+
40+
## Step 3: Check the Planet SDK for Python version
41+
42+
```console
43+
$ planet --version
44+
```
45+
46+
You should be on some version 2 of the Planet SDK for Python.
47+
48+
## Step 4: Sign on to your account
49+
50+
Planet SDK for Python, like the Planet APIs, requires an account for use.
51+
52+
### Have your Planet account username and password ready
53+
54+
To confirm your Planet account, or to get one if you don’t already have one, see [Get your Planet Account](../get-started/get-your-planet-account.md).
55+
56+
### Authenticate with the Planet server
57+
58+
Just as you log in when you browse to https://account.planet.com, you’ll want to sign on to your account so you have access to your account and orders.
59+
60+
At a terminal console, type the following Planet command:
61+
62+
```console
63+
$ planet auth init
64+
```
65+
66+
You’ll be prompted for the email and password you use to access [your account](https://account.planet.com). When you type in your password, you won’t see any indication that the characters are being accepted. But when you hit enter, you’ll know that you’ve succeeded because you’ll see on the command line:
67+
68+
```console
69+
Initialized
70+
```
71+
72+
### Get your API key
73+
74+
Now that you’ve logged in, you can easily retrieve your API key that is being used for requests with the following command:
75+
76+
```console
77+
planet auth value
78+
```
79+
80+
Many `planet` calls you make require an API key. This is a very convenient way to quickly grab your API key.
81+
82+
#### Your API Key as an Environment Variable
83+
84+
You can also set the value of your API Key as an environment variable in your terminal at the command line:
85+
86+
```console
87+
export PL_API_KEY=<your api key>
88+
```
89+
90+
And you can see that the value was stored successfully as an environment variable with the following command:
91+
92+
```console
93+
echo $PL_API_KEY
94+
```
95+
96+
!!!note "The API Key environment variable is ignored by the CLI but used by the Python library"
97+
If you do create a `PL_API_KEY` environment variable, the CLI will be unaffected but the Planet library will use this as the source for authorization instead of the value stored in `planet auth init`.
98+
99+
## Step 5: Search for Planet Imagery
100+
101+
You’ve installed the environment, the SDK, and connected with the Planet server. You’re now ready to get your first bunch of data.
102+
103+
In this step, you search for the most recent PSScene images available to download and filter the list based on those images you actually have permissions to download.
104+
105+
### planet data filter
106+
107+
One of the commands you’ll use most frequently is `planet data filter`. This “convenience method” creates the JSON you need to run other commands. Run it with no arguments to see how it works by default:
108+
109+
```console
110+
planet data filter --permission --std-quality
111+
```
112+
113+
Look at the console output to see some default filters. `PermissionFilter` filters the output to only contain imagery that you have permission to download. You’ll also see `quality_category`, which means the output lists only images in the [`standard quality` category](https://developers.planet.com/docs/data/planetscope/#image-quality-standard-vs-test-imagery). Without these options, an empty filter is generated which would be used to disable filtering and simply return all results.
114+
115+
!!!note "The --help switch is your friend"
116+
You can do a lot with this `filter` command. We recommend running `planet data filter --help` often to get a reference of how the commands work.
117+
118+
### planet data search
119+
120+
Run the filter command and save it to a file named `filter.json`:
121+
122+
```console
123+
planet data filter --permission --std-quality > filter.json
124+
```
125+
126+
Then use that file with the search command and save the results to another file named `recent-psscene.json`.
127+
128+
```console
129+
planet data search PSScene --filter filter.json > recent-psscene.json
130+
```
131+
132+
Open `recent-psscene.json` to see the 100 most recent PSScene images you have permissions to actually download.
133+
134+
## Next steps
135+
136+
Now that you have the quick setup for the Planet SDK for Python, you have a few options:
137+
138+
* Continue to explore the [No-Code CLI Guide](#cli-guide-overview).
139+
* Start coding with the [Python SDK User Guide](../python/sdk-guide.md).
140+
* Check out some of the [examples in our GitHub repo](https://github.com/planetlabs/planet-client-python/tree/main/examples).
141+
142+
## How to Get Help
143+
144+
As The Planet SDK (V2) is in active development, features & functionality will continue to be added.
145+
146+
If there's something you're missing or are stuck, the development team would love to hear from you.
147+
148+
- To report a bug or suggest a feature, [raise an issue on GitHub](https://github.com/planetlabs/planet-client-python/issues/new)
149+
- To get in touch with the development team, email [developers@planet.com](mailto:developers@planet.com)

‎docs/get-started/quick-start-guide.md‎

Lines changed: 23 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,48 @@
11
---
2-
title: Quick Start Guide
2+
title: Python SDK Quick Start
33
---
44

5+
The Planet SDK for Python makes it easy to access Planet’s massive repository of satellite imagery and add Planet
6+
data to your data ops workflow.
57

6-
If you’re a Python developer, this Planet SDK for Python makes it easy to access Planet’s massive repository of satellite imagery and add Planet data to your data ops workflow.
8+
**Note:** This is the new, non-asyncio client. If you want to take advantage of asyncio, see the [async client guide](../python/async-sdk-guide.md). For the no-code CLI client, see the [CLI guide](../cli/cli-guide.md).
79

8-
If you’re not a Python developer, you can use the Command Line Interface (CLI) to get Planet data, and to process and analyze that data.
10+
Your feedback on this version of our client is appreciated. Please raise an issue on [GitHub](https://github.com/planetlabs/planet-client-python/issues) if you encounter any problems.
911

10-
Take the following steps to install the SDK and connect with the Planet Server.
12+
## Dependencies
1113

12-
[TOC]
14+
This package requires [Python 3.9 or greater](https://python.org/downloads/). A virtual environment is strongly recommended.
1315

14-
## Step 1: Install Python 3.9+ and a virtual environment
16+
You will need your Planet API credentials. You can find your API key in [Planet Explorer](https://planet.com/explorer) under Account Settings.
1517

16-
This is a Python package, so you’ll need to install Python (version 3.9 or greater), and set up and install a virtual environment.
18+
## Installation
1719

18-
Yes. Even if you’re not writing code—and only using the "no code" CLI part of the Planet SDK for Python—you’re using Python to communicate with the Planet Labs PBC servers. If you need help with Python install and setting up a virtual environment, read [Virtual Environments and the Planet SDK for Python](venv-tutorial.md).
20+
Install from PyPI using pip:
1921

20-
## Step 2: Install the Planet SDK for Python
21-
22-
Install the Planet SDK for Python using [pip](https://pip.pypa.io):
23-
24-
```console
25-
$ pip install planet
26-
```
27-
28-
## Step 3: Check the Planet SDK for Python version
29-
30-
```console
31-
$ planet --version
22+
```bash
23+
pip install planet
3224
```
3325

34-
You should be on some version 2 of the Planet SDK for Python.
35-
36-
## Step 4: Sign on to your account
26+
## Usage
3727

38-
Planet SDK for Python, like the Planet APIs, requires an account for use.
28+
### Authentication
3929

40-
### Have your Planet account username and password ready
30+
Use the `PL_API_KEY` environment variable to authenticate with the Planet API. For other authentication options, see the [SDK guide](../python/sdk-guide.md).
4131

42-
To confirm your Planet account, or to get one if you don’t already have one, see [Get your Planet Account](get-your-planet-account.md).
43-
44-
### Authenticate with the Planet server
45-
46-
Just as you log in when you browse to https://account.planet.com, you’ll want to sign on to your account so you have access to your account and orders.
47-
48-
At a terminal console, type the following Planet command:
49-
50-
```console
51-
$ planet auth init
32+
```bash
33+
export PL_API_KEY=your_api_key
5234
```
5335

54-
You’ll be prompted for the email and password you use to access [your account](https://account.planet.com). When you type in your password, you won’t see any indication that the characters are being accepted. But when you hit enter, you’ll know that you’ve succeeded because you’ll see on the command line:
55-
56-
```console
57-
Initialized
58-
```
59-
60-
### Get your API key
61-
62-
Now that you’ve logged in, you can easily retrieve your API key that is being used for requests with the following command:
63-
64-
```console
65-
planet auth value
66-
```
67-
68-
Many `planet` calls you make require an API key. This is a very convenient way to quickly grab your API key.
69-
70-
#### Your API Key as an Environment Variable
71-
72-
You can also set the value of your API Key as an environment variable in your terminal at the command line:
73-
74-
```console
75-
export PL_API_KEY=<your api key>
76-
```
36+
### The Planet client
7737

78-
And you can see that the value was stored successfully as an environment variable with the following command:
38+
The `Planet` class is the main entry point for the Planet SDK. It provides access to the various APIs available on the Planet platform.
7939

80-
```console
81-
echo $PL_API_KEY
40+
```python
41+
from planet import Planet
42+
pl = Planet() # automatically detects PL_API_KEY
8243
```
8344

84-
!!!note "The API Key environment variable is ignored by the CLI but used by the Python library"
85-
If you do create a `PL_API_KEY` environment variable, the CLI will be unaffected but the Planet library will use this as the source for authorization instead of the value stored in `planet auth init`.
86-
87-
## Step 5: Search for Planet Imagery
88-
89-
You’ve installed the environment, the SDK, and connected with the Planet server. You’re now ready to get your first bunch of data.
90-
91-
In this step, you search for the most recent PSScene images available to download and filter the list based on those images you actually have permissions to download.
92-
93-
### planet data filter
94-
95-
One of the commands you’ll use most frequently is `planet data filter`. This “convenience method” creates the JSON you need to run other commands. Run it with no arguments to see how it works by default:
96-
97-
```console
98-
planet data filter --permission --std-quality
99-
```
100-
101-
Look at the console output to see some default filters. `PermissionFilter` filters the output to only contain imagery that you have permission to download. You’ll also see `quality_category`, which means the output lists only images in the [`standard quality` category](https://developers.planet.com/docs/data/planetscope/#image-quality-standard-vs-test-imagery). Without these options, an empty filter is generated which would be used to disable filtering and simply return all results.
102-
103-
!!!note "The --help switch is your friend"
104-
You can do a lot with this `filter` command. We recommend running `planet data filter --help` often to get a reference of how the commands work.
105-
106-
### planet data search
107-
108-
Run the filter command and save it to a file named `filter.json`:
109-
110-
```console
111-
planet data filter --permission --std-quality > filter.json
112-
```
113-
114-
Then use that file with the search command and save the results to another file named `recent-psscene.json`.
115-
116-
```console
117-
planet data search PSScene --filter filter.json > recent-psscene.json
118-
```
119-
120-
Open `recent-psscene.json` to see the 100 most recent PSScene images you have permissions to actually download.
121-
122-
## Next steps
123-
124-
Now that you have the quick setup for the Planet SDK for Python, you have a few options:
125-
126-
* Continue to explore the [No-Code CLI Guide](../cli/cli-guide.md).
127-
* Start coding with the [Python SDK User Guide](../python/sdk-guide.md).
128-
* Check out some of the [examples in our GitHub repo](https://github.com/planetlabs/planet-client-python/tree/main/examples).
45+
The Planet client has members `data`, `orders`, and `subscriptions`, which allow you to interact with the Data API, Orders API, and Subscriptions API. Usage examples for searching, ordering and creating subscriptions can be found in the [SDK guide](../python/sdk-guide.md).
12946

13047
## How to Get Help
13148

0 commit comments

Comments
 (0)