go-stac-server

README

go-stac-server

Spatio-Temporal Asset Catalog (STAC) STAC is a standard for publishing meta-data about geo-spatial data. It defines a common REST API for accessing, searching and modifying geospatial data. For further details about the STAC spec see STAC Specification

go-stac-server is a golang implementation of the STAC API specification using a PostgreSQL database to store data.

There is a rich ecosystem of tools available for STAC. For a list of tools currently available consult the STAC Tools & Resources webpage.

Requirements

1. PostgreSQL 13+
2. PostGIS 3+
3. pgstac schema

Quickstart

# install pypgstac and initialize database
pip install pypgstac
pip install "pypgstac[psycopg]"
export DSN=postgresql://stac@localhost:5432/stac
pypgstac migrate
go-stac-server

In a web browser, navigate to https://localhost:3000/ to browse the catalog.

Testing

Testing is done with the stac-api-validator. To validate the STAC server:

pip install stac-api-validator
stac-api-validator \
    --root-url http://localhost:3000/api/stac/v1/ \
    --conformance core \
    --conformance item-search \
    --conformance features \
    --collection noaa-emergency-response \
    --geometry '{"type": "Polygon", "coordinates": [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]]}'

Configuration

Command Flag	Environment Variable	Configuration File	Description
--dsn	DSN	database.dsn	Database connection string postgresql://[[username:[password]@][host[:port]][/dbname][?paramspec]
--port	PORT	server.port	Port to run server on
--base-url	BASE_URL	server.baseUrl	Base URL to use when expanding links
--catalog-id	STAC_CATALOG_ID	stac.catalog.id	ID used for STAC catalog
--catalog-title	STAC_CATALOG_TITLE	stac.catalog.title	Title of this STAC catalog
--catalog-description	STAC_CATALOG_DESCRIPTION	stac.catalog.description	Description of this STAC catalog

Sample configuration file:

[server]
port=3000
baseUrl="http://localhost:3000"

[database]
dsn="postgresql://stac@localhost:5432/stac"

[stac.catalog]
id="stac-catalog"
title="STAC API"
description="go-stac-server STAC API"

PgSTAC provides the backend database and offers several configuration options. See their documentation for specifics on what options are available.

Title	Version	Description
Browseable	1.0.0-rc.3	Browseable advertises all Items in a STAC API Catalog can be reached by traversing child and item links.
Context	1.0.0-rc.2	Context Extension
Fields	1.0.0-rc.3	The Fields Extensions describes a mechanism to include or exclude certain fields from a response.
Filter	1.0.0-rc.2	The Filter extension provides an expressive mechanism for searching based on Item attributes.
Query	1.0.0-rc.2	The Query Extension adds a query parameter that allows additional filtering based on the properties of Item objects.
Sort	1.0.0-rc.2	The Sort Extension that allows the user to define the fields by which to sort results.
Transaction	1.0.0-rc.2	The Transaction Extension supports the creation, editing, and deleting of items through POST, PUT, PATCH, and DELETE requests.

Errors

go-stac-server logs most errors using structured logging. For fatal errors the application will exit with a non-zero exit code.

Exit Code	Description
0	Application exited successfully
66	Could not connect to database
73	Could not bind to server port