Feature References

last updated: July 17, 2024

Feature references

Feature References are unique identifiers to specific Features in your Feature Collection, which can be used as a reference to the Feature geometry in supported Planet APIs (listed below).

Referring to a collection: pl:features/[dataset]/[collection-id]

Referring to a feature (latest version) either pl:features/[dataset]/[collection-id]/[feature-id] pl:features/[dataset]/[collection-id]/[feature-id]#latest

Referring to a feature (specific version): pl:features/[dataset]/[collection-id]/[feature-id]#[version-id]

Get a feature reference id

The Feature Reference ID can be accessed for an individual item in the properties of the particular feature with the key pl:ref The Reference ID is helpful for referencing your Features when making requests to Planet’s delivery APIs. See Retrieve a feature documentation for an example on how to make such request.

Use the Reference ID when making requests to Planet’s Subscriptions, Orders and Data APIs so that you don’t have to pass in the GeoJson each time. See below for examples on how to use them with each of these APIs.

Using feature references in Planet's delivery APIs

Subscriptions API

An AOI is required to request data from the Subscriptions API. You can now use your saved AOI Feature references in your Subscription API requests.

Example:

POST https://api.planet.com/subscriptions/v1/
{
    "name": "Example Subscription",
    "source": {
        "type": "catalog",
        "parameters": {
            "geometry": {
                "content": "pl:features/my/[collection-id]/[feature-id]",
                "type": "ref"
            },
            "time_range_type": "acquired",
            "start_time": "2023-03-01T00:00:00Z",
            "end_time": "2023-04-01T00:00:00Z",
            "item_types": [
                "PSScene"
            ],
            "asset_types": [
                "ortho_analytic_4b"
            ]
        }
    },
    "delivery": {}
}

Tip

For more information about the Subscriptions API visit the documentation here.

Orders API

An AOI can be used in an Orders API request to clip data to your area of interest. You can now use your saved AOI Feature references in your Orders API with clip requests.

Example:

POST https://api.planet.com/compute/ops/orders/v2/
{
    "name": "just clip",
    "source_type": "scenes",
    "products": [
        {
            "item_ids": [
                "20170614_113217_3163208_RapidEye-5"
            ],
            "item_type": "REOrthoTile",
            "product_bundle": "analytic"
        }
    ],
    "tools": [
        {
            "clip": {
                "aoi": {
                    "content": "pl:features/my/[collection-id]/[feature-id]",
                    "type": "ref"
                }
            }
        }
    ]
}

Tip

For more information about the Orders API visit the documentation here.

Data API

An AOI can be used in your Data API searches to filter results to only matching data within your area of interest. You can now use your saved AOI Feature references in your Data API requests.

Example:

POST https://api.planet.com/data/v1/quick-search 
{
  "item_type": "<item_type>",
  "asset_type": [
    "<asset_type>"
  ],
  "geometry": {
    "content": "pl:features/my/[collection]/[feature-id]",
    "type": "ref"
  },
  "filter": …
}

Tip

For more information about the Orders API visit the documentation here.