API Mechanics

last updated: November 10, 2021

Authentication

The Reports API uses Basic HTTP Authentication and requires that you have a Planet API key.

Once you're signed up, you can find your API key on the My Settings page in my account. Authenticate by setting username to your API key.

You can find your organizations ID in your Organization ID on the Organizations tab in my account. If you have sub organizations you may also find the ID number for those organizations on the same page.

Example: Listing Reports

Here, we're using a (fictional) API key "12345" to list available reports for an (again, fictional) Organization with ID "0000":

With cURL

  curl -u 12345: https://api.planet.com/reports/v0/?org_id=0000

With Python

import requests

PLANET_API_KEY = 12345

BASE_URL = "https://api.planet.com/reports/v0"

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, params={"org_id": 0000})
# make a GET request to the Reports API to list available reports

print(res.text)
# print response body

Permissions

Users must be an organization administrator in order to list and download usage reports for a plan.

Most Reports 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 Reports 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.