@azure/planetarycomputer

v1.0.0-beta.1

Published

9 days ago

A generated SDK for PlanetaryComputerProClient.

0High
0Medium
0Low

azure-sdk

microsoft1es

microsoft-oss-releases

node azure cloud typescript browser isomorphic

Azure Planetary Computer Pro client library for JavaScript

The Microsoft Planetary Computer Pro is a geospatial data management service built on Azure's hyperscale infrastructure. The GeoCatalog is an Azure resource that provides foundational capabilities to ingest, manage, search, and distribute geospatial datasets using the SpatioTemporal Asset Catalog (STAC) open specification.

Key capabilities

STAC Collection Management: Create, read, update, and delete STAC collections and items to organize your geospatial datasets
Collection Configuration: Configure render options, mosaics, tile settings, and queryables to optimize query performance and visualization
Data Visualization: Generate map tiles (XYZ, TileJSON, WMTS), preview images, crop by GeoJSON or bounding box, extract point values, and compute statistics
Mosaic Operations: Register STAC search-based mosaics for pixel-wise data query and retrieval, generate tiles from multiple items, and access TileJSON and WMTS capabilities
Map Legends: Retrieve class map legends (categorical) and interval legends (continuous) as JSON or PNG images with predefined color maps
Data Ingestion: Set up ingestion sources (Managed Identity or SAS token), define ingestions from STAC catalogs, and create and monitor ingestion runs
STAC API Operations: Full CRUD operations on items, search with spatial/temporal filters and sorting, retrieve queryable properties, and check API conformance
Secure Access: Generate SAS tokens with configurable duration for collections, sign asset HREFs for secure downloads, and revoke tokens—all secured via Microsoft Entra ID

Key links:

Getting started

Currently supported environments

LTS versions of Node.js
Latest versions of Safari, Chrome, Edge and Firefox.

See our support policy for more details.

Prerequisites

An Azure subscription
A Microsoft Planetary Computer Pro GeoCatalog resource. You can create the resource via the Azure Portal, the Azure PowerShell, or the Azure CLI.

The GeoCatalog endpoint (catalogUri) can be found in the Azure Portal on your GeoCatalog resource's overview page.

Install the `@azure/planetarycomputer` package

Install the Azure Planetary Computer Pro client library for JavaScript with npm:

npm install @azure/planetarycomputer

Create and authenticate a `PlanetaryComputerProClient`

There are several ways to authenticate with the Microsoft Planetary Computer Pro service and the recommended way is to use Microsoft Entra ID for secure, keyless authentication via the Azure Identity library. To get started:

Install the Azure Identity package:

npm install @azure/identity

Register a new Microsoft Entra ID application and grant access to Microsoft Planetary Computer Pro by assigning the suitable role to your service principal.
Set the values of the client ID, tenant ID, and client secret of the Microsoft Entra ID application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.
Create the client using DefaultAzureCredential:

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>"; // e.g., "https://your-geocatalog.geocatalogs.azure.com"
const client = new PlanetaryComputerProClient(catalogUri, credential);

Key concepts

PlanetaryComputerProClient

PlanetaryComputerProClient is the primary interface for developers using the Microsoft Planetary Computer Pro client library. The client provides access to several operation groups:

STAC Operations (`client.stac`)

Collection Management: Create, update, list, and delete STAC collections to organize your geospatial datasets
Item Management: Create, read, update, and delete individual STAC items within collections
Search API: Search for items using spatial and temporal filters, sorting, and queryable properties
Configuration: Manage render options, mosaics, tile settings, queryables, and partition types
API Conformance: Retrieve STAC API conformance classes and landing page information

Data Operations (`client.data`)

Tile Generation: Generate map tiles (XYZ, TileJSON, WMTS) from collections, items, and mosaics
Data Visualization: Create preview images, crop by GeoJSON or bounding box, extract point values, and compute statistics
Mosaic Operations: Register STAC search-based mosaics and retrieve mosaic tiles, TileJSON, and WMTS capabilities
Map Legends: Retrieve class map and interval legends as JSON or PNG images
Asset Metadata: Retrieve tile matrix sets and asset metadata for collections and items

Ingestion Operations (`client.ingestion`)

Ingestion Sources: Set up ingestion sources using Managed Identity or SAS token authentication
Ingestion Definitions: Define automated STAC catalog ingestion from public and private data sources
Ingestion Runs: Create and monitor ingestion runs with detailed operation tracking

Shared Access Signature Operations (`client.sharedAccessSignature`)

Token Generation: Generate SAS tokens with configurable duration for collections
Asset Signing: Sign asset HREFs for secure downloads of managed storage assets
Token Revocation: Revoke tokens when needed to control access

GeoCatalog

A GeoCatalog is the top-level Azure resource that stores and organizes your geospatial data. It provides:

Zone-redundant, managed storage for raster and data cube formats
Built-in cloud-optimization for supported data types
A managed STAC API for all stored data
Integration with Azure's security and identity management through Microsoft Entra ID

STAC (SpatioTemporal Asset Catalog)

STAC is an open specification for organizing and describing geospatial data. Microsoft Planetary Computer Pro uses STAC to provide:

