radiantearth / stac-spec

SpatioTemporal Asset Catalog specification - making geospatial assets openly searchable and crawlable

About

The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standardize the way geospatial asset metadata is structured and queried. A "spatiotemporal asset" is any file that represents information about the Earth at a certain place and time. The original focus was on scenes of satellite imagery, but the specifications now cover a broad variety of uses, including sources such as aircraft and drone and data such as hyperspectral optical, synthetic aperture radar (SAR), video, point clouds, lidar, digital elevation models (DEM), vector, machine learning labels, and composites like NDVI and mosaics. STAC is intentionally designed with a minimal core and flexible extension mechanism to support a broad set of use cases. This specification has matured over the past several years, and is used in numerous production deployments.

This is advantageous to providers of geospatial data, as they can simply use a well-designed, standard format and API without needing to design their own proprietary one. This is advantageous to consumers of geospatial data, as they can use existing libraries and tools to access metadata, instead of needing to write new code to interact with each data provider's proprietary formats and APIs.

The STAC specifications define related JSON object types connected by link relations to support a HATEOAS-style traversable interface and a RESTful API providing additional browse and search interfaces. Typically, several STAC specifications are composed together to create an implementation. The Item, Catalog, and Collection specifications define a minimal core of the most frequently used JSON object types. Because of the hierarchical structure between these objects, a STAC catalog can be implemented in a completely 'static' manner as a group of hyperlinked Catalog, Collection, and Item URLs, enabling data publishers to expose their data as a browsable set of files. If more complex query abilities are desired, such as spatial or temporal predicates, the STAC API specification can be implemented as a web service interface to query over a group of STAC objects, usually held in a database.

To the greatest extent possible, STAC uses and extends existing specifications. The most important object in STAC is an Item, which is simply a GeoJSON Feature with a well-defined set of additional attributes ("foreign members"). The STAC API extends the OGC API - Features - Part 1: Core with additional web service endpoints and object attributes.

Current version and branches

The master branch is the 'stable' version of the spec. It is currently version 1.0.0 of the specification. The STAC specification follows Semantic Versioning, so any breaking change will require the spec to go to 2.0.0.

The dev branch is where active development takes place, and may have inconsistent examples. Whenever dev stabilizes, a release is cut and we merge dev in to master. So master should be stable at any given time. More information on how the STAC development process works can be found in process.md.

Communication

Our gitter channel is the best place to ask questions or provide feedback. The majority of communication about the evolution of the specification takes place in the issue tracker and in pull requests.

In this Repository

This repository contains the core object type specifications, examples, validation schemas, and documentation about the context and plans for the evolution of the specification. Each folder contains a README explaining the layout of the folder, the main specification document, examples, and validating schemas.

Additionally, the STAC API specification provides API endpoints, based on the OGC API - Features standard, that enable clients to search for Item objects that match their filtering criteria.

The Item, Catalog, Collection, and STAC API specifications are intended to be used together, but are designed so each piece is small, self-contained, and reusable in other contexts.

• Overview describes the three core object type specifications and how they relate to one another.
• Item Specification defines a STAC Item, which is a GeoJSON Feature with additional fields ("foreign members") for attributes like time and links to related entities and assets (including thumbnails). This is the core entity that describes the data to be discovered.
• Catalog Specification specifies a structure to link various STAC Items together to be crawled or browsed. It is a simple, flexible JSON file of links to Items, Catalogs or Collections that can be used in a variety of ways.
• Collection Specification provides additional information about a spatio-temporal collection of data. In the context of STAC it is most likely a related group of STAC Items that is made available by a data provider. It includes things like the spatial and temporal extent of the data, the license, keywords, etc. It enables discovery at a higher level than individual Item objects, providing a simple way to describe sets of data.
• Examples: The examples/ folder contains examples for all three specifications, linked together to form two complete examples. Each spec and extension links in to highlight particular files that demonstrate key concepts.
• Extensions describe how STAC can use extensions that extend the functionality of the core spec or add fields for specific domains. Extensions can be published anywhere, although the preferred location for public extensions is in the GitHub stac-extensions organization.
• Additional documents: The supporting documents include a complementary best practices document, and information on contributing (links in the next section). We also maintain a changelog of what was modified in each version.

Contributing

