stac

README

STAC Utilities

Utilities for working with Spatio-Temporal Asset Catalog (STAC) resources.

The stac command line utility can be used to crawl and validate STAC metadata. In addition, the github.com/planetlabs/go-stac module can be used in Go projects.

Command Line Interface

The stac program can be installed by downloading one of the archives from the latest release.

Extract the archive and place the stac executable somewhere on your path. See a list of available commands by running stac in your terminal.

Mac users can install the stac program with brew:

brew install planetlabs/tap/go-stac

CLI Usage

Run stac help to see a full list of commands and their arguments. The primary stac commands are documented below.

stac validate

The stac validate command crawls STAC resources and validates them against the appropriate schema.

Example use:

stac validate --entry path/to/catalog.json

The --entry can be a file path or URL pointing to a catalog, collection, or item. By default, all catalogs, collections, and items linked from the entry point will be validated. Use the --no-recursion option to validate a single resource without crawling to linked resources. See stac validate --help for a full list of supported options.

stac stats

The stac stats command crawls STAC resources and prints out counts of resource type, versions, extensions, asset types, and conformance classes (for API endpoints).

Example use:

stac stats --entry path/to/catalog.json

The --entry can be a file path or URL pointing to a catalog, collection, or item. The stats output is a JSON object with top-level properties for catalog, collection, and item stats.

The structure of the output conforms with the schema of the STAC Stats extension, so the results can be added to a STAC entrypoint to provide stats on child catalogs, collections, and items. The stac stats command can write out a copy of the provided entrypoint with statistics added.

To write out a version of a catalog or collection that includes metadata for the STAC Stats extension, run the following:

stac stats --entry path/to/catalog.json --output path/to/catalog-with-stats.json

Library Use

Requires Go >= 1.18

Install the module into your project.

go get github.com/planetlabs/go-stac

See the reference documentation for example usage in a Golang project.

Development

See the development doc for information on developing and releasing the go-stac library.

Documentation

Index

• func DecodeExtendedAsset(assetExtension Extension, assetMap map[string]any) error
• func DecodeExtendedItemProperties(itemExtension Extension, itemMap map[string]any) error
• func EncodeAssets(assets map[string]*Asset) (map[string]any, []string, error)
• func EncodeExtendedAsset(assetExtension Extension, assetMap map[string]any) error
• func EncodeExtendedItemProperties(itemExtension Extension, itemMap map[string]any) error
• func GetExtensionUris(data map[string]any) ([]string, error)
• func IsCoreItemProperty(prop string) bool
• func PopulateExtensionFromProperties(extension Extension, properties map[string]any) error
• func RegisterAssetExtension(pattern *regexp.Regexp, provider ExtensionProvider)
• func RegisterCollectionExtension(pattern *regexp.Regexp, provider ExtensionProvider)
• func RegisterItemExtension(pattern *regexp.Regexp, provider ExtensionProvider)
• func SetExtensionUris(data map[string]any, uris []string)
• type Asset
• type Catalog
  • func (catalog Catalog) MarshalJSON() ([]byte, error)
• type Collection
  • func (collection Collection) MarshalJSON() ([]byte, error)
  • func (collection *Collection) UnmarshalJSON(data []byte) error
• type CollectionsList
• type Extension
  • func GetAssetExtension(uri string) Extension
  • func GetCollectionExtension(uri string) Extension
  • func GetItemExtension(uri string) Extension
• type ExtensionProvider
• type Extent
• type Item
  • func (item Item) MarshalJSON() ([]byte, error)
  • func (item *Item) UnmarshalJSON(data []byte) error
• type ItemsList
• type Link
  • func (link *Link) MarshalJSON() ([]byte, error)
  • func (link *Link) UnmarshalJSON(data []byte) error
• type Provider
• type SpatialExtent
• type TemporalExtent

Functions

func DecodeExtendedAsset

func DecodeExtendedAsset(assetExtension Extension, assetMap map[string]any) error

func DecodeExtendedItemProperties

func DecodeExtendedItemProperties(itemExtension Extension, itemMap map[string]any) error

func EncodeAssets

func EncodeAssets(assets map[string]*Asset) (map[string]any, []string, error)

func EncodeExtendedAsset

func EncodeExtendedAsset(assetExtension Extension, assetMap map[string]any) error

func EncodeExtendedItemProperties

func EncodeExtendedItemProperties(itemExtension Extension, itemMap map[string]any) error

func GetExtensionUris

func GetExtensionUris(data map[string]any) ([]string, error)

func IsCoreItemProperty

func IsCoreItemProperty(prop string) bool

