API Mechanics

last updated: February 05, 2024

Authentication

The Features API requires providing your Planet API key through Basic HTTP Authentication. You can find your API key in your account settings.

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/features/v0/ogc"

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 Features API

print(res.status_code)
# test response

print(res.text)
# print response body

Authentication Via cURL

curl -u {api-key}: https://api.planet.com/features/v0/ogc

Pagination

The Planet Features API paginates responses to limit the results, making them easier to work with. All top-level API resources have support for bulk fetches through their respective GET requests.

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.

These API methods share a common structure and accept, at a minimum, the following parameters: limit, and offset. Features API GET methods use offset-based pagination through the offset parameter.

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.