You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
It retrieves a group of Collection objects that match the provided parameters and provides them through
27
-
the `GET /collections` endpoint as well.
23
+
This extension extends the STAC API `GET /collections` endpoint to support advanced search capabilities
24
+
for STAC [Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/README.md).
28
25
29
-
The Collection Search endpoint by default doesn't provide any query parameters to filter and all
30
-
additional behavior will be defined in [Extensions](#extensions). These extensions can be composed
31
-
by an implementer to cover only the set of functionality the implementer requires.
26
+
The [`GET /collections` endpoint](https://api.stacspec.org/v1.0.0/collections/#tag/Collections/operation/getCollections)
27
+
doesn't provide any query parameters by default, so a beasic set of query parameters is defined in [Basics](#basics)
28
+
for some rudimentary search functionality that is similar to the default items endpoint in STAC API.
29
+
Additional, more advanced behavior is defined as [optional conformance classes](#optional-conformance-classes).
30
+
These extensions can be composed by an implementer to cover only the set of functionality the implementer requires.
31
+
32
+
## Relation to OGC APIs
32
33
33
34
This extension is based on *[OGC API - Common - Part 2: Geospatial Data](https://portal.ogc.org/files/99149#rc-simple-query-section)*
34
-
and aligned to *[OGC API - Records - Part 1: Local Resource Catalogue](https://docs.ogc.org/DRAFTS/20-004.html#clause-local-resources-catalogue)*
35
+
and aligned to *[OGC API - Records - Part 1: Local Resource Catalogue](https://docs.ogc.org/is/20-004r1/20-004r1.html#clause-local-resources-catalogue)*
35
36
and selectively implements a subset of their "requirements classes".
36
37
37
38
All functionality in *OGC API - Records - Part 1: Local Resource Catalogue* is only defined for the `GET` method (i.e. `GET /collections`).
38
-
*Note:* STAC may add behavior for `POST /collections` in the future, but due to a potential conflict
39
-
with the Transaction Extension, specific rules for content negotiation might be required.
40
39
41
-
## Pagination
40
+
> [!NOTE]
41
+
> STAC may add behavior for `POST /collections` in the future, but due to a potential conflict
42
+
> with the Transaction Extension, specific rules for content negotiation might be required.
43
+
44
+
## Versioning
42
45
43
-
Pagination for collections works exactly as it defined for Collections in general.
44
-
See [Collection Pagination](https://github.com/radiantearth/stac-api-spec/blob/main/ogcapi-features/README.md#collection-pagination)
45
-
for details.
46
+
The version of this extension only defines the version of the <https://api.stacspec.org/v1.0.0/collection-search>
47
+
conformance class. All other conformance classes define their own version numbers, e.g.
48
+
Sort is already available in v1.1.0 and as such the conformance class is
- Requirement class in *OGC API - Common - Part 2: Geospatial Data*: [Simple Query](https://portal.ogc.org/files/99149#rc-simple-query-section)
53
63
54
-
A basic set of query parameters MUST be implemented.
55
-
These are aligned with the corresponding parameters in STAC API - Features and OGC API - Records:
56
-
-[`bbox`](https://docs.ogc.org/DRAFTS/20-004.html#_parameter_bbox) (intersection of the given `bbox` with any of the spatial extent provided in a STAC Collection at `extent.spatial.bbox`)
57
-
-[`datetime`](https://docs.ogc.org/DRAFTS/20-004.html#_parameter_datetime) (intersection of the given `datetime` with any of the temporal extent provided in a STAC Collection at `extent.temporal.interval`)
This defines a basic set of query parameters for spatial and temporal querying, plus pagination.
65
+
Implementations of Collection Search MUST implemented the following three parameters:
59
66
60
-
### Extensions
67
+
-[`bbox`](https://docs.ogc.org/is/20-004r1/20-004r1.html#_parameter_bbox): Spatal filtering, i.e. the intersection of the given `bbox` with any of the spatial extents provided in a STAC Collection for the path `extent.spatial.bbox`.
68
+
-[`datetime`](https://docs.ogc.org/is/20-004r1/20-004r1.html#_parameter_datetime): Temporal filtering, i.e. the intersection of the given `datetime` with any of the temporal extents provided in a STAC Collection for the path `extent.temporal.interval`.
69
+
-[`limit`](https://docs.ogc.org/is/20-004r1/20-004r1.html#_parameter_limit): Limits the page size.
61
70
62
-
#### Free text search
71
+
The parameters are all aligned with the corresponding parameters in STAC API - Features and OGC API - Records.
- Requirement class in *OGC API - Records*: [Simple Query](https://portal.ogc.org/files/99149#rc-simple-query-section)
81
+
82
+
This defines a new parameter, `q` that allows the user to perform free-text queries against STAC Collection metadata.
83
+
You have to choose to **either** implement Basic or Advanced free-text search.
84
+
This extension recommends to implement the Basic free-text search due to its simplicity.
85
+
86
+
The authoritative specification is the [STAC API - Free-Text Search Extension](https://github.com/stac-api-extensions/freetext-search)
87
+
and this chapter is only a summary of the extension in the context of the Collection Search Extension.
88
+
The basic (but *not* the advanced) free-text search is also aligned with [OGC API - Records](https://docs.ogc.org/is/20-004r1/20-004r1.html#core-query-parameters-q).
68
89
69
90
The specific set of text fields of a Collection to which the parameter is applied is left to the discretion of the implementation, but a recommendation is to at least consider `title`, `description` and `keywords`.
70
91
71
-
The search works case-insensitive and spaces have no special meaning.
72
-
Any of the search terms must be present in the set of text fields (OR operaror).
92
+
For basic free-text search, the search works case-insensitive and spaces have no special meaning, which means
93
+
any of the search terms must be present in the set of text fields.
94
+
Commas act as separator between terms and reflect an *OR* operator.
95
+
For example, `q=EO,Earth Observation` would search for "Earth Observation" or "EO".
73
96
74
-
- In HTTP `GET` requests, all search terms must be separated by a comma. For example, if you want to search for "Earth Observation" or "EO", your query parameter should be as follows: `q=EO,Earth Observation`.
75
-
- In HTTP `POST` requests, an array of search terms must be provided, for example: `{"q": ["EO", "Earth Observation"]}`.
- Requirement class in *OGC API - Records*: [Local Resource Catalogue, CQL Filter](https://docs.ogc.org/is/20-004r1/20-004r1.html#clause-local-resources-catalog_filtering)
- Requirement class in *OGC API - Records*: [Local Resource Catalogue, CQL Filter](https://docs.ogc.org/DRAFTS/20-004.html#clause-local-resources-catalogue_cql2-filter)
102
+
The Filter extension provides an expressive mechanism for searching based on Collection fields.
81
103
82
-
The filter extension for CQL support can be implemented, too.
83
-
See <https://github.com/stac-api-extensions/filter> for details.
84
-
It works as it does for Items, except that the queryables link for Collection Search is located in the response of `GET /collections` (property `links`).
85
-
The path/endpoint for Collection Search queryables can be freely chosen, but SHOULD NOT conflict with `GET /queryables`.
104
+
The authoritative specification is the [STAC API - Filter Extension](https://github.com/stac-api-extensions/filter)
105
+
and this chapter is only a summary of the extension in the context of the Collection Search Extension.
86
106
87
-
#### Query (STACQL)
107
+
In general, the extension works for Collections exactly as it works for Items, with the following notable differences:
- Requirement class in *OGC API - Records*: [Local Resource Catalogue, Sorting](https://docs.ogc.org/DRAFTS/20-004.html#clause-local-resources-catalogue_sorting)
122
+
- Requirement class in *OGC API - Records*: [Local Resource Catalogue, Sorting](https://docs.ogc.org/is/20-004r1/20-004r1.html#clause-local-resources-catalog_sorting)
123
+
124
+
The Sort extension provides a simple but extensible mechanism to order search results according to certain properties.
125
+
126
+
The authoritative specification is the [STAC API - Sort Extension](https://github.com/stac-api-extensions/sort)
127
+
and this chapter is only a summary of the extension in the context of the Collection Search Extension.
128
+
129
+
In general, the extension works for Collections exactly as it works for Items, with the following notable differences:
130
+
131
+
- It is implemented for `GET /collections` and sorts STAC Collections accordingly
132
+
- The link to the sortables endpoint for Collection Search is located in the response of `GET /collections` (property `links`)
133
+
- The path/endpoint for Collection Search sortables can be freely chosen, but SHOULD NOT conflict with `GET /sortables`
98
134
99
-
The sort extension can be implemented, too. It works as it does for Items.
100
-
See <https://github.com/stac-api-extensions/sort> for details.
135
+
Additionally, Items and Collections have differences in (common) availability of properties and their location within the document.
| Sort by creation time | created | properties.created |
101
144
102
145
Note that Items and Collections have differences in (common) availability of properties and their location within the document. You can find some examples below:
103
146
@@ -110,7 +153,14 @@ Note that Items and Collections have differences in (common) availability of pro
0 commit comments