Anyone building software that catalogs imagery or other geospatial assets is welcome to collaborate. Beforehand, please review our guidelines for contributions and code of conduct. You may also be interested in our overall process, and the principles that guide our collaboration

stac-spec's Issues

Define a 'transaction' extension for STAC + WFS

This may end up as just a pointer to pure WFS issues, to which we add a reference in the STAC stuff. But since there seems to be more progress making transactions this may be a good contribution from STAC to WFS.

We should define the OpenAPI snippet and a narrative text, and contribute to WFS. https://app.swaggerhub.com/apis/joshfix/STAC/1.0.0-RC5 contains an API with the transaction verbs in it that Boundless implemented and ENVI then borrowed. Should break it out in to its own snippet.

Specify GET search request for STAC API

I think we want to provide guidance on what the GET endpoint for the STAC API looks like. I think POST in the search endpoint should be the required one. But I think it'd be good to have a recommendation on a GET endpoint, that is the same filter values, etc.

We could do this as an extension, to emphasize that it's optional. Though I'd be fine if we had it in core and just said it was optional.

Move thumbnails from 'links' to 'assets'

There was discussion at the ft. collins sprint on moving thumbnails to be an 'asset' instead of a 'link'. It feels more like an asset - it can be downloaded and used, and as participants remembered it was just in links because that's where it started.

So it should move to the 'assets' field.

• Update the spec fields and narrative in json-spec/
• Update the JSON Schema #57
• Update the OpenAPI doc #55
• Update examples + samples (in openapi doc, json-spec and static examples)

Thumbnails should be strongly recommended, not required

There was discussion at the ft. collins sprint brought up by Simon from Google on if thumbnails should be mandatory.

Though the group generally wants to encourage thumbnails where ever possible it was agreed that there are some cases where they make less sense, and forcing thumbnails is less good.

But there is agreement to make it strongly recommended, and to try to make validators give a warning if they're not there.

• Update the spec fields and narrative in json-spec/
• Update the JSON Schema
• Update the OpenAPI doc #55
• Update examples + samples (in openapi doc, json-spec and static examples)

Create SpatioTemporal Asset Metadata GeoJSON profile in this repo

Move the geojson profile of SpatioTemporal Asset Metadata to this repository from https://github.com/radiantearth/stam-spec/tree/dev/json-spec with a JSON Schema and examples - one with core fields, and one that is extended.

Ideally preserve the history of that, but it's also ok if it's new.

Finalize Item and Asset JSON

At the boulder sprint, we have a good stab at working through the Item and Asset JSON specs, including some examples of how they would be applied to different cases. We need to discuss all of the details, including #22 and #23, and move all examples to be in line with the specification we have created.

Acquire samples of product metadata and show its mappings to the spec

One of challenges of creating a common metadata schema is that we lack the whole picture.

It would be beneficial to reach out to DG, Planet, and other providers for samples of their metadata with a license that allows it to be stored in this repository.

Once acquired, we could keep the a mapping of the "EO" profile to actual metadata. And when a Pull Request changes the EO profile, reviewers can the see consequences in the mapping.

Essentially, showing in addition to describing.

Include CBERS-4 MUX example

Hi @cholmes , I'll start working on a CBERS example to be included into the repo, as the first pass of generating a static catalog based on the current CBERS on AWS content.

Opening this to discuss the implementation.

Those who are interested in the dataset may obtain more information in https://github.com/fredliporace/cbers-on-aws

Decide 'link' style, for links and assets

See https://gist.github.com/miyagawa/1912431 for options.

Defining the mime types in the link is potentially interesting, but then there's also arguments that the rest API should respond with those types. But with static catalogs it seems like we won't be able to control mime types, at least not as well / with custom mime types.

Add an 'asset definition' file to the spec

One of the main things discussed in the EO session was the notion of a 'product' or 'asset definition' file. This would be a link from an Item, that contains all the definitions of the possible assets in the item. The 'assets' dict in the Item should share the same keys as the asset definition, so one could easily look up the fields. I believe we also decided the asset definition should be optional - assets could also define their fields inline.

We also need to flesh out a bit more the asset fields - what all should have, what the common names are and what they mean, like 'name' and 'type', and which are required.

Planet example doesn't use property namespaces

The planet example is currently inconsistent with the other examples. It shows all the properties without the trait set namespaces. I think we need to agree on the names with or without namespacing. It will make searching and parsing difficult if the property keys are not consistent.

https://github.com/radiantearth/stac-spec/blob/master/json-spec/examples/planet-sample.json

consideration of OpenSearch EO extensions

Hi all: wondering if there has been any consideration on the OGC OpenSearch Extension for Earth Observation Implementation Standard? Seems like use cases for collections and products are covered, and leveraging an existing standard could provide the value of broad interoperability as well.

Thoughts/comments? Apologies in advance if I missed this in the docs somewhere.

Non Polygon geometry types

Great work on this! It came along at just the right time.

We just started working towards implementing a static catalogue using the STAC spec. I should start off by saying that we have non-imagery data, which I realize is not the first priority for the STAC spec. The only part of the core STAC spec which causes us problems is the requirement that the geometry be of either Polygon or MultiPolygon type.

We have data collected as point measurements, so it would make the most sense to use a GeoJSON Point as the geometry type for each Item. We could define a polygonal envelope around each point to satisfy the requirement that the geometry be a Polygon or MultiPolygon, but it would be somewhat ambiguous how we define the polygon.

Better define what should go in 'provider' field

The 'provider' field is so loose as to not be so useful. We should improve that incrementally, and also figure out the long term plan.