func PopulateExtensionFromProperties

func PopulateExtensionFromProperties(extension Extension, properties map[string]any) error

func RegisterAssetExtension

func RegisterAssetExtension(pattern *regexp.Regexp, provider ExtensionProvider)

func RegisterCollectionExtension

func RegisterCollectionExtension(pattern *regexp.Regexp, provider ExtensionProvider)

func RegisterItemExtension

func RegisterItemExtension(pattern *regexp.Regexp, provider ExtensionProvider)

func SetExtensionUris

func SetExtensionUris(data map[string]any, uris []string)

Types

type Asset

type Asset struct {
	Type        string      `json:"type,omitempty"`
	Href        string      `json:"href,omitempty"`
	Title       string      `json:"title,omitempty"`
	Description string      `json:"description,omitempty"`
	Created     string      `json:"created,omitempty"`
	Roles       []string    `json:"roles,omitempty"`
	Extensions  []Extension `json:"-"`
}

type Catalog

type Catalog struct {
	Version     string   `json:"stac_version"`
	Id          string   `json:"id"`
	Title       string   `json:"title,omitempty"`
	Description string   `json:"description"`
	Links       []*Link  `json:"links"`
	ConformsTo  []string `json:"conformsTo,omitempty"`
}

func (Catalog) MarshalJSON

func (catalog Catalog) MarshalJSON() ([]byte, error)

type Collection

type Collection struct {
	Version     string            `json:"stac_version"`
	Id          string            `json:"id"`
	Title       string            `json:"title,omitempty"`
	Description string            `json:"description"`
	Keywords    []string          `json:"keywords,omitempty"`
	License     string            `json:"license"`
	Providers   []*Provider       `json:"providers,omitempty"`
	Extent      *Extent           `json:"extent"`
	Summaries   map[string]any    `json:"summaries,omitempty"`
	Links       []*Link           `json:"links"`
	Assets      map[string]*Asset `json:"assets,omitempty"`
	Extensions  []Extension       `json:"-"`
}

func (Collection) MarshalJSON

func (collection Collection) MarshalJSON() ([]byte, error)

func (*Collection) UnmarshalJSON

func (collection *Collection) UnmarshalJSON(data []byte) error

type CollectionsList

type CollectionsList struct {
	Collections []*Collection `json:"collections"`
	Links       []*Link       `json:"links"`
}

type Extension

type Extension interface {
	URI() string
	Encode(map[string]any) error
	Decode(map[string]any) error
}

func GetAssetExtension

func GetAssetExtension(uri string) Extension

func GetCollectionExtension

func GetCollectionExtension(uri string) Extension

func GetItemExtension

func GetItemExtension(uri string) Extension

type ExtensionProvider

type ExtensionProvider func() Extension

type Extent

type Extent struct {
	Spatial  *SpatialExtent  `json:"spatial,omitempty"`
	Temporal *TemporalExtent `json:"temporal,omitempty"`
}

type Item

type Item struct {
	Version    string            `json:"stac_version"`
	Id         string            `json:"id"`
	Geometry   any               `json:"geometry"`
	Bbox       []float64         `json:"bbox,omitempty"`
	Properties map[string]any    `json:"properties"`
	Links      []*Link           `json:"links"`
	Assets     map[string]*Asset `json:"assets"`
	Collection string            `json:"collection,omitempty"`
	Extensions []Extension       `json:"-"`
}

func (Item) MarshalJSON

func (item Item) MarshalJSON() ([]byte, error)

func (*Item) UnmarshalJSON

func (item *Item) UnmarshalJSON(data []byte) error

type ItemsList

type ItemsList struct {
	Type  string  `json:"type"`
	Items []*Item `json:"features"`
	Links []*Link `json:"links,omitempty"`
}

type Link

type Link struct {
	Href             string         `mapstructure:"href"`
	Rel              string         `mapstructure:"rel"`
	Type             string         `mapstructure:"type,omitempty"`
	Title            string         `mapstructure:"title,omitempty"`
	AdditionalFields map[string]any `mapstructure:",remain"`
}

func (*Link) MarshalJSON

func (link *Link) MarshalJSON() ([]byte, error)

func (*Link) UnmarshalJSON

func (link *Link) UnmarshalJSON(data []byte) error

type Provider

type Provider struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Roles       []string `json:"roles,omitempty"`
	Url         string   `json:"url,omitempty"`
}

type SpatialExtent

type SpatialExtent struct {
	Bbox [][]float64 `json:"bbox"`
}

type TemporalExtent

type TemporalExtent struct {
	Interval [][]any `json:"interval"`
}