Reports API

The Reports API allows Organization Administrators to download usage reports systematically for internal processing and analysis. Reports downloaded from the API are the exact same reports available from the user interface accessible from your Account at www.planet.com/account.

Usage Reports Overview

The Planet usage system generates reports every day; each report covers the activity for the previous 24 hours. Each day at GMT 23:59:59 Planet’s system starts generating the daily report. When reports are completed for all customers they are made accessible via both your Account and the Reports API at the same time. Reports are generated according to the assigned quota style. Each PlanetScope plan has an assigned quota style: Starter, Preferred, Premium, or Area Under Management.

note

No quota style selection is required in the API. If you have questions please reach out to your Customer Success Manager or support@planet.com.

PlanetScope usage reports have two different formats:

1. Standard usage reports sum all of the usage charged to the plan by date, item (for example: PSScene, SkySatCollect), and by user (who downloaded the image).
2. Detailed usage reports list out every image and all metadata (e.g. xml files) downloaded.

Key Features

List Usage Reports

The Reports API allows customers and partners to systematically list all of the reports that are available for each plan. Planetscope reports are available in Usage Report and Detailed Usage report versions. Usage reports are produced for each day covering 00:00:00 to 23:59:59 GMT.

Download Usage Reports

The Reports API also allows customers and partners to download the selected usage reports for a plan.

note

You must be an Organization Administrator to list and download usage reports for a plan.

Download Usage Reports for Sub-Orgs

The Reports API allows administrators to download usage reports for their organizations. You can select between a detailed report or a summary. The API returns a link for downloading the usage report for the time (within the last 90 days) you’ve specified.

Mechanics

Authentication

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

Once you sign 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 organization ID on the Organizations tab in my account. If you have sub-organizations, you can also find the ID number for those organizations on the same page.

note

You must be an Organization Administrator to list and download usage reports for a plan.

Example: Listing Reports

In the following example, we're using a sample API key "12345" to list available reports for an Organization with ID "0000":

CURL

curl -u $PL_API_KEY: https://api.planet.com/reports/v1/?org_id=31743

Python SDK

# NOTE: the reports API is not currently supported in the planet SDK.
# The following example uses requests sessions.
import os

import pytest
import requests

PL_API_KEY = os.getenv("PL_API_KEY")
BASE_URL = "https://api.planet.com/reports/v1/"


def list_reports():
    session = requests.Session()
    session.auth = (PL_API_KEY, "")
    res = session.get(BASE_URL, params={"org_id": 31743})
    print(res.status_code)
    return res.json()

Links

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 follows the current page
• _prev - The page that logically precedes the current page

Errors

Refer to the errors overview for information on conventional HTTP response codes.

In addition to these, the Reports API returns the following common errors:

Status Code	Error Message	Common Causes & Solutions
400	{"reason":" Invalid Type"}	Ensure that all request parameters have valid values.
403	{"reason":" Forbidden"}	You must be an Organization Administrator to list and download usage reports for a plan.