Overview¶
Planet’s Subscriptions API is its latest data delivery API. A user can create subscriptions to continuous cloud delivery of curated imagery and metadata with a single API call. No longer will users have to worry about delivery options, selecting the correct product bundle, or extracting item id’s. This API Quickstart Guide will walk you through a subscription from creation to cloud delivery. Before getting started with the Subscriptions API see The Getting Started Guide for API key access and more information on searching Planet data. Also, read the docs for a more detailed guide to the mechanics of the Subscriptions API.
Creating a Subscription¶
To create a Subscription you must define an AOI and create a POST request to https://api.planet.com/subscriptions/v1/. The request body can include name, source, tools, and delivery blocks. Name, source and delivery are required. Name is easy. Source describes the data from which the subscription is derived. Simply put, the source catalog allows access to all of Planet's imagery archives, which take parameters of item_types, asset_types, and filters. It operates with the same search and filter capabilities of the Data API. Search filters are a powerful tool allowing a user to narrow down their search programmatically by boolean argument, metadata, location, and many more.Tool is optional and limited to clip at the moment with more raster toolkit functionality to come in the future. Delivery specifies your cloud delivery provider. Currently, cloud delivery is the only delivery option for Subscriptions. It supports GCP, AWS, and Azure cloud storage buckets. Now let’s take a look at some examples.
subscription_schema = {
name: "string",
source: {
type: "catalog",
parameters: {
filter: {},
item_types: ["string"],
asset_types: ["string"],
},
},
*tools: [
{
type: "clip"
parameters: {
aoi: {},
},
},
],
delivery: {
type: "cloud_storage_provider",
parameters: {
"parameter1-name": "p1-value",
"parameter2-name": "p2-value"
},
},
}
Defining AOI's with GeoJSON¶
Before making a request to Subscriptions. We must first define an area of interest (AOI). AOI is how we define a selected geographic area of data. Planet`s APIs accept AOI’s in GeoJSON format. Users can clip an area by geometry utilizing Planet Explorer, and the geojson will be generated for the user. An alternative is using geojson.io. For this example, I used Planet Explorer to define the AOI of a vineyard in California. Below is the GeoJSON output from Planet Explorer.
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-121.096221,
36.183758
],
[
-121.086524,
36.183758
],
[
-121.086524,
36.187311
],
[
-121.096221,
36.187311
],
[
-121.096221,
36.183758
]
]
]
}
}
]
}
Sending a Request¶
Now create a simple request to send to the Subscriptions API!
request = {
# Name Block
"name": "basic_subscription",
# Source Block
"source": {
"type": "catalog",
"parameters": {
"item_types": [
"PSScene"
],
"asset_types": [
"analytic"
],
#There's no limit to the types of searches you can create with the filter functionality.
"filter": {
"type": "AndFilter",
"config": [
{
"type": "DateRangeFilter",
"field_name": "published",
"config": {
"gt":"2021-06-01T00:00:00Z",
"lte":"2021-09-01T00:00:00Z"
}
},
{
# Here we pass in our geoJSON from Explorer. The geometry filter accepts any valid GeoJSON object.
# It was cleaned up to make our request more pretty.
"type": "GeometryFilter",
"field_name": "geometry",
"config": {
"type": "Polygon",
"coordinates": [
[
[-121.096221,36.183758],
[-121.086524,36.183758],
[-121.086524,36.187311],
[-121.096221,36.187311],
[-121.096221,36.183758]
]
]
}
},
{
"type": "RangeFilter",
"field_name": "visible_percent",
"config": {
"gte": 50
}
}
]
}
}
},
#Delivery
"delivery": {
"type": "google_cloud_storage",
"parameters": {
"bucket": "subscriptions-practice",
"credentials": "nunya"
}
}
}
More on Delivery¶
Let's use a GCP storage bucket and walk through the steps to delivery of our vineyard data.
GCP Buckets¶
For GCP delivery you will need a GCS account and project with write and delete permissions. You then need to create a bucket. We named our bucket subscriptions-practice in this example. You could additionaly add folders to your bucket and add the path prefix parameter for delivery to that path.
Creating and Accessing Credentials¶
To create credentials in GCP. You will need to create a service account for your desired project and create keys for it. For more detailed instructions click me. This will allow you to download a JSON file with your credentials. You will only be allowed to download it once, so do not lose it. You must now encode your credentials as a base64 string. Use the following command:
cat creds.json | base64 | tr -d '\n'
Paste the encoded json as a string for the credentials parameter into the example request. Now we can send our subscription!
The Response¶
The POST request should yield a 200 response, which means success! You have created and delivered a subscription. The returned response body is included below. An order id, status, and endpoint for the subscription is created among other details. You can modify your subscription with the id.
{
"_links": {
"_self": "https://api.planet.com/subscriptions/v1/4ca9dccc-4204-49ae-9b29-cb900862acc1"
},
"id": "4ca9dccc-4204-49ae-9b29-cb900862acc1",
"status": "preparing",
"name": "basic_subscription",
"source": {
"type": "catalog",
"parameters": {
"asset_types": ["analytic"],
"filter": {
"config": [
{
"config": {
"gt": "2021-06-01T00:00:00Z",
"lte": "2021-09-01T00:00:00Z",
},
"field_name": "published",
"type": "DateRangeFilter",
},
{
"config": {
"coordinates": [
[
[-121.096221, 36.183758],
[-121.086524, 36.183758],
[-121.086524, 36.187311],
[-121.096221, 36.187311],
[-121.096221, 36.183758],
]
],
"type": "Polygon",
},
"field_name": "geometry",
"type": "GeometryFilter",
},
{
"config": {"gte": 50},
"field_name": "visible_percent",
"type": "RangeFilter",
},
],
"type": "AndFilter",
},
"item_types": ["PSScene"],
},
},
"delivery": {
"type": "google_cloud_storage",
"parameters": {"bucket": "subscriptions-practice", "credentials": "<REDACTED>"},
},
"created": "2021-08-20T15:36:14.53073Z",
"updated": "2021-08-20T15:36:14.53073Z",
}
Accessing and Modifying Subscriptions¶
# Create a Subscription
POST https://api.planet.com/subscriptions/v1/
# Edit a Subscription
PUT https://api.planet.com/subscriptions/v1/<subscription_id>
# Cancel a Subscription
POST https://api.planet.com/subscriptions/v1/<subscription_id>/cancel
# Filter Subscriptions by Status
GET https://api.planet.com/subscriptions/v1?status=running&status=completed
# Return Subscription Results
GET https://api.planet.com/subscriptions/v1/<subscription_id>/results
Questions or comments about this guide? Join the conversation at Planet Community or contact developers@planet.com.
Rate this guide: