client

package
v0.0.0-...-fd8a2b5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 11, 2025 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package client provides a CQL2-JSON filter query builder for STAC API searches.

This implementation wraps the github.com/planetlabs/go-ogc/filter package to provide a convenient, fluent API for building CQL2-JSON filter expressions.

Example usage: 

f := client.NewFilterBuilder().
    And(client.Lt(client.Property("eo:cloud_cover"), client.Number(10))).
    And(client.SIntersects(
        client.Property("geometry"),
        client.BBox(-122.5, 37.5, -122.0, 38.0),
    )).
    Build()

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AContainedBy 

func AContainedBy(left, right filter.ArrayExpression) *filter.ArrayComparison

AContainedBy tests if all elements of the first array are in the second.

func AContains 

func AContains(left, right filter.ArrayExpression) *filter.ArrayComparison

AContains tests if the first array contains all elements of the second.

func AEquals 

func AEquals(left, right filter.ArrayExpression) *filter.ArrayComparison

AEquals tests if two arrays are equal.

func AOverlaps 

func AOverlaps(left, right filter.ArrayExpression) *filter.ArrayComparison

AOverlaps tests if two arrays have at least one common element.

func And 

func And(exprs ...filter.BooleanExpression) *filter.And

And creates a logical AND of multiple expressions.

func Array 

func Array(items ...filter.ArrayItemExpression) filter.Array

Array creates an array literal from items.

func BBox 

func BBox(minLon, minLat, maxLon, maxLat float64) *filter.BoundingBox

BBox creates a 2D bounding box expression. Order: minLon, minLat, maxLon, maxLat

func BBox3D 

func BBox3D(minLon, minLat, minElev, maxLon, maxLat, maxElev float64) *filter.BoundingBox

BBox3D creates a 3D bounding box expression. Order: minLon, minLat, minElev, maxLon, maxLat, maxElev

func Between 

func Between(value, low, high filter.NumericExpression) *filter.Between

Between creates a range comparison (value BETWEEN low AND high).

func Boolean 

func Boolean(b bool) *filter.Boolean

Boolean creates a boolean literal.

func Date 

func Date(dateStr string) *filter.Date

Date creates a date expression from a date string (YYYY-MM-DD).

func DateFromTime 

func DateFromTime(t time.Time) *filter.Date

DateFromTime creates a date expression from a time.Time.

func DefaultNextHandler 

func DefaultNextHandler(links []*stac.Link) (*url.URL, error)

DefaultNextHandler looks for the first link with rel="next" and returns its Href parsed as a URL. The returned URL may be relative or absolute, as specified in the link's Href.

func Eq 

func Eq(left, right filter.ScalarExpression) *filter.Comparison

Eq creates an equality comparison (=).

func Geometry 

func Geometry(g orb.Geometry) *filter.Geometry

Geometry converts an orb.Geometry to a filter.Geometry for use in spatial operations. This is the primary way to use orb geometries with the CQL2 filter builder.

Example: 

pt := orb.Point{-122.4194, 37.7749}
filter := SIntersects(Property("geometry"), Geometry(pt))

func GeometryCollection 

func GeometryCollection(geometries ...orb.Geometry) *filter.Geometry

GeometryCollection creates a GeoJSON GeometryCollection from multiple orb geometries.

func GeometryCollectionFromOrb 

func GeometryCollectionFromOrb(gc orb.Collection) *filter.Geometry

GeometryCollectionFromOrb creates a filter.Geometry from an orb.Collection.

func GeometryFromGeoJSON 

func GeometryFromGeoJSON(gjson map[string]any) *filter.Geometry

GeometryFromGeoJSON creates a filter.Geometry from a raw GeoJSON map. Use this when you have GeoJSON data that's not in orb format.

func Gt 

func Gt(left, right filter.ScalarExpression) *filter.Comparison

Gt creates a greater-than comparison (>).

func Gte 

func Gte(left, right filter.ScalarExpression) *filter.Comparison

Gte creates a greater-than-or-equal comparison (>=).

func In 

func In(item filter.ScalarExpression, list ...filter.ScalarExpression) *filter.In

In creates a membership test (value IN list).

func Interval 

func Interval(start, end filter.InstantExpression) *filter.Interval

Interval creates a time interval expression from start and end timestamps.

func IntervalFromStrings 

func IntervalFromStrings(start, end string) *filter.Interval

IntervalFromStrings creates a time interval from ISO 8601 strings. Use empty string for open-ended intervals.

func IntervalFromTimes 

func IntervalFromTimes(start, end time.Time) *filter.Interval

