Azure Planetary Computer Pro client library for JavaScript - version 1.0.0-beta.1

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

See our support policy for more details.

Prerequisites

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:

  1. Install the Azure Identity package:
npm install @azure/identity

  1. Register a new Microsoft Entra ID application and grant access to Microsoft Planetary Computer Pro by assigning the suitable role to your service principal.

  2. 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.

  3. 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

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 opencode@microsoft.com with any additional questions or comments.

  • Last updated on