Log inSuggest an edit

API Mechanics

Table of Contents

  1. Authentication
  2. Permissions
  3. Links
  4. Pagination
  5. Errors
  6. HTTP Redirects
  7. Rate Limits
  8. Maximum Payload Size

All Planet APIs implement a shared set of API mechanics. Each of these mechanics are documented herein.

1. Authentication

The protected API endpoints require that a client provide an API key along with a request. This API key can be retrieved from the user's Planet Account.

This API key should be provided with requests using Basic HTTP Authentication. Setting the username field to the API key and leaving the password field blank will result in an authorization HTTP header attached to a request that looks like this:

Authorization: Basic <base64-encoded-username-and-password>

For example, a curl request to the Data API might be structured like this, with the Planet API key stored as environment variable $PL_API_KEY:

curl -u $PL_API_KEY: https://api.planet.com/data/v1 

2. Permissions

A client may be prevented from taking certain actions on objects in the system. In the case that these restrictions exist, Planet APIs do two things:

  • communicate what a given client may do via a list of "permissions" attached to that object
  • allow the client to filter collections to objects with a specific permission

For example, a client may only be able to download assets from certain items. In the case that an asset is downloadable, its list of permissions will include a "download permission" entry. If the asset is not downloadable, the download permission will be absent.

Planet APIs embed a container of hyperlinks in HTTP responses that communicate to the client how to access related data. For example, an item object provides a link to its collection of assets, a search object provides a link to its collection of results, and a page of items provides a link to the subsequent page of items. Clients are encouraged to rely on these links rather than constructing links themselves.

The most common link is _self; it indicates where a client may retrieve the object to which the link is attached. For example, each item in a page will communicate the unique URL where it may be reached directly.

4. Pagination

Clients of Planet APIs consume collections of objects (e.g. items or searches) via a process called "pagination". This process exposes only a subset of the collection to the client in a single response, called a "page". A client must make a series of requests to construct an entire view of a collection.

The first GET request against a collection will yield the first page along with a URI representing the location of the subsequent page. A client makes a second GET request against this URI, which will return another page of results. This process should be repeated until a URI is no longer returned, indicating the API has communicated all objects in the collection.

Several links exist to facilitate pagination:

  • '_self': the canonical location of the current page of objects
  • '_next': the page of objects that logically follow the current page
  • '_prev': the page of objects that logically precedes the current page
  • '_first': the initial page of objects

5. Errors

Whenever a fault occurs, whether it be the fault of the user or an internal system, an Error object may be returned. The Error object contains a set of error messages grouped by scope, where scope is global (i.e."general") or specific to a field contained in the request.

For example, the following invalid request...

GET /data/v1/item-types/?platypus=present

...could result in an error like this:

{
  "field": {
    "general": [
      {
        "message": "The requested item type does not exist."
      }
    ]
  },
}

In this case, the error object indicates a general request failure and the field-level failure with a Response Code of 404.

6. HTTP Redirects

HTTP redirects (the 3XX family of HTTP responses) are commonly used across the Planet APIs. All redirects must be followed by clients, and a failure to do so will result in unexpected behavior.

7. Rate Limits

When requests are made too rapidly, they may get throttled with a 429 response:

HTTP/1.1 429
Server: nginx/1.8.1
Date: Mon, 18 Apr 2016 22:34:19 GMT
Content-Length: 0
Connection: keep-alive

Robust clients should be prepared for 429 responses from any endpoint and to retry after a backoff period.

There are a few rate-limits classes currently in place:

  1. For most endpoints, the rate limit is 10 requests per second, per API key.

  2. For activation endpoints, the rate limit is 5 requests per second, per API key.

  3. For operation endpoints at /compute/ops, the rate limit is 5 requests per second, per API key.

  4. For download endpoints, the rate limit is 15 requests per second, per API key.

8. Maximum Payload Size

When sending a POST request to Planet APIs, the server will accept a maximum payload size of 1 megabyte.