IntervalFromTimes creates a time interval from time.Time values.

func IsNull 

func IsNull(value filter.Expression) *filter.IsNull

IsNull creates a null check (value IS NULL).

func Like 

func Like(value filter.CharacterExpression, pattern filter.PatternExpression) *filter.Like

Like creates a pattern matching expression. Use % for multi-character wildcard and _ for single character wildcard.

func LineString 

func LineString(coords ...[]float64) *filter.Geometry

LineString creates a GeoJSON LineString geometry from coordinate pairs. Each coordinate is [lon, lat].

func LineStringFromOrb 

func LineStringFromOrb(ls orb.LineString) *filter.Geometry

LineStringFromOrb creates a filter.Geometry from an orb.LineString.

func Lt 

func Lt(left, right filter.ScalarExpression) *filter.Comparison

Lt creates a less-than comparison (<).

func Lte 

func Lte(left, right filter.ScalarExpression) *filter.Comparison

Lte creates a less-than-or-equal comparison (<=).

func MultiLineString 

func MultiLineString(lines ...[][]float64) *filter.Geometry

MultiLineString creates a GeoJSON MultiLineString geometry.

func MultiLineStringFromOrb 

func MultiLineStringFromOrb(mls orb.MultiLineString) *filter.Geometry

MultiLineStringFromOrb creates a filter.Geometry from an orb.MultiLineString.

func MultiPoint 

func MultiPoint(coords ...[]float64) *filter.Geometry

MultiPoint creates a GeoJSON MultiPoint geometry from coordinate pairs.

func MultiPointFromOrb 

func MultiPointFromOrb(mp orb.MultiPoint) *filter.Geometry

MultiPointFromOrb creates a filter.Geometry from an orb.MultiPoint.

func MultiPolygon 

func MultiPolygon(polygons ...[][][]float64) *filter.Geometry

MultiPolygon creates a GeoJSON MultiPolygon geometry.

func MultiPolygonFromOrb 

func MultiPolygonFromOrb(mpoly orb.MultiPolygon) *filter.Geometry

MultiPolygonFromOrb creates a filter.Geometry from an orb.MultiPolygon.

func Neq 

func Neq(left, right filter.ScalarExpression) *filter.Comparison

Neq creates an inequality comparison (<>).

func Not 

func Not(expr filter.BooleanExpression) *filter.Not

Not creates a logical NOT of an expression.

func Number 

func Number(n float64) *filter.Number

Number creates a numeric literal.

func OpenIntervalAfter 

func OpenIntervalAfter(start string) *filter.Interval

OpenIntervalAfter creates an open-ended interval from the given time.

func OpenIntervalBefore 

func OpenIntervalBefore(end string) *filter.Interval

OpenIntervalBefore creates an open-ended interval up to the given time.

func Or 

func Or(exprs ...filter.BooleanExpression) *filter.Or

Or creates a logical OR of multiple expressions.

func Point 

func Point(lon, lat float64) *filter.Geometry

Point creates a GeoJSON Point geometry from longitude and latitude.

func Point3D 

func Point3D(lon, lat, elevation float64) *filter.Geometry

Point3D creates a GeoJSON Point geometry with elevation. Note: orb.Point only supports 2D, so elevation is stored in coordinates array.

func Polygon 

func Polygon(rings ...[][]float64) *filter.Geometry

Polygon creates a GeoJSON Polygon geometry from rings. The first ring is the exterior ring, subsequent rings are holes. Each ring is a slice of [lon, lat] coordinates.

func PolygonFromOrb 

func PolygonFromOrb(poly orb.Polygon) *filter.Geometry

PolygonFromOrb creates a filter.Geometry from an orb.Polygon.

func Property 

func Property(name string) *filter.Property

Property creates a property reference expression. Common STAC properties include:

  • "datetime" - acquisition datetime
  • "eo:cloud_cover" - cloud cover percentage
  • "geometry" - item geometry
  • "id" - item ID
  • "collection" - collection ID

func SContains 

func SContains(geom any) *filter.SpatialComparison

SContains creates a spatial contains test against the "geometry" property. Accepts orb.Geometry, orb.Bound, *filter.Geometry, or *filter.BoundingBox.

func SCrosses 

func SCrosses(geom any) *filter.SpatialComparison

SCrosses creates a spatial crosses test against the "geometry" property. Accepts orb.Geometry, orb.Bound, *filter.Geometry, or *filter.BoundingBox.

func SDisjoint 

func SDisjoint(geom any) *filter.SpatialComparison

SDisjoint creates a spatial disjoint test against the "geometry" property. Accepts orb.Geometry, orb.Bound, *filter.Geometry, or *filter.BoundingBox.