Collections: Logical groupings of related geospatial datasets
Items: Individual assets (e.g., satellite imagery, rasters) with metadata
Assets: The actual data files referenced by STAC Items

Examples

This section provides code snippets covering common GeoCatalog workflows. For complete working examples, see the samples directory.

List STAC Collections

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const collections = await client.stac.getCollections();
console.log(`Found ${collections.collections.length} collections`);
for (const collection of collections.collections) {
  console.log(`- ${collection.id}: ${collection.description}`);
}

Search for STAC Items

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const searchResult = await client.stac.search({
  collections: ["naip"],
  datetime: "2021-01-01T00:00:00Z/2022-12-31T23:59:59Z",
  limit: 10,
});
console.log(`Found ${searchResult.features.length} items`);
for (const item of searchResult.features) {
  console.log(`Item ID: ${item.id}, Collection: ${item.collection}`);
}

Get STAC Item Details

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const item = await client.stac.getItem("naip", "ga_m_3308421_se_16_060_20211114");
console.log(`Item ID: ${item.id}`);
console.log(`Assets: ${Object.keys(item.assets)}`);

Create a STAC Collection

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const poller = await client.stac.createCollection({
  id: "my-collection",
  type: "Collection",
  stacVersion: "1.0.0",
  description: "A collection of geospatial data",
  license: "proprietary",
  extent: {
    spatial: { boundingBox: [[-180, -90, 180, 90]] },
    temporal: { interval: [[null, null]] },
  },
  links: [],
});
await poller.pollUntilDone();
console.log("Collection created");

Register and Render Mosaic Tiles

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const registration = await client.data.registerMosaicsSearch({
  collections: ["naip"],
  filterLang: "cql2-json" as const,
  filter: { op: "=", args: [{ property: "naip:year" }, "2021"] },
});
console.log(`Search ID: ${registration.searchId}`);
const tileJson = await client.data.getSearchTileJson(registration.searchId, {
  assets: ["image"],
});
console.log(`Tile URLs: ${tileJson.tiles}`);

Extract Point Values

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const pointData = await client.data.getItemPoint(
  "naip",
  "ga_m_3308421_se_16_060_20211114",
  -84.41,
  33.65,
  { assets: ["image"] },
);
console.log(`Coordinates: ${pointData.coordinates}`);
console.log(`Values: ${pointData.values}`);

Generate Map Tiles

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const tileResponse = await client.data.getTile(
  "naip",
  "ga_m_3308421_se_16_060_20211114",
  "WebMercatorQuad",
  14,
  4322,
  6463,
  { assets: ["image"] },
);
console.log(`Tile size: ${tileResponse.length} bytes`);

Set Up Ingestion Source

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const source = await client.ingestion.createSource({
  id: "my-storage-source",
  kind: "BlobManagedIdentity",
  connectionInfo: {
    containerUri: "https://mystorage.blob.core.windows.net/geospatial-data",
    objectId: "00000000-0000-0000-0000-000000000000",
  },
});
console.log(`Created source: ${source.id}`);

Data Ingestion Management

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const ingestion = await client.ingestion.create("my-collection", {
  importType: "StaticCatalog",
  displayName: "My data ingestion",
  sourceCatalogUrl: "https://example.com/catalog.json",
  keepOriginalAssets: true,
  skipExistingItems: true,
});
console.log(`Created ingestion: ${ingestion.id}`);

Get a SAS Token

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const token = await client.sharedAccessSignature.getToken("naip");
console.log(`Token expires at: ${token.expiresOn}`);
// Sign an asset URL for secure download
const signed = await client.sharedAccessSignature.getUrl(
  "https://storage.blob.core.windows.net/container/asset.tif",
);
console.log(`Signed URL: ${signed.href}`);

Troubleshooting

General

Planetary Computer Pro client library will raise exceptions defined in Azure Core.

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";
import { RestError } from "@azure/core-rest-pipeline";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
try {
  await client.stac.getCollection("non-existent-collection");
} catch (e) {
  if (e instanceof RestError) {
    console.log(`Status code: ${e.statusCode}`);
    console.log(`Message: ${e.message}`);
  }
}

Logging

Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL environment variable to info. Alternatively, logging can be enabled at runtime by calling setLogLevel in the @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

For more detailed instructions on how to enable logs, you can look at the @azure/logger package docs.

Next steps

More sample code

For complete working examples, see the individual sample files:

| Scenario | Sample | |---|---| | STAC Collection Management | stacCreateCollectionSample.ts | | STAC Item Management | stacCreateItemSample.ts | | STAC Search | stacSearchSample.ts | | Mosaic Registration | dataRegisterMosaicsSearchSample.ts | | Map Tile Generation | dataGetTileSample.ts | | Point Values | dataGetPointSample.ts | | Ingestion Setup | ingestionCreateSourceSample.ts | | Ingestion Management | ingestionCreateSample.ts | | SAS Token | sharedAccessSignatureGetTokenSample.ts | | Map Legends | dataGetLegendSample.ts |

Additional documentation

Learn more about Microsoft Planetary Computer Pro
Read the STAC Specification
See how to Deploy a GeoCatalog resource
Understand how to Manage access to Microsoft Planetary Computer Pro

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.