In the short term that means picking a definition, either the organization providing or the sensor/instrument, and then having all the examples be consistent (right now we have 'landsat' and 'planet' in the examples, which aren't really the same level). We should then update the spec narrative to be clearer.

In the long term should perhaps figure out some way to enumerate the options, so we don't have 'landsat', 'landsat8', 'usgs', 'nasa', etc all representing the same data.

This came up in #75

Link to provider examples instead of including them

It's a pain to keep all the samples and examples up to date. We should keep just a small core in the stac repo, and then just maintain a page with links to repos of providers.

There's now:
https://github.com/TDG-Platform/dg-stac
https://github.com/cholmes/pdd-stac (which can move to Planet github repo)
and I think a CBERS one somewhere?

Decide on an Item <-> Asset linking structure.

At the end of the Boulder Sprint, we came up with a number of ideas for linking together Assets and Items. We need to finalize that linking concept and codify it into the spec.

Move static catalog and relevant examples from boulder-sprint repo.

https://github.com/radiantearth/boulder-sprint/tree/master/specs/flat_file has lots of great info, it should be ported to this repo, and updated to fit with the latest decisions from #22, #23 and #24 as those are figured out. Would be great to preserve history, but not required.

Create filtering extensions for the EO profile in the STAC API

The core filters are just time and geometry. In the eo profile we can count on a few fields, with a number of optional ones that will often be used. We should define the filters that are used against them.

We might consider making more fields required, so we can count on more filters.

Better specify the Catalog json for static catalogs

The static catalog spec talks about a catalog.json in the narrative but doesn't fully specify it. We should make that more clear.

• Update the narrative (#58)
• Create a json schema for the catalog.
• Validate samples against the json schema and update any changes needed.

Change Assets from Array to Dict

There was solid consensus to change the 'assets' fields from an array to a dict. See summary of discussion.

This enables easier use of the assets for a variety of systems.

• Update the JSON Schema (in #57)
• Update the spec fields and narrative in json-spec/
• Update the OpenAPI doc and api spec narrative in api-spec/ #55
• Update the samples in the json-spec/
• Update the static STAC narrative and examples in static-catalog

fully remove references to pre 0.4.0 stuff in openapi specs

@francbartoli pointed out on gitter that assets is still an array, and start and end are still in there. Need to purge these and get a 0.4.1 release out

`self` links should always be absolute URLs

This change had unanimous agreement. This would allow all other relative links to be clearly resolved. While it may make moving catalogs slightly more involved, we feel it is a reasonable burden that results in a more easily navigable catalog.

Handle contact info and other collection level metadata with 'catalog' link?

Originally we had 'contact' on a per item level. It could be good to at least have an option to refer back to the catalog for the contact info, so we don't have to repeat it each time.

Could be nice to have a convention to refer back to a catalog. Both as a recommendation in the links section, but also a way to specify a particular section of catalog level metadata, like contact, or license.

Provide a swagger sample document

While OpenAPI 3.0 still does not have amazing tooling support we should also provide a swagger (OpenAPI 2.0) version of at least the standalone specification, and ideally of the full wfs integrated one.

Add best practice of HTML version of 'Items' and 'Catalogs

One important piece discussed at the boulder sprint was to have an HTML / human-readable version of each item. It was decided that the JSON one should be the core standard, but HTML should be encouraged with examples and tooling. HTML pages should be optimized for human consumption, so won't all look the same.

But it'd be good to make some examples and create tooling that can take JSON items and make HTML ones that can sit in static catalogs. The html should have lots of links, display thumbnails, display product and collection level information, and when possible have a slippy map backed by dynamic COG tiling. Perhaps even put up comments (using disqus might be an easy route there).

Update STAC API to align with WFS 3

One of the major decisions made last week in ft. collins was to make it so STAC API is compliant with WFS 3.0. See stac wfs discussion and the stac api breakout group notes.

This will mean that the OpenAPI document will be an 'example' like the WFS openapi stuff, and we'll need to specify STAC as a set of extensions to WFS. So the narrative / guide will likely need to expand.

• Update the openapi document with path changes api-spec/ (progress here)
• Update api-spec narrative document describing how STAC is now a WFS
• Specify the STAC API search extension to wfs /search/stac
• Articulate how one could have multiple 'collections' with schemas or just a single schemaless items collection
• Explain how to do 'content extensions' in STAC that do cross collection search on commonly defined fields.

Add README to describe the STAC domain model

We need to generate some text for the README that describes the domain model of the STAC at a high level. Some components to be defined are:

• SpatioTemporal Asset Catalog (STAC): This is the general name of the catalog system specified in this repository.
• Item: An Item is contained in a STAC, and is described by a OGC SimpleFeature (expressible as GeoJson) that contains the footprint and timestamps of one or more linked Items or Assets.
• Asset: An Asset represents the final thing a Catalog can point to, such as a GeoTiff representing imagery, a laz file representing some lidar information, a metadata file describing other assets, etc.

We should potentially also include the concept for a STAC that was introduced by the Static Catalog working group in the Boulder Sprint, namely the idea that a STAC JSON representation can point to other STACs, creating a tree of crawlable, hierarchically grouped STACs.

Rename repositories and relevant text to reflect naming choice.

In the Boulder Sprint and afterwards in Gitter channel, we decided on the general name of the catalog system specified in this repository to be SpatioTemporal Asset Catalog (STAC). We need to update the repository name and relevant text to reflect this choice.

Band information in Landsat8 example is not as specified

I think the Landsat example at https://github.com/radiantearth/stac-spec/blob/master/json-spec/examples/landsat8-sample.json has some errors, which I struggled with during my work on #81.

• Why is "eo:bands" part of the assets? I assume it's an error and should be moved either one level up or into properties.
• The landsat example uses fwhm instead of full_width_half_max. ;)

Suggestions for remote sensing datasets

Background: in the Google Earth Engine catalog, we have a number of remote sensing raster datasets updated daily. Many of them are not observation results - they can also be, for example, global hourly climate model outputs with a pixel size of 0.1 degree, containing temperature, precipitation and other bands.

We have hit a number of pain points browsing catalogs on medium and large sites, so here are some things I wish catalogs included, with more important fields first.

1. Band type - observational, classification or bitmask. This is important for pyramiding during ingestion when one higher-level pixel is created from several low-level ones. Observational bands have continuous physical values that should be averaged during pyramiding. Classification bands (eg, forest/non-forest) usually contain integer values between 0 and N representing different land classes, and averaging them makes no sense. For the, we just pick the majority pixel value during pyramiding. Bitmask bands should just use random sampling.
2. Fill (nodata) value. It's sometimes specified in gdal metadata, but not always, and may even be wrong.
3. File modification date. Some providers regenerate files in-place several times.
4. Product version. Many providers release several versions of the same product, and it would be convenient to have a dedicated version field, rather than hunt for it in the title string.
5. Dedicated fields for band units (at least as a freeform string).
6. Band scale and offset. Even observation bands sometimes specify scale, and climate datasets use scale/offset a lot.
7. For categoric bands, it would be nice to encode the class values, names, and maybe desired colors. (Eg, value=0, class=Forest, color=00ff00; value=1, class=Water, color=0000ff)
8. Ditto for bitmask bands. They can have a complicated structure, and describing it needs a separate bug.

The rest of suggestions contain some fields we have added to our own dataset descriptions. They reflect the parameters that we think users often want to see in search results or use in queries. That is, I don't need them as much when ingesting data from other's catalogs, but I think I should provide them to improve user experience.

9. Product DOI and citation(s).
10. Per-band resolution (eg, 10 m or 0.25 degrees)
11. Instrument name. This is different from platform name - one platform (satellite) may have multiple instruments.
12. Product periodicity (eg, hourly or daily climate data) or revisit period (eg, 16 days for Landsat 8).
13. List of tags/keywords to help searching.

add a picture

I'd like to add a picture like this:

Figure out a nice display of core openapi specs

Right now the instructions to 'explore the spec' are to put the file in to http://editor.swagger.io/

But that doesn't persist anything, and it's annoying to do that each time.

It should be pretty easy to generate the same type of online page from our documents and make it persistent. I don't actually know how to do this, so if anyone else does please let me know.

Add querying capability to STAC api

The key feature of the API is to enable querying, but the group did not define a full query mechanism at the boulder sprint. Implementing groups should feel free to propose a mechanism to query metadata fields

Add schema responses to catalog api

Add the mechanism to return the json schema for the returned data to the swagger API

Decide how to describe "Product" level information for Assets and Items

In the Boulder Sprint, we determined that there was some need to describe an Asset at the Product level, in that many Assets will be of the same type (e.g. NAIP RGBIR), and there should be one place to describe things like band information, license, etc. We should finalize how to handle the Product level information for Assets and Items.

Update EO examples to be consistent with coming EO profile

We have a few different examples, from landsat, planet, cbers, etc that all share common fields, but right now the definitions are all over the place.

I don't think we need a full EO profile for the 0.4.0 release, but it'd be good to at least have the samples be consistent with one another and point to where we're going. If we can get to a full EO profile in the release that'd be great too.

Create JSON-schema for EO profile validation

It'd be good to have a JSON-Schema file that can be used to validate the Earth Observation profile, so people can check that they're compliant.

cc @jeffnaus & @matthewhanson

Provide json examples & updated specs to reflect core 0.2 decisions

After #22, #23 and #24 are decided we need to make sure there are updated metadata and static catalog specs. Plus e also decided on Asset and Item / Items for the core names, so specs should be updated to reflect that.

And we should be sure to provide good examples of how the specs work, ideally with several asset types (landsat, DG, NAIP, etc). We likely need an 'examples' folder.

Adding (content-)type to links

For consistency with WFS 3 links, it could be interesting to add a "type" property to links to describe the content-type.

So the liinks from https://github.com/radiantearth/stac-spec/blob/dev/static-catalog/examples/Planet/20170129_181030_0e1f_analytic.json would become:

"links": [
    { "rel": "self", "type": "application/json", "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.json"},
    { "rel": "thumbnail", "type": "image/png", "href":"thumbnail.png"},
    { "rel": "catalog", "type": "application/json",  "href": "http://cool-sat.com/catalog/"},
    { "rel": "acquisition",  "type": "application/json", "href": "http://cool-sat.com/catalog/acquisitions/20160503_56"}
]

Advantages: possibiliity to add alternate representations for the same resource
Drawbacks: may make client life harder to determine "unique" resources. In particular for list of items.

e.g

    { "rel": "catalog", "type": "application/json",  "href": "http://itemA.json"},
    { "rel": "catalog", "type": "text/html",  "href": "http://itemA.html"},
    { "rel": "catalog", "type": "application/json",  "href": "http://itemB.json"},
    { "rel": "catalog", "type": "text/html",  "href": "http://itemB.html"},

So perhaps not such a good idea to have multiple representations. Or perhaps provide them as rel:alternate in the itemXXXX.json file ?

Align stac api swagger spec with static catalog

Once the static catalog is set we should revisit the swagger / openapi 2.0 document to make sure that the responses from it mirror it exactly, so a client could treat them as the same.

Define the branching / PR / changes 'process'

As the spec stabilizes a bit we should document a process for how a new version is made and how the community reaches consensus on how a suggestion gets incorporated.

cc @jeffnaus - you said you could help on this one.

Webpage for STAC

Not high priority, but once the specification is a bit more firm we should put up a webpage to explain the concepts to non-developers. And highlight implementations that support the standard.

Slippy maps from Cloud Optimized GeoTiff

@cholmes I saw in your implementation details for Planet that you use COG. Do you also use COG as a basis for slippy maps? Eg; generating TMS endpoints? If so, are you able to explain how?

Refine the collection concept

See discussion in #63

Should contain the information about a set of Items that share metadata and assets.

Should include the collection level metadata so the Items don't have to repeat so much.

Should include the json-schema to validate (or probably a link to it?)

May be the spot we put DCAT type metadata.

Drop 'start' and 'end' in favor of a single time field.

After extensive discussion about time the conclusion seemed to be that in core we would go to a single time field. Extensions like EO could define additional fields if they wanted to.

• Update the spec fields and narrative in json-spec/
• Update the JSON Schema
• Update the OpenAPI doc and api spec narrative in api-spec/
• Update the samples in the json-spec/
• Update the static STAC narrative and examples in static-catalog

Reference WFS/WMTS representations of STAC Items

Hello,
In our catalog response we embeded specific links for consuming WFS and WMTS

 "_links": {
                "panSharpenedWms": {
                    "href": "https://foo/bar/104527cc-6476-4605-ad45-f6f2a28f563c?SERVICE=WMS&REQUEST=GetCapabilities",
                    "name": "OTF PanSharpened",
                    "type": "WMS"
                },
                "panSharpenedWmts": {
                    "href": "https://foo/bar/104527cc-6476-4605-ad45-f6f2a28f563c/1.0.0/WMTSCapabilities.xml",
                    "name": "OTF PanSharpened",
                    "type": "WMTS"
                },
}

I don't know if it can be studied as part of the STAC spec, so I'm just writting down the idea and our use case.

Drop repo

This repo is redundant. It should be dropped in favor of www.openstreetmap.org and other APIs such as mapbox.com, https://market.trimbledata.com 💯

sat-api implementation status and lessons learned

I've got a new version of sat-api up and running at http://sat-api.developmentseed.org which includes Landsat-8 and Sentinel-2 data on AWS. Not all the records are ingested yet, but by tomorrow night it should contain all of the landsat-8 and sentinel-2 data, around 5.5 million scenes.

sat-api a partial implementation of STAC 0.4.1 and includes the EO and Collections extensions. Below are notes on my specific sat-api implementation, as well as questions and issues that came up about the STAC spec. Of particular note is the section on Collections below, which details how the search is able to search items by using metadata from both it and the collections they are part of.

If you don't have a JSON viewer browser plugin I suggest you install one, it will format the JSON to be readabale and will automatically make links from URLs.

sat-api endpoints

There is no documenation endpoint ATM (I could use suggestions or help with how best to creaate that), but there are two endpoints, one for collections and one for items. items and collections have a collection property which is the name of the collection, and items also have a link in the links section to the collection.

/collections: Can search on any field in the collection, e.g. https://sat-api.developmentseed.org/collections?collection=landsat-8
/search/stac: Can search on any field that appears in Items or the Collections those items link to. More on that below.

It's a little weird because both endpoints are search endpoints. /search/stac was to be compliant with WFS3, but /items here would make more sense or an equivalent /search endpoint for collections.

Departures from STAC spec

Here is a list of things that are different between the sat-api implemenation and the STAC spec.

• Not yet implemented bbox for searching. However, it does accept the more useful 'intersects' term for searches based on polygons
• 'collection_name' is now just 'collection'
• No more CRS field, instead there is an 'eo:epsg' field. It is currently ommitted from Landsat, but is included for Sentinel
• datetime field, not 'time' (some parts of the spec I think still refer to just 'time')
• ISO 8601 is not implemented for date searches, so period strings are not accepted, however single datetimes, partial or full, work, as do date ranges specified with a slash, e.g., 2017-08-01/2017-08-31
• The spec does not currently have specifics on how ranges should be specified for other fields. For now I used the slash notation, but think the spec should specify using separate gt and lt filters. e.g. eo:cloud_cover=0/20 for cloud cover between 0 and 20%
• The assets are currently barebones, I did not add additional fields such as descriptions, filetype, etc.

Not all fields are included for both landsat and sentinel. Landsat does not have an eo:epsg code, sentinel does not have viewing azimuth (eo:azimuth) or sun angle information (eo:sun_azimuth, eo:sun_elevation)

Links

Assets use a dictionary structure with a key. It feels like links should follow the same structure and instead of a 'rel' field, make it a key, e.g.

links = {
    "self": {"href": ...url...}
}

Also I couldn't decide whether or not provider supplied metadata files were an asset or a link. I currently made them assets (under the metadata key), but it might make more sense as a link.

Collections

The most challenging aspect of the API ended up being handling the concept of collections as presented in the Collections extension. Collections can include any abitrary fields that were part of an item, and that would apply to all STAC items in that collection (specified through the collection field). So, for landsat-8 we can specify eo:platform as "landsat-8" and it applies to all items in the landsat-8 collection.

The challenge was how to implement this using elasticsearch, because you don't actually know what fields are in the item and which are in the collection (stored in two different indices in elasticsearch). If the field is present in one it will be missing in the other, and by default missing fields do not match. So if you search items for eo:platform and that field is in an items collection, it will not be matched.

So instead /search/stac takes a two step approach and in each it allows for missing fields.

1 - Search the collections index, but allow for either a match or a missing field. This ends up returning all collections for which each of the search fields is either a match or the field is missing. The exception to this is geometry. The geometry search in elasticsearch is a bit more complicated so for now I removed it when searching collections. So at this time, sat-api does not support geometry in collections, only items.

2 - With the list of matched collections, add these to the item search. Therefore any matched collection will now return all items that are part of it, further filtered by the additional fields. Again, a missing field is considered a match, because it is presumed to have been in the collection.

Overall this approach works well, however allowing missing fields to match does create a side effect which is both a feature and a bug. The issue comes in when a search field is missing from both the collection and the item, because this will stil return a match.

• On one hand this is a feature, because it allows you to search on terms only in one collection and have that filter only apply to items in that collection. For example we can search for landsat and sentinel imagery in an area and daterange, but also further filter landsat based on path or row (e.g., landsat:row, landsat:path) and filter sentinel also based on the MGRS grid designation. Note that I currently do not have collection-specific metadata in sat-api, but will add them as they are found useful

• On the other hand this is a bug as you can search for non-existent terms by accident, for example searching for cloud_cover=0/10 instead of eo:cloud_cover=0/10. This may lead a user to think they are getting mostly cloud free imagery when they are not due to a typo.

The benefits outweigh the problem I think, and we could fix the problem other ways by validating search terms against the spec. Also, this approach still works fine when an item has no collection, since those items will have a missing collection field.

Please feel free to test out sat-api and point out any problems, or jump into the repo and take a look at open tickets if you want to contribute!
https://github.com/sat-utils/sat-api

Consider z axis

We should consider if height is also part of geometries in STAC, and either explicitly say it's not or make sure that an extension mechanism can handle it, or that it's just ok with geojson definitions.

Catalog API versus rsync/mirroring

I'm not sure if this is the best place to bring this up. Perhaps the mailing list would be better?

Whilst we're in the preliminary stages here, I just thought it might be good to at least briefly explore other approaches to the same goal, namely;

increase interoperability, enabling more catalog clients and cross-catalog searching

In essence: what if only imagery was standardised?

This would mean that catalogs were able to easily ingest imagery from multiple sources, but were free to implement any form of search interface. Of course it would indeed be ideal to have standardised APIs as well, but does that extra effort reflect the extra value achieved? For example, if rsync and a standardised imagery specification were made the only requirements, the primary goal of cross-catalog searching would still be made possible by pointing your client to the catalog that archived the sources you were interested in. The only drawback I see is the headache to the client users who must write extra code if a single catalog didn't meet their requirements. This seems like a smaller thing than expecting multiple catalog owners to implement and conform to a single canonical API.

Whatever approach is taken, at some point I can foresee that someone will be able to create a catalog that archives everything! After all, they only need to store small JSON objects, not imagery, so the running costs will be trivial. So what if instead of standardising on an API, we just come together to maintain a single catalog implementation?