func SEquals 

func SEquals(geom any) *filter.SpatialComparison

SEquals creates a spatial equality test against the "geometry" property. Accepts orb.Geometry, orb.Bound, *filter.Geometry, or *filter.BoundingBox.

func SIntersects 

func SIntersects(geom any) *filter.SpatialComparison

SIntersects creates a spatial intersection test against the "geometry" property. Accepts orb.Geometry, orb.Bound, *filter.Geometry, or *filter.BoundingBox.

func SOverlaps 

func SOverlaps(geom any) *filter.SpatialComparison

SOverlaps creates a spatial overlaps test against the "geometry" property. Accepts orb.Geometry, orb.Bound, *filter.Geometry, or *filter.BoundingBox.

func STouches 

func STouches(geom any) *filter.SpatialComparison

STouches creates a spatial touches test against the "geometry" property. Accepts orb.Geometry, orb.Bound, *filter.Geometry, or *filter.BoundingBox.

func SWithin 

func SWithin(geom any) *filter.SpatialComparison

SWithin creates a spatial within test against the "geometry" property. Accepts orb.Geometry, orb.Bound, *filter.Geometry, or *filter.BoundingBox.

func String 

func String(s string) *filter.String

String creates a string literal.

func TAfter 

func TAfter(left, right filter.TemporalExpression) *filter.TemporalComparison

TAfter creates a temporal "after" test.

func TBefore 

func TBefore(left, right filter.TemporalExpression) *filter.TemporalComparison

TBefore creates a temporal "before" test.

func TContains 

func TContains(left, right filter.TemporalExpression) *filter.TemporalComparison

TContains creates a temporal "contains" test.

func TDisjoint 

func TDisjoint(left, right filter.TemporalExpression) *filter.TemporalComparison

TDisjoint creates a temporal "disjoint" test.

func TDuring 

func TDuring(left, right filter.TemporalExpression) *filter.TemporalComparison

TDuring creates a temporal "during" test.

func TEquals 

func TEquals(left, right filter.TemporalExpression) *filter.TemporalComparison

TEquals creates a temporal "equals" test.

func TFinishedBy 

func TFinishedBy(left, right filter.TemporalExpression) *filter.TemporalComparison

TFinishedBy creates a temporal "finished by" test.

func TFinishes 

func TFinishes(left, right filter.TemporalExpression) *filter.TemporalComparison

TFinishes creates a temporal "finishes" test.

func TIntersects 

func TIntersects(left, right filter.TemporalExpression) *filter.TemporalComparison

TIntersects creates a temporal "intersects" test.

func TMeets 

func TMeets(left, right filter.TemporalExpression) *filter.TemporalComparison

TMeets creates a temporal "meets" test.

func TMetBy 

func TMetBy(left, right filter.TemporalExpression) *filter.TemporalComparison

TMetBy creates a temporal "met by" test.

func TOverlappedBy 

func TOverlappedBy(left, right filter.TemporalExpression) *filter.TemporalComparison

TOverlappedBy creates a temporal "overlapped by" test.

func TOverlaps 

func TOverlaps(left, right filter.TemporalExpression) *filter.TemporalComparison

TOverlaps creates a temporal "overlaps" test.

func TStartedBy 

func TStartedBy(left, right filter.TemporalExpression) *filter.TemporalComparison

TStartedBy creates a temporal "started by" test.

func TStarts 

func TStarts(left, right filter.TemporalExpression) *filter.TemporalComparison

TStarts creates a temporal "starts" test.

func Timestamp 

func Timestamp(iso8601 string) *filter.Timestamp

Timestamp creates a timestamp expression from an ISO 8601 string.

func TimestampFromTime 

func TimestampFromTime(t time.Time) *filter.Timestamp

TimestampFromTime creates a timestamp expression from a time.Time.

Types

type BooleanExpression 

type BooleanExpression = filter.BooleanExpression

Expression types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client represents a STAC API client

func NewClient 

func NewClient(baseURL string, opts ...ClientOption) (*Client, error)

NewClient creates a new STAC client.

func (*Client) DownloadAsset 

func (c *Client) DownloadAsset(ctx context.Context, assetURL, destPath string) error

DownloadAsset retrieves the asset at assetURL and writes it to destPath.

func (*Client) DownloadAssetWithProgress 

func (c *Client) DownloadAssetWithProgress(
	ctx context.Context,
	assetURL string,
	destPath string,
	progress ProgressFunc,
) error

DownloadAssetWithProgress downloads an asset while reporting progress.

func (*Client) GetCatalog 

func (c *Client) GetCatalog(ctx context.Context) (*stac.Catalog, error)

GetCatalog fetches the root catalog document from the STAC API. This is typically the entry point for exploring a STAC API, containing links to collections, search endpoints, and conformance information.

func (*Client) GetCollection 

func (c *Client) GetCollection(ctx context.Context, collectionID string) (*stac.Collection, error)

GetCollection fetches a single collection document by ID.

func (*Client) GetCollections 

func (c *Client) GetCollections(ctx context.Context) iter.Seq2[*stac.Collection, error]

GetCollections iterates over every collection exposed by the STAC API referenced by the client. It transparently follows pagination using the client's nextHandler. The returned iterator yields either *stac.Collection values or an error. The iteration stops when the consumer returns false or when there are no further pages.

func (*Client) GetCollectionsWithDecoder 

func (c *Client) GetCollectionsWithDecoder(ctx context.Context, decoder PageDecoder[stac.Collection]) iter.Seq2[*stac.Collection, error]

GetCollectionsWithDecoder fetches collections using a custom page decoder. This is useful for APIs that return non-standard response formats.

func (*Client) GetConformance 

func (c *Client) GetConformance(ctx context.Context) ([]string, error)

GetConformance fetches the conformance classes supported by the STAC API. This is a convenience method that fetches the catalog and returns the conformsTo field. For more detailed conformance information, use GetCatalog directly.

func (*Client) GetGlobalQueryables 

func (c *Client) GetGlobalQueryables(ctx context.Context) (*stac.Queryables, error)

GetGlobalQueryables fetches the global queryable properties for the STAC API. The endpoint is /queryables as per OGC API - Features Part 3.

func (*Client) GetItem 

func (c *Client) GetItem(ctx context.Context, collectionID, itemID string) (*stac.Item, error)

GetItem fetches an individual item from a collection.

func (*Client) GetItems 

func (c *Client) GetItems(ctx context.Context, collectionID string) iter.Seq2[*stac.Item, error]

func (*Client) GetItemsFromPath 

func (c *Client) GetItemsFromPath(ctx context.Context, path string, decoder PageDecoder[stac.Item]) iter.Seq2[*stac.Item, error]

GetItemsFromPath fetches items from an arbitrary path using a custom page decoder. This is useful for APIs with non-standard endpoint paths (e.g., ICEYE's /catalog/v2/items).

func (*Client) GetItemsWithDecoder 

func (c *Client) GetItemsWithDecoder(ctx context.Context, collectionID string, decoder PageDecoder[stac.Item]) iter.Seq2[*stac.Item, error]

GetItemsWithDecoder fetches items from a collection using a custom page decoder. This is useful for APIs that return non-standard response formats.

func (*Client) GetQueryables 

func (c *Client) GetQueryables(ctx context.Context, collectionID string) (*stac.Queryables, error)

GetQueryables fetches the queryable properties for a collection. The endpoint is /collections/{collectionId}/queryables as per OGC API - Features Part 3.

func (*Client) SearchCQL2 

func (c *Client) SearchCQL2(ctx context.Context, params SearchParams) iter.Seq2[*stac.Item, error]

SearchCQL2 performs a POST-based STAC search using the provided SearchParams as JSON payload.

func (*Client) SearchSimple 

func (c *Client) SearchSimple(ctx context.Context, params SearchParams) iter.Seq2[*stac.Item, error]

SearchSimple performs a GET-based STAC search using URL query parameters.

func (*Client) SearchWithDecoder 

func (c *Client) SearchWithDecoder(ctx context.Context, params SearchParams, decoder PageDecoder[stac.Item]) iter.Seq2[*stac.Item, error]

SearchWithDecoder performs a POST-based search with a custom page decoder. This is useful for APIs that return non-standard response formats (e.g., ICEYE's cursor-based pagination).

Example for ICEYE: 

decoder := client.CursorItemDecoder("data", "cursor", "/catalog/v2/items?cursor=%s")
for item, err := range cli.SearchWithDecoder(ctx, params, decoder) {
    // ...
}

func (*Client) SupportsConformance 

func (c *Client) SupportsConformance(ctx context.Context, conformanceClass string) (bool, error)

SupportsConformance checks if the STAC API supports a specific conformance class. Use the stac.Conformance* constants for common conformance classes.

type ClientOption 

type ClientOption func(*Client)

ClientOption configures the Client.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client.

func WithMiddleware 

func WithMiddleware(mw ...Middleware) ClientOption

WithMiddleware registers one or more request-middleware functions.

func WithNextHandler 

func WithNextHandler(h NextHandler) ClientOption

WithNextHandler configures a custom NextHandler for pagination.

func WithTimeout 

func WithTimeout(d time.Duration) ClientOption

WithTimeout sets the HTTP timeout.

type Error 

type Error struct {
	Code        int    `json:"code"` // HTTP status code
	Description string `json:"description"`
	Type        string `json:"type,omitempty"` // Specific error type if provided by API
}

type FieldsFilter 

type FieldsFilter struct {
	Include []string `json:"include,omitempty"`
	Exclude []string `json:"exclude,omitempty"`
}

type Filter 

type Filter = filter.Filter

Filter is the top-level CQL2 filter type from go-ogc.

type FilterBuilder 

type FilterBuilder struct {
	// contains filtered or unexported fields
}

FilterBuilder provides a fluent interface for building CQL2 filters.

func NewFilterBuilder 

func NewFilterBuilder() *FilterBuilder

NewFilterBuilder creates a new FilterBuilder.

func (*FilterBuilder) And 

func (b *FilterBuilder) And(expr filter.BooleanExpression) *FilterBuilder

And adds an AND condition to the existing filter.

func (*FilterBuilder) Build 

func (b *FilterBuilder) Build() *filter.Filter

Build returns the Filter that can be used in search requests.

func (*FilterBuilder) Or 

func (b *FilterBuilder) Or(exprs ...filter.BooleanExpression) *FilterBuilder

Or creates an OR branch with the given expressions.

func (*FilterBuilder) Where 

func (b *FilterBuilder) Where(expr filter.BooleanExpression) *FilterBuilder

Where sets the initial filter expression.

type Middleware 

type Middleware func(context.Context, *http.Request) error

Middleware manipulates an outgoing *http.Request before it is executed. The context is provided for cancellation and to support auth implementations that may need to perform async operations (e.g., token refresh).

type NextHandler 

type NextHandler func([]*stac.Link) (*url.URL, error)

NextHandler determines the next-page URL from a list of STAC links. Return nil if there's no next page, or an error if parsing fails.

type NumericExpression 

type NumericExpression = filter.NumericExpression

Expression types

type PageDecoder 

type PageDecoder[T any] func(r io.Reader) (*PageResponse[T], error)

PageDecoder decodes a paginated response body into items and pagination info.

func CursorItemDecoder 

func CursorItemDecoder(itemsField, cursorField, nextURLTemplate string) PageDecoder[stac.Item]

CursorItemDecoder creates a decoder for cursor-based pagination APIs like ICEYE. These APIs return {"data": [...], "cursor": "..."} instead of STAC-standard format. The nextURLTemplate should contain "%s" where the cursor value will be substituted. Example: "/catalog/v2/items?cursor=%s"

func DefaultCollectionDecoder 

func DefaultCollectionDecoder() PageDecoder[stac.Collection]

DefaultCollectionDecoder creates a decoder for standard STAC collection responses. Standard STAC APIs return {"collections": [...], "links": [...]}.

func DefaultItemDecoder 

func DefaultItemDecoder() PageDecoder[stac.Item]

DefaultItemDecoder creates a decoder for standard STAC item responses. Standard STAC APIs return {"features": [...], "links": [...]}.

type PageResponse 

type PageResponse[T any] struct {
	Items   []*T
	Links   []*stac.Link
	Cursor  string   // For cursor-based pagination (e.g., ICEYE)
	NextURL *url.URL // Pre-computed next URL (optional, takes precedence over Links)
}

PageResponse holds the decoded response from a paginated API call.

type ProgressFunc 

type ProgressFunc func(downloaded, total int64)

ProgressFunc reports cumulative bytes downloaded and the expected total.

type ScalarExpression 

type ScalarExpression = filter.ScalarExpression

Expression types

type SearchParams 

type SearchParams struct {
	Collections []string       `json:"collections,omitempty"`
	Bbox        []float64      `json:"bbox,omitempty"`
	Datetime    string         `json:"datetime,omitempty"`
	Query       map[string]any `json:"query,omitempty"`
	Limit       int            `json:"limit,omitempty"`
	SortBy      []SortField    `json:"sortby,omitempty"`
	Fields      *FieldsFilter  `json:"fields,omitempty"`
}

type SortField 

type SortField struct {
	Field     string `json:"field"`
	Direction string `json:"direction"` // "asc" or "desc"
}

type SpatialExpression 

type SpatialExpression = filter.SpatialExpression

Expression types

type TemporalExpression 

type TemporalExpression = filter.TemporalExpression

Expression types

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.