|
| 1 | +--- |
| 2 | +title: Adding STAC Items to Collections in Microsoft Planetary Computer Pro |
| 3 | +description: Learn how to add and use STAC Items in Microsoft Planetary Computer Pro GeoCatalog and Python. |
| 4 | +author: aloverro |
| 5 | +ms.author: adamloverro |
| 6 | +ms.service: azure |
| 7 | +ms.topic: quickstart |
| 8 | +ms.date: 04/09/2025 |
| 9 | + |
| 10 | +#customer intent: As a user of geospatial data, I want to ingest STAC items so that I can efficiently query and access my geospatial data. |
| 11 | +--- |
| 12 | + |
| 13 | +# Quickstart: Ingest a Single STAC Item into a Collection in a Microsoft Planetary Computer Pro GeoCatalog |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +## Prerequisites |
| 18 | + |
| 19 | +Before starting this quickstart, you should first complete the quickstart to [Create a STAC collection with Microsoft Planetary Computer Pro GeoCatalog](./create-stac-collection.md), or have a GeoCatalog with a STAC collection for the items you intend to ingest. |
| 20 | + |
| 21 | +**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: |
| 22 | + |
| 23 | +```python |
| 24 | +# Put the URL to your Microsoft Planetary Computer Pro GeoCatalog Explorer (not including '/api') here. |
| 25 | +# Make sure there's no trailing '/' |
| 26 | +geocatalog_url = "<your-geocatalog-url>" |
| 27 | +# collection_id is "spatio-quickstart" if you're following the collection quickstart |
| 28 | +collection_id = "<your-collection-id>" |
| 29 | +``` |
| 30 | + |
| 31 | +## Create item metadata |
| 32 | + |
| 33 | +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. |
| 34 | + |
| 35 | +>[!TIP] |
| 36 | +> Don't have STAC Items for your data? To accelerate the creation of STAC Items, we have a [detailed tutorial](./create-stac-item.md) and also have an open source tool called [STAC Forge](https://github.com/Azure/microsoft-planetary-computer-pro/tree/main/tools/stacforge-functions). |
| 37 | +
|
| 38 | +For this quick start, you use STAC Items and assets from the open Planetary Computer's [10 m Annual Land Use Land Cover](https://planetarycomputer.microsoft.com/dataset/io-lulc-annual-v02) collection. |
| 39 | + |
| 40 | +```python |
| 41 | +import requests |
| 42 | + |
| 43 | +response = requests.get( |
| 44 | + "https://planetarycomputer.microsoft.com/api/stac/v1/search", |
| 45 | + params={"collections": "io-lulc-annual-v02", "ids": "23M-2023,23L-2023,24M-2023,24L-2023"}, |
| 46 | +) |
| 47 | + |
| 48 | +item_collection = response.json() |
| 49 | +``` |
| 50 | + |
| 51 | +Use the open Planetary Computer's [SAS API](https://planetarycomputer.microsoft.com/docs/concepts/sas/) to get short-lived SAS tokens for the assets. |
| 52 | + |
| 53 | +```python |
| 54 | +sas_token = requests.get( |
| 55 | + "https://planetarycomputer.microsoft.com/api/sas/v1/token/io-lulc-annual-v02" |
| 56 | +).json()["token"] |
| 57 | + |
| 58 | +for item in item_collection["features"]: |
| 59 | + for asset in item["assets"].values(): |
| 60 | + asset["href"] = "?".join([asset["href"], sas_token]) |
| 61 | +``` |
| 62 | + |
| 63 | +This SAS Token is required to allow your GeoCatalog to copy the data from the open Planetary Computer. See [Ingestion sources](./ingestion-source.md) for more on how Planetary Computer Pro accesses data. |
| 64 | + |
| 65 | +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. |
| 66 | + |
| 67 | +```python |
| 68 | +for item in item_collection["features"]: |
| 69 | + item["collection"] = collection_id |
| 70 | +``` |
| 71 | + |
| 72 | +## Get an access token |
| 73 | + |
| 74 | +Planetary Computer Pro requires an access token to authenticate requests via [Microsoft Entra](/entra/fundamentals/whatis). Use the [Azure-identity](/python/api/overview/azure/identity-readme) client library for Python to get a token. |
| 75 | + |
| 76 | +```python |
| 77 | +import azure.identity |
| 78 | + |
| 79 | +credential = azure.identity.AzureCliCredential() |
| 80 | +token = credential.get_token("https://geocatalog.spatio.azure.com") |
| 81 | +headers = { |
| 82 | + "Authorization": f"Bearer {token.token}" |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +## Add items to a collection |
| 87 | + |
| 88 | +Items can be added to a collection by posting an `Item` or `ItemCollection` object to the `/stac/collections/{collection_id}/items` endpoint. |
| 89 | + |
| 90 | +```python |
| 91 | +response = requests.post( |
| 92 | + f"{geocatalog_url}/stac/collections/{collection_id}/items?api-version=2025-04-30-preview", |
| 93 | + headers=headers, |
| 94 | + json=item_collection |
| 95 | +) |
| 96 | +print(response.status_code) |
| 97 | +``` |
| 98 | + |
| 99 | +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())`. |
| 100 | + |
| 101 | +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. |
| 102 | + |
| 103 | +```python |
| 104 | +import time |
| 105 | +import datetime |
| 106 | + |
| 107 | +location = response.headers["location"] |
| 108 | + |
| 109 | +while True: |
| 110 | + response = requests.get(location, headers={"Authorization": f"Bearer {token.token}"}) |
| 111 | + status = response.json()["status"] |
| 112 | + print(datetime.datetime.now().isoformat(), status) |
| 113 | + if status not in {"Pending", "Running"}: |
| 114 | + break |
| 115 | + time.sleep(5) |
| 116 | +``` |
| 117 | + |
| 118 | +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. |
| 119 | + |
| 120 | +```python |
| 121 | +items_response = requests.get( |
| 122 | + f"{geocatalog_url}/stac/collections/{collection_id}/items", |
| 123 | + headers={"Authorization": f"Bearer {token.token}"}, |
| 124 | + params={"api-version": "2025-04-30-preview"}, |
| 125 | +) |
| 126 | +items_ingested = items_response.json() |
| 127 | +print(f"Found {len(items_ingested['features'])} items") |
| 128 | +``` |
| 129 | + |
| 130 | +Or search: |
| 131 | + |
| 132 | +```python |
| 133 | +search_response = requests.get( |
| 134 | + f"{geocatalog_url}/stac/search", |
| 135 | + headers={"Authorization": f"Bearer {token.token}"}, |
| 136 | + params={"api-version": "2025-04-30-preview", "collection": collection_id}, |
| 137 | +) |
| 138 | +#print(search_response.json()) |
| 139 | +``` |
| 140 | + |
| 141 | +You can view the items by visiting your [Data Explorer](./use-explorer.md) once the STAC Collection is [configured for visualization](./collection-configuration-concept.md). |
| 142 | + |
| 143 | +## Delete Items from a Collection |
| 144 | + |
| 145 | +Items can be deleted from a collection with a `DELETE` request to the item detail endpoint. |
| 146 | + |
| 147 | +```python |
| 148 | +item_id = item_collection["features"][0]["id"] |
| 149 | +delete = requests.delete( |
| 150 | + f"{geocatalog_url}/stac/collections/{collection_id}/items/{item_id}", |
| 151 | + headers=headers, |
| 152 | + params={"api-version": "2025-04-30-preview"}, |
| 153 | +) |
| 154 | +print(delete.status_code) |
| 155 | +``` |
| 156 | + |
| 157 | +## Clean up resources |
| 158 | + |
| 159 | +See [Create a STAC collection with Microsoft Planetary Computer Pro GeoCatalog](./create-stac-collection.md) for steps to |
| 160 | +delete an entire Collection and all items and assets underneath it. |
| 161 | + |
| 162 | +## Next steps |
| 163 | + |
| 164 | +Now that you added a few items, you should configure the data for visualization. |
| 165 | + |
| 166 | +> [!div class="nextstepaction"] |
| 167 | +> [Collection configuration in Microsoft Planetary Computer Pro](./collection-configuration-concept.md) |
| 168 | +
|
| 169 | +## Related Items |
| 170 | + |
| 171 | +- [Ingest data into GeoCatalog with the Bulk Ingestion API](./bulk-ingestion-api.md) |
| 172 | +- [Quickstart: Ingest data using the Microsoft Planetary Computer Pro web interface](./ingest-via-web-interface.md) |
| 173 | +- [Ingest data into Microsoft Planetary Computer Pro](./ingestion-overview.md) |
| 174 | +- [Ingestion source for Microsoft Planetary Computer Pro](./ingestion-source.md) |
0 commit comments