Authentication¶
The Planet API uses Basic HTTP Authentication and requires that you have a Planet API key. Currently, anyone can sign up for a free account on our main website. The free account gives you access to imagery from anywhere in the world at 3-5 m/px resolution.
Once you're signed up, you can find your API key in your account
settings. Authenticate by setting username
to your API key.
**Authentication Via Basic HTTP with Python
import os
# import os module to access enviornmental modules
import requests
os.environ['PL_API_KEY']='12345'
# pass in your API key
PLANET_API_KEY = os.getenv('PL_API_KEY')
# Setup the API Key from the `PL_API_KEY` environment variable
BASE_URL = "https://api.planet.com/analytics/"
session = requests.Session()
#setup a session
session.auth = (PLANET_API_KEY, "")
#authenticate session with user name and password, pass in an empty string for the password
res = session.get(BASE_URL)
#make a get request to the Data API
print(res.status_code)
# test response
print(res.text)
# print response body
Authentication Via cURL
curl -u {api-key}: https://api.planet.com/analytics/
Pagination¶
The Planet Analytics API paginates responses to limit the results, making them easier to
work with. The JSON response will contain 250 detections maximum by default.
The first GET request will yield the first page along with links
representing the location of the next page. Following the next link will
return another page of results. To get more results we link the rel of next.
For a more detailed guide on accessing and paginating through our analytic feeds
check out this jupyter notebook.
Rate Limiting¶
To improve the experience for all of our users, Planet uses rate limiting to prevent overloading the system. If handled correctly, rate limiting errors can be a normal and useful part of working with the API.
When a rate limit has been exceeded, the Planet API responds with an HTTP 429 response code. When this occurs, we recommend implementing retry with an exponential backoff. An exponential backoff means that you wait for exponentially longer intervals between each retry of a single failing request.
The following rate limits are currently in place:
- Activation endpoint - 5 requests per second, per API key.
- Download endpoint - 5 requests per second, per API key.
- Compute operation endpoints - 5 requests per second, per API key.
- Other endpoints - 10 requests per second, per API key.
Maximum Payload Size¶
When sending a POST request to the Planet API, the server will accept a maximum payload size of 1 megabyte.
Errors¶
Whenever an error occurs, whether it be the fault of the user or an internal
system, an error object will be returned.
HTTP response codes of 4xx suggest a bad request. If you receive a 4xx response, we recommend reviewing the API reference docs for more context to help you troubleshoot. 5xx errors suggest a problem on Planet's end, so if you receive a 5xx error, please contact support.
We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.