Quickstart: Ingest a Single STAC Item into a Collection in a Microsoft Planetary Computer Pro GeoCatalog

2025-06-24

In this quickstart, you ingest SpatioTemporal Asset Catalog (STAC) items to a collection in Microsoft Planetary Computer Pro GeoCatalog using the single item ingestion API. STAC items are the fundamental building block of STAC that contain properties for querying and links to the data assets.

Prerequisites

Before starting this quickstart, you should first complete the quickstart to Create a STAC collection with Microsoft Planetary Computer Pro GeoCatalog, or have a GeoCatalog with a STAC collection for the items you intend to ingest.

Skip the following code snippet if you created the STAC collection within the current terminal/script, otherwise you must set the geocatalog_url and collection_id using the following Python code:

# Put the URL to your Microsoft Planetary Computer Pro GeoCatalog Explorer (not including '/api') here.
# Make sure there's no trailing '/'
geocatalog_url = "<your-geocatalog-url>"
# collection_id is "spatio-quickstart" if you're following the collection quickstart
collection_id = "<your-collection-id>"

Create item metadata

The STAC item metadata is unique to the assets you're cataloging. It contains all the information required to catalog the data, along with pointers to where the data is stored.

Tip

Don't have STAC Items for your data? To accelerate the creation of STAC Items, we have a detailed tutorial and also have an open source tool called STAC Forge.

For this quick start, you use STAC Items and assets from the open Planetary Computer's 10 m Annual Land Use Land Cover collection.

import requests

response = requests.get(
    "https://planetarycomputer.microsoft.com/api/stac/v1/search",
    params={"collections": "io-lulc-annual-v02", "ids": "23M-2023,23L-2023,24M-2023,24L-2023"},
)

item_collection = response.json()

Use the open Planetary Computer's SAS API to get short-lived SAS tokens for the assets.

sas_token = requests.get(
    "https://planetarycomputer.microsoft.com/api/sas/v1/token/io-lulc-annual-v02"
).json()["token"]

for item in item_collection["features"]:
    for asset in item["assets"].values():
        asset["href"] = "?".join([asset["href"], sas_token])

This SAS Token is required to allow your GeoCatalog to copy the data from the open Planetary Computer. See Ingestion sources for more on how Planetary Computer Pro accesses data.

STAC requires that the collection property on STAC items match the collection they're in. If necessary, update the items to match the collection ID you're using.

for item in item_collection["features"]:
    item["collection"] = collection_id

Get an access token

Planetary Computer Pro requires an access token to authenticate requests via Microsoft Entra. Use the Azure-identity client library for Python to get a token.

import azure.identity

credential = azure.identity.AzureCliCredential()
token = credential.get_token("https://geocatalog.spatio.azure.com")
headers = {
    "Authorization": f"Bearer {token.token}"
}

Add items to a collection

Items can be added to a collection by posting an Item or ItemCollection object to the /stac/collections/{collection_id}/items endpoint.

response = requests.post(
    f"{geocatalog_url}/stac/collections/{collection_id}/items?api-version=2025-04-30-preview",
    headers=headers,
    json=item_collection
)
print(response.status_code)

A 202 status code indicates that your items were accepted for ingestion. Check the response JSON if you get a 40x status code, for example, print(response.json()).

Planetary Computer Pro asynchronously ingests the items into your GeoCatalog. The location header includes a URL that you can poll to monitor the status of the ingestion workflow.

import time
import datetime

location = response.headers["location"]

while True:
    response = requests.get(location, headers={"Authorization": f"Bearer {token.token}"})
    status = response.json()["status"]
    print(datetime.datetime.now().isoformat(), status)
    if status not in {"Pending", "Running"}:
        break
    time.sleep(5)

Once the items are ingested, use the `/stac/collections/{collection_id}/items` or `/stac/search` endpoints to get a paginated list of items, including your newly ingested items. If the ingestion fails or you encounter errors, consult the [troubleshooting guide](./troubleshooting-ingestion.md) and the [list of error codes](./error-codes-ingestion.md).

```python
items_response = requests.get(
    f"{geocatalog_url}/stac/collections/{collection_id}/items",
    headers={"Authorization": f"Bearer {token.token}"},
    params={"api-version": "2025-04-30-preview"},
)
items_ingested = items_response.json()
print(f"Found {len(items_ingested['features'])} items")

Or search:

search_response = requests.get(
    f"{geocatalog_url}/stac/search",
    headers={"Authorization": f"Bearer {token.token}"},
    params={"api-version": "2025-04-30-preview", "collection": collection_id},
)
#print(search_response.json())

You can view the items by visiting your Data Explorer once the STAC Collection is configured for visualization.

Delete Items from a Collection

Items can be deleted from a collection with a DELETE request to the item detail endpoint.

item_id = item_collection["features"][0]["id"]
delete = requests.delete(
    f"{geocatalog_url}/stac/collections/{collection_id}/items/{item_id}",
    headers=headers,
    params={"api-version": "2025-04-30-preview"},
)
print(delete.status_code)

Clean up resources

See Create a STAC collection with Microsoft Planetary Computer Pro GeoCatalog for steps to delete an entire Collection and all items and assets underneath it.

Next steps

Now that you added a few items, you should configure the data for visualization.

Collection configuration in Microsoft Planetary Computer Pro

Share via