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 daily medium resolution imagery through our Open California initiative and low resolution imagery worldwide.
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 cURL
curl -u {api-key}: https://api.planet.com/data/v1/
Permissions
Depending on your account type, you may be prevented from taking certain
actions. Things that have permission restrictions will return a list of
permissions attached to the object. As an example, free accounts can only
download assets from
items located in California. In this case,
its list of permissions will include a download permission. If the asset is
not downloadable, the download permission will be absent.
If you wish, you can filter objects based on your permission level.
Links
Most Planet API responses contain a _links object that contain a list of
hyperlinks to itself and related data. You are encouraged to rely on these
links rather than constructing the links yourself.
The most common _link is _self, which is a self reference. When an API
response is paginated, _links will contain _next and _prev references.
Pagination
The Planet API paginates responses to limit the results, making them easier to
work with. 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. This process may be repeated until the _next
link is no longer returned, which indicates the last page of results.
The following _links are provided in the response to facilitate pagination:
_self- The canonical location of the current page._first- The initial page._next- The page that logically follow the current page._prev- The page that logically precedes the current page.
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.