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": {}
}

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"
                }
            }
        }
    ]
}

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": …
}