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.

Documentation

Index

• func IsCoreItemProperty(prop string) bool
• func PopulateExtensionFromProperties(extension ItemExtension, properties map[string]any) error
• type Asset
  • func (asset Asset) MarshalJSON() ([]byte, error)
• type AssetExtension
• type Catalog
  • func (catalog Catalog) MarshalJSON() ([]byte, error)
• type Collection
  • func (collection Collection) MarshalJSON() ([]byte, error)
• type CollectionsList
• type Extent
• type Item
  • func (item Item) MarshalJSON() ([]byte, error)
• type ItemExtension
• 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 IsCoreItemProperty

func IsCoreItemProperty(prop string) bool

func PopulateExtensionFromProperties

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

Types

type Asset

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

func (Asset) MarshalJSON

func (asset Asset) MarshalJSON() ([]byte, error)

type AssetExtension

type AssetExtension interface {
	Apply(*Asset)
	URI() string
}

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"`
}

func (Collection) MarshalJSON

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

type CollectionsList

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

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 []ItemExtension   `json:"-"`
}

func (Item) MarshalJSON

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

type ItemExtension

type ItemExtension interface {
	Apply(*Item)
	URI() string
}

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"`
}