Skip to main content

Quota API

Overview​

Planet Quota API allows you to create, estimate, and view existing quota reservations on the Planet platform (available for users of Planetary Variables).

Using feature references created in Features API you can reserve quota, estimate quota usage, or view how much your currently reserved features have consumed.

Key Concepts​

AOI Reference​

A feature reference created within the Features API as a result of uploading an Areas of Interest (AOI)

Product​

A data product you are authorized to access along with a record of your reserved quota and remaining quota

Quota Reservation​

The outcome of POSTing one or more AOI references and valid product ID to Quota API

Quota Total​

The amount of quota you can reserve

Quota Used​

The amount of quota that has already been reserved

API Mechanics​

Pagination​

The Planet Quota API paginates responses to limit the results, making them easier to work with.

The first GET request will yield the first page in a meta object next values representing the location of the next page. Following the next link will return another page of results. The prev link returns the previous set of results. The meta object also contains a count representing the number of records in your request.

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

Errors​

An ‘ error ‘ object will be returned whenever an error occurs, whether the user’s fault or an internal system.

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.

Creating an area quota reservation​

Get my products​

Area quota requests are completed within the context of a product. To create or estimate a quota reservation, you must first retrieve a valid id from my/products that displays the products currently available to your organization.

curl -X GET "https://api.planet.com/account/v1/my/products" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Estimating the cost of a quota reservation​

To estimate a quota reservation, upload your Areas of Interest (AOIs) using the Planet Features API. Use the generated feature reference as your aoi_refs value.

Use the ID and NAME values fetched from Get my products as your product_access_id and product_id.

curl -X POST "https://api.planet.com/account/v1/quota-reservations/estimate" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "aoi_refs": [ "pl:features/my/it-municipalities-5ZJNy8Z/0-mk6La40" ],
        "product_access_id": 147
    }'

Making a reservation​

Making a reservation is the same as estimating above. Retrieve one or more valid aoi_refs and product_id to complete a request like so:

info

To reserve a large list of aoi_refs, please refer to the section on bulk requests

curl -X POST "https://api.planet.com/account/v1/quota-reservations/" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "aoi_refs": [ "$AOI_REF" ],
        "product_access_id": $PRODUCT_ACCESS_ID,
        "product_id": "$PRODUCT_ID"
    }'

View your quota reservations​

To view the status of your created quota reservations, you can run:

curl -X GET "https://api.planet.com/account/v1/quota-reservations/" \
    --include \
    -H "Authorization api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

View a specific quota reservation​

To view a specific quota reservation, you can run:

curl -X GET "https://api.planet.com/account/v1/quota-reservations/100" \
    --include \
    -H "Authorization api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Bulk Requests​

Making reservations​

Follow the same instructions from above for making a reservation, and include as many aoi_refs as you need to reserve.

For the best performance, POSTing one payload containing all of your aoi_refs is recommended over chunking and making multiple requests.

!!! info "Disclaimer" There is a 10 megabyte request body limit to remember when submitting large bulk reservations.

curl -X POST "https://api.planet.com/account/v1/quota-reservations/bulk-reserve" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "aoi_refs": $AOI_REF_ARRAY,
        "product_access_id": $PRODUCT_ACCESS_ID,
        "product_id": "$PRODUCT_ID"
    }'
Last updated on