stac-fastapi.core 3.0.0a2__tar.gz → 3.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/PKG-INFO +123 -91
  2. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/README.md +118 -87
  3. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/setup.py +4 -3
  4. stac_fastapi_core-3.1.0/stac_fastapi/core/basic_auth.py +61 -0
  5. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/core.py +39 -13
  6. stac_fastapi_core-3.1.0/stac_fastapi/core/extensions/aggregation.py +542 -0
  7. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/extensions/filter.py +25 -15
  8. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/models/links.py +26 -0
  9. stac_fastapi_core-3.1.0/stac_fastapi/core/route_dependencies.py +176 -0
  10. stac_fastapi_core-3.1.0/stac_fastapi/core/version.py +2 -0
  11. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/PKG-INFO +123 -91
  12. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/SOURCES.txt +2 -0
  13. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/requires.txt +4 -3
  14. stac_fastapi_core-3.0.0a2/stac_fastapi/core/basic_auth.py +0 -115
  15. stac_fastapi_core-3.0.0a2/stac_fastapi/core/version.py +0 -2
  16. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/setup.cfg +0 -0
  17. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/__init__.py +0 -0
  18. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/base_database_logic.py +0 -0
  19. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/base_settings.py +0 -0
  20. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/datetime_utils.py +0 -0
  21. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/extensions/__init__.py +0 -0
  22. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/extensions/fields.py +0 -0
  23. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/extensions/query.py +0 -0
  24. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/models/__init__.py +0 -0
  25. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/models/search.py +0 -0
  26. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/serializers.py +0 -0
  27. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/session.py +0 -0
  28. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/utilities.py +0 -0
  29. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/dependency_links.txt +0 -0
  30. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/not-zip-safe +0 -0
  31. {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: stac-fastapi.core
3
- Version: 3.0.0a2
3
+ Version: 3.1.0
4
4
  Summary: Core library for the Elasticsearch and Opensearch stac-fastapi backends.
5
5
  Home-page: https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch
6
6
  License: MIT
@@ -19,14 +19,15 @@ Requires-Dist: fastapi-slim
19
19
  Requires-Dist: attrs>=23.2.0
20
20
  Requires-Dist: pydantic[dotenv]
21
21
  Requires-Dist: stac_pydantic>=3
22
- Requires-Dist: stac-fastapi.types==3.0.0a3
23
- Requires-Dist: stac-fastapi.api==3.0.0a3
24
- Requires-Dist: stac-fastapi.extensions==3.0.0a3
22
+ Requires-Dist: stac-fastapi.types==3.0.0
23
+ Requires-Dist: stac-fastapi.api==3.0.0
24
+ Requires-Dist: stac-fastapi.extensions==3.0.0
25
25
  Requires-Dist: orjson
26
26
  Requires-Dist: overrides
27
27
  Requires-Dist: geojson-pydantic
28
28
  Requires-Dist: pygeofilter==0.2.1
29
29
  Requires-Dist: typing_extensions==4.8.0
30
+ Requires-Dist: jsonschema
30
31
 
31
32
  # stac-fastapi-elasticsearch-opensearch (sfeos)
32
33
 
@@ -39,9 +40,9 @@ Requires-Dist: typing_extensions==4.8.0
39
40
  </p>
40
41
 
41
42
 
42
- [![PyPI version](https://badge.fury.io/py/stac-fastapi.elasticsearch.svg)](https://badge.fury.io/py/stac-fastapi.elasticsearch)
43
+ [![PyPI version](https://badge.fury.io/py/stac-fastapi.elasticsearch.svg)](https://badge.fury.io/py/stac-fastapi.elasticsearch)
43
44
  [![Join the chat at https://gitter.im/stac-fastapi-elasticsearch/community](https://badges.gitter.im/stac-fastapi-elasticsearch/community.svg)](https://gitter.im/stac-fastapi-elasticsearch/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
44
-
45
+
45
46
 
46
47
  ---
47
48
 
@@ -52,15 +53,15 @@ Requires-Dist: typing_extensions==4.8.0
52
53
 
53
54
  ---
54
55
 
55
- ### Notes:
56
+ ### Notes:
56
57
 
57
- - Our Api core library can be used to create custom backends. See [stac-fastapi-mongo](https://github.com/Healy-Hyperspatial/stac-fastapi-mongo) for a working example.
58
+ - Our Api core library can be used to create custom backends. See [stac-fastapi-mongo](https://github.com/Healy-Hyperspatial/stac-fastapi-mongo) for a working example.
58
59
  - Reach out on our [Gitter](https://app.gitter.im/#/room/#stac-fastapi-elasticsearch_community:gitter.im) channel or feel free to add to our [Discussions](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/discussions) page here on github.
59
60
  - There is [Postman](https://documenter.getpostman.com/view/12888943/2s8ZDSdRHA) documentation here for examples on how to run some of the API routes locally - after starting the elasticsearch backend via the docker-compose.yml file.
60
- - The `/examples` folder shows an example of running stac-fastapi-elasticsearch from PyPI in docker without needing any code from the repository. There is also a Postman collection here that you can load into Postman for testing the API routes.
61
-
62
- - For changes, see the [Changelog](CHANGELOG.md)
63
- - We are always welcoming contributions. For the development notes: [Contributing](CONTRIBUTING.md)
61
+ - The `/examples` folder shows an example of running stac-fastapi-elasticsearch from PyPI in docker without needing any code from the repository. There is also a Postman collection here that you can load into Postman for testing the API routes.
62
+
63
+ - For changes, see the [Changelog](CHANGELOG.md)
64
+ - We are always welcoming contributions. For the development notes: [Contributing](CONTRIBUTING.md)
64
65
 
65
66
 
66
67
  ### To install from PyPI:
@@ -68,25 +69,25 @@ Requires-Dist: typing_extensions==4.8.0
68
69
  ```shell
69
70
  pip install stac_fastapi.elasticsearch
70
71
  ```
71
- or
72
+ or
72
73
  ```
73
74
  pip install stac_fastapi.opensearch
74
75
  ```
75
-
76
+
76
77
  ## Build Elasticsearch API backend
77
78
 
78
79
  ```shell
79
80
  docker-compose up elasticsearch
80
81
  docker-compose build app-elasticsearch
81
82
  ```
82
-
83
+
83
84
  ## Running Elasticsearch API on localhost:8080
84
85
 
85
86
  ```shell
86
87
  docker-compose up app-elasticsearch
87
88
  ```
88
89
 
89
- By default, docker-compose uses Elasticsearch 8.x and OpenSearch 2.11.1.
90
+ By default, docker-compose uses Elasticsearch 8.x and OpenSearch 2.11.1.
90
91
  If you wish to use a different version, put the following in a
91
92
  file named `.env` in the same directory you run docker-compose from:
92
93
 
@@ -106,7 +107,7 @@ curl -X "POST" "http://localhost:8080/collections" \
106
107
  }'
107
108
  ```
108
109
 
109
- Note: this "Collections Transaction" behavior is not part of the STAC API, but may be soon.
110
+ Note: this "Collections Transaction" behavior is not part of the STAC API, but may be soon.
110
111
 
111
112
  ## Configure the API
112
113
 
@@ -121,12 +122,12 @@ The application root path is left as the base url by default. If deploying to AW
121
122
  The collections route handles optional `limit` and `token` parameters. The `links` field that is
122
123
  returned from the `/collections` route contains a `next` link with the token that can be used to
123
124
  get the next page of results.
124
-
125
+
125
126
  ```shell
126
127
  curl -X "GET" "http://localhost:8080/collections?limit=1&token=example_token"
127
128
  ```
128
129
 
129
- ## Ingesting Sample Data CLI Tool
130
+ ## Ingesting Sample Data CLI Tool
130
131
 
131
132
  ```shell
132
133
  Usage: data_loader.py [OPTIONS]
@@ -144,12 +145,12 @@ Options:
144
145
 
145
146
  ```shell
146
147
  python3 data_loader.py --base-url http://localhost:8080
147
- ```
148
+ ```
148
149
 
149
150
 
150
151
  ## Elasticsearch Mappings
151
152
 
152
- Mappings apply to search index, not source. The mappings are stored in index templates on application startup.
153
+ Mappings apply to search index, not source. The mappings are stored in index templates on application startup.
153
154
  These templates will be used implicitly when creating new Collection and Item indices.
154
155
 
155
156
 
@@ -305,81 +306,112 @@ curl -X "POST" "http://localhost:9200/_aliases" \
305
306
  The modified Items with lowercase identifiers will now be visible to users accessing `my-collection` in the STAC API.
306
307
 
307
308
 
308
- ## Basic Auth
309
+ ## Auth
309
310
 
310
- #### Environment Variable Configuration
311
+ Authentication is an optional feature that can be enabled through `Route Dependencies` examples can be found and a more detailed explanation in [examples/auth](examples/auth).
311
312
 
312
- Basic authentication is an optional feature. You can enable it by setting the environment variable `BASIC_AUTH` as a JSON string.
313
313
 
314
- Example:
315
- ```
316
- BASIC_AUTH={"users":[{"username":"user","password":"pass","permissions":"*"}]}
317
- ```
318
-
319
- ### User Permissions Configuration
320
-
321
- In order to set endpoints with specific access permissions, you can configure the `users` key with a list of user objects. Each user object should contain the username, password, and their respective permissions.
322
-
323
- Example: This example illustrates the configuration for two users: an **admin** user with full permissions (*) and a **reader** user with limited permissions to specific read-only endpoints.
324
- ```json
325
- {
326
- "users": [
327
- {
328
- "username": "admin",
329
- "password": "admin",
330
- "permissions": "*"
331
- },
332
- {
333
- "username": "reader",
334
- "password": "reader",
335
- "permissions": [
336
- {"path": "/", "method": ["GET"]},
337
- {"path": "/conformance", "method": ["GET"]},
338
- {"path": "/collections/{collection_id}/items/{item_id}", "method": ["GET"]},
339
- {"path": "/search", "method": ["GET", "POST"]},
340
- {"path": "/collections", "method": ["GET"]},
341
- {"path": "/collections/{collection_id}", "method": ["GET"]},
342
- {"path": "/collections/{collection_id}/items", "method": ["GET"]},
343
- {"path": "/queryables", "method": ["GET"]},
344
- {"path": "/queryables/collections/{collection_id}/queryables", "method": ["GET"]},
345
- {"path": "/_mgmt/ping", "method": ["GET"]}
346
- ]
347
- }
348
- ]
349
- }
350
- ```
314
+ ## Aggregation
351
315
 
316
+ Sfeos supports the STAC API [Aggregation Extension](https://github.com/stac-api-extensions/aggregation). This enables geospatial aggregation of points and geometries, as well as frequency distribution aggregation of any other property including dates. Aggregations can be defined at the root Catalog level (`/aggregations`) and at the Collection level (`/<collection_id>/aggregations`). The `/aggregate` route also fully supports base search and the STAC API [Filter Extension](https://github.com/stac-api-extensions/filter). Any query made with `/search` may also be executed with `/aggregate`, provided that the relevant aggregation fields are available,
352
317
 
353
- ### Public Endpoints Configuration
354
318
 
355
- In order to set endpoints with public access, you can configure the public_endpoints key with a list of endpoint objects. Each endpoint object should specify the path and method of the endpoint.
319
+ A field named `aggregations` should be added to the Collection object for the collection for which the aggregations are available, for example:
356
320
 
357
- Example: This example demonstrates the configuration for public endpoints, allowing access without authentication to read-only endpoints.
358
321
  ```json
359
- {
360
- "public_endpoints": [
361
- {"path": "/", "method": "GET"},
362
- {"path": "/conformance", "method": "GET"},
363
- {"path": "/collections/{collection_id}/items/{item_id}", "method": "GET"},
364
- {"path": "/search", "method": "GET"},
365
- {"path": "/search", "method": "POST"},
366
- {"path": "/collections", "method": "GET"},
367
- {"path": "/collections/{collection_id}", "method": "GET"},
368
- {"path": "/collections/{collection_id}/items", "method": "GET"},
369
- {"path": "/queryables", "method": "GET"},
370
- {"path": "/queryables/collections/{collection_id}/queryables", "method": "GET"},
371
- {"path": "/_mgmt/ping", "method": "GET"}
372
- ],
373
- "users": [
374
- {
375
- "username": "admin",
376
- "password": "admin",
377
- "permissions": "*"
378
- }
379
- ]
380
- }
381
- ```
382
-
383
- ### Docker Compose Configurations
384
-
385
- See `docker-compose.basic_auth_protected.yml` and `docker-compose.basic_auth_public.yml` for basic authentication configurations.
322
+ "aggregations": [
323
+ {
324
+ "name": "total_count",
325
+ "data_type": "integer"
326
+ },
327
+ {
328
+ "name": "datetime_max",
329
+ "data_type": "datetime"
330
+ },
331
+ {
332
+ "name": "datetime_min",
333
+ "data_type": "datetime"
334
+ },
335
+ {
336
+ "name": "datetime_frequency",
337
+ "data_type": "frequency_distribution",
338
+ "frequency_distribution_data_type": "datetime"
339
+ },
340
+ {
341
+ "name": "sun_elevation_frequency",
342
+ "data_type": "frequency_distribution",
343
+ "frequency_distribution_data_type": "numeric"
344
+ },
345
+ {
346
+ "name": "platform_frequency",
347
+ "data_type": "frequency_distribution",
348
+ "frequency_distribution_data_type": "string"
349
+ },
350
+ {
351
+ "name": "sun_azimuth_frequency",
352
+ "data_type": "frequency_distribution",
353
+ "frequency_distribution_data_type": "numeric"
354
+ },
355
+ {
356
+ "name": "off_nadir_frequency",
357
+ "data_type": "frequency_distribution",
358
+ "frequency_distribution_data_type": "numeric"
359
+ },
360
+ {
361
+ "name": "cloud_cover_frequency",
362
+ "data_type": "frequency_distribution",
363
+ "frequency_distribution_data_type": "numeric"
364
+ },
365
+ {
366
+ "name": "grid_code_frequency",
367
+ "data_type": "frequency_distribution",
368
+ "frequency_distribution_data_type": "string"
369
+ },
370
+ {
371
+ "name": "centroid_geohash_grid_frequency",
372
+ "data_type": "frequency_distribution",
373
+ "frequency_distribution_data_type": "string"
374
+ },
375
+ {
376
+ "name": "centroid_geohex_grid_frequency",
377
+ "data_type": "frequency_distribution",
378
+ "frequency_distribution_data_type": "string"
379
+ },
380
+ {
381
+ "name": "centroid_geotile_grid_frequency",
382
+ "data_type": "frequency_distribution",
383
+ "frequency_distribution_data_type": "string"
384
+ },
385
+ {
386
+ "name": "geometry_geohash_grid_frequency",
387
+ "data_type": "frequency_distribution",
388
+ "frequency_distribution_data_type": "numeric"
389
+ },
390
+ {
391
+ "name": "geometry_geotile_grid_frequency",
392
+ "data_type": "frequency_distribution",
393
+ "frequency_distribution_data_type": "string"
394
+ }
395
+ ]
396
+ ```
397
+
398
+ Available aggregations are:
399
+
400
+ - total_count (count of total items)
401
+ - collection_frequency (Item `collection` field)
402
+ - platform_frequency (Item.Properties.platform)
403
+ - cloud_cover_frequency (Item.Properties.eo:cloud_cover)
404
+ - datetime_frequency (Item.Properties.datetime, monthly interval)
405
+ - datetime_min (earliest Item.Properties.datetime)
406
+ - datetime_max (latest Item.Properties.datetime)
407
+ - sun_elevation_frequency (Item.Properties.view:sun_elevation)
408
+ - sun_azimuth_frequency (Item.Properties.view:sun_azimuth)
409
+ - off_nadir_frequency (Item.Properties.view:off_nadir)
410
+ - grid_code_frequency (Item.Properties.grid:code)
411
+ - centroid_geohash_grid_frequency ([geohash grid](https://opensearch.org/docs/latest/aggregations/bucket/geohash-grid/) on Item.Properties.proj:centroid)
412
+ - centroid_geohex_grid_frequency ([geohex grid](https://opensearch.org/docs/latest/aggregations/bucket/geohex-grid/) on Item.Properties.proj:centroid)
413
+ - centroid_geotile_grid_frequency (geotile on Item.Properties.proj:centroid)
414
+ - geometry_geohash_grid_frequency ([geohash grid](https://opensearch.org/docs/latest/aggregations/bucket/geohash-grid/) on Item.geometry)
415
+ - geometry_geotile_grid_frequency ([geotile grid](https://opensearch.org/docs/latest/aggregations/bucket/geotile-grid/) on Item.geometry)
416
+
417
+ Support for additional fields and new aggregations can be added in the associated `database_logic.py` file.
@@ -9,9 +9,9 @@
9
9
  </p>
10
10
 
11
11
 
12
- [![PyPI version](https://badge.fury.io/py/stac-fastapi.elasticsearch.svg)](https://badge.fury.io/py/stac-fastapi.elasticsearch)
12
+ [![PyPI version](https://badge.fury.io/py/stac-fastapi.elasticsearch.svg)](https://badge.fury.io/py/stac-fastapi.elasticsearch)
13
13
  [![Join the chat at https://gitter.im/stac-fastapi-elasticsearch/community](https://badges.gitter.im/stac-fastapi-elasticsearch/community.svg)](https://gitter.im/stac-fastapi-elasticsearch/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
14
-
14
+
15
15
 
16
16
  ---
17
17
 
@@ -22,15 +22,15 @@
22
22
 
23
23
  ---
24
24
 
25
- ### Notes:
25
+ ### Notes:
26
26
 
27
- - Our Api core library can be used to create custom backends. See [stac-fastapi-mongo](https://github.com/Healy-Hyperspatial/stac-fastapi-mongo) for a working example.
27
+ - Our Api core library can be used to create custom backends. See [stac-fastapi-mongo](https://github.com/Healy-Hyperspatial/stac-fastapi-mongo) for a working example.
28
28
  - Reach out on our [Gitter](https://app.gitter.im/#/room/#stac-fastapi-elasticsearch_community:gitter.im) channel or feel free to add to our [Discussions](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/discussions) page here on github.
29
29
  - There is [Postman](https://documenter.getpostman.com/view/12888943/2s8ZDSdRHA) documentation here for examples on how to run some of the API routes locally - after starting the elasticsearch backend via the docker-compose.yml file.
30
- - The `/examples` folder shows an example of running stac-fastapi-elasticsearch from PyPI in docker without needing any code from the repository. There is also a Postman collection here that you can load into Postman for testing the API routes.
31
-
32
- - For changes, see the [Changelog](CHANGELOG.md)
33
- - We are always welcoming contributions. For the development notes: [Contributing](CONTRIBUTING.md)
30
+ - The `/examples` folder shows an example of running stac-fastapi-elasticsearch from PyPI in docker without needing any code from the repository. There is also a Postman collection here that you can load into Postman for testing the API routes.
31
+
32
+ - For changes, see the [Changelog](CHANGELOG.md)
33
+ - We are always welcoming contributions. For the development notes: [Contributing](CONTRIBUTING.md)
34
34
 
35
35
 
36
36
  ### To install from PyPI:
@@ -38,25 +38,25 @@
38
38
  ```shell
39
39
  pip install stac_fastapi.elasticsearch
40
40
  ```
41
- or
41
+ or
42
42
  ```
43
43
  pip install stac_fastapi.opensearch
44
44
  ```
45
-
45
+
46
46
  ## Build Elasticsearch API backend
47
47
 
48
48
  ```shell
49
49
  docker-compose up elasticsearch
50
50
  docker-compose build app-elasticsearch
51
51
  ```
52
-
52
+
53
53
  ## Running Elasticsearch API on localhost:8080
54
54
 
55
55
  ```shell
56
56
  docker-compose up app-elasticsearch
57
57
  ```
58
58
 
59
- By default, docker-compose uses Elasticsearch 8.x and OpenSearch 2.11.1.
59
+ By default, docker-compose uses Elasticsearch 8.x and OpenSearch 2.11.1.
60
60
  If you wish to use a different version, put the following in a
61
61
  file named `.env` in the same directory you run docker-compose from:
62
62
 
@@ -76,7 +76,7 @@ curl -X "POST" "http://localhost:8080/collections" \
76
76
  }'
77
77
  ```
78
78
 
79
- Note: this "Collections Transaction" behavior is not part of the STAC API, but may be soon.
79
+ Note: this "Collections Transaction" behavior is not part of the STAC API, but may be soon.
80
80
 
81
81
  ## Configure the API
82
82
 
@@ -91,12 +91,12 @@ The application root path is left as the base url by default. If deploying to AW
91
91
  The collections route handles optional `limit` and `token` parameters. The `links` field that is
92
92
  returned from the `/collections` route contains a `next` link with the token that can be used to
93
93
  get the next page of results.
94
-
94
+
95
95
  ```shell
96
96
  curl -X "GET" "http://localhost:8080/collections?limit=1&token=example_token"
97
97
  ```
98
98
 
99
- ## Ingesting Sample Data CLI Tool
99
+ ## Ingesting Sample Data CLI Tool
100
100
 
101
101
  ```shell
102
102
  Usage: data_loader.py [OPTIONS]
@@ -114,12 +114,12 @@ Options:
114
114
 
115
115
  ```shell
116
116
  python3 data_loader.py --base-url http://localhost:8080
117
- ```
117
+ ```
118
118
 
119
119
 
120
120
  ## Elasticsearch Mappings
121
121
 
122
- Mappings apply to search index, not source. The mappings are stored in index templates on application startup.
122
+ Mappings apply to search index, not source. The mappings are stored in index templates on application startup.
123
123
  These templates will be used implicitly when creating new Collection and Item indices.
124
124
 
125
125
 
@@ -275,81 +275,112 @@ curl -X "POST" "http://localhost:9200/_aliases" \
275
275
  The modified Items with lowercase identifiers will now be visible to users accessing `my-collection` in the STAC API.
276
276
 
277
277
 
278
- ## Basic Auth
278
+ ## Auth
279
279
 
280
- #### Environment Variable Configuration
280
+ Authentication is an optional feature that can be enabled through `Route Dependencies` examples can be found and a more detailed explanation in [examples/auth](examples/auth).
281
281
 
282
- Basic authentication is an optional feature. You can enable it by setting the environment variable `BASIC_AUTH` as a JSON string.
283
282
 
284
- Example:
285
- ```
286
- BASIC_AUTH={"users":[{"username":"user","password":"pass","permissions":"*"}]}
287
- ```
288
-
289
- ### User Permissions Configuration
290
-
291
- In order to set endpoints with specific access permissions, you can configure the `users` key with a list of user objects. Each user object should contain the username, password, and their respective permissions.
292
-
293
- Example: This example illustrates the configuration for two users: an **admin** user with full permissions (*) and a **reader** user with limited permissions to specific read-only endpoints.
294
- ```json
295
- {
296
- "users": [
297
- {
298
- "username": "admin",
299
- "password": "admin",
300
- "permissions": "*"
301
- },
302
- {
303
- "username": "reader",
304
- "password": "reader",
305
- "permissions": [
306
- {"path": "/", "method": ["GET"]},
307
- {"path": "/conformance", "method": ["GET"]},
308
- {"path": "/collections/{collection_id}/items/{item_id}", "method": ["GET"]},
309
- {"path": "/search", "method": ["GET", "POST"]},
310
- {"path": "/collections", "method": ["GET"]},
311
- {"path": "/collections/{collection_id}", "method": ["GET"]},
312
- {"path": "/collections/{collection_id}/items", "method": ["GET"]},
313
- {"path": "/queryables", "method": ["GET"]},
314
- {"path": "/queryables/collections/{collection_id}/queryables", "method": ["GET"]},
315
- {"path": "/_mgmt/ping", "method": ["GET"]}
316
- ]
317
- }
318
- ]
319
- }
320
- ```
283
+ ## Aggregation
321
284
 
285
+ Sfeos supports the STAC API [Aggregation Extension](https://github.com/stac-api-extensions/aggregation). This enables geospatial aggregation of points and geometries, as well as frequency distribution aggregation of any other property including dates. Aggregations can be defined at the root Catalog level (`/aggregations`) and at the Collection level (`/<collection_id>/aggregations`). The `/aggregate` route also fully supports base search and the STAC API [Filter Extension](https://github.com/stac-api-extensions/filter). Any query made with `/search` may also be executed with `/aggregate`, provided that the relevant aggregation fields are available,
322
286
 
323
- ### Public Endpoints Configuration
324
287
 
325
- In order to set endpoints with public access, you can configure the public_endpoints key with a list of endpoint objects. Each endpoint object should specify the path and method of the endpoint.
288
+ A field named `aggregations` should be added to the Collection object for the collection for which the aggregations are available, for example:
326
289
 
327
- Example: This example demonstrates the configuration for public endpoints, allowing access without authentication to read-only endpoints.
328
290
  ```json
329
- {
330
- "public_endpoints": [
331
- {"path": "/", "method": "GET"},
332
- {"path": "/conformance", "method": "GET"},
333
- {"path": "/collections/{collection_id}/items/{item_id}", "method": "GET"},
334
- {"path": "/search", "method": "GET"},
335
- {"path": "/search", "method": "POST"},
336
- {"path": "/collections", "method": "GET"},
337
- {"path": "/collections/{collection_id}", "method": "GET"},
338
- {"path": "/collections/{collection_id}/items", "method": "GET"},
339
- {"path": "/queryables", "method": "GET"},
340
- {"path": "/queryables/collections/{collection_id}/queryables", "method": "GET"},
341
- {"path": "/_mgmt/ping", "method": "GET"}
342
- ],
343
- "users": [
344
- {
345
- "username": "admin",
346
- "password": "admin",
347
- "permissions": "*"
348
- }
349
- ]
350
- }
351
- ```
352
-
353
- ### Docker Compose Configurations
354
-
355
- See `docker-compose.basic_auth_protected.yml` and `docker-compose.basic_auth_public.yml` for basic authentication configurations.
291
+ "aggregations": [
292
+ {
293
+ "name": "total_count",
294
+ "data_type": "integer"
295
+ },
296
+ {
297
+ "name": "datetime_max",
298
+ "data_type": "datetime"
299
+ },
300
+ {
301
+ "name": "datetime_min",
302
+ "data_type": "datetime"
303
+ },
304
+ {
305
+ "name": "datetime_frequency",
306
+ "data_type": "frequency_distribution",
307
+ "frequency_distribution_data_type": "datetime"
308
+ },
309
+ {
310
+ "name": "sun_elevation_frequency",
311
+ "data_type": "frequency_distribution",
312
+ "frequency_distribution_data_type": "numeric"
313
+ },
314
+ {
315
+ "name": "platform_frequency",
316
+ "data_type": "frequency_distribution",
317
+ "frequency_distribution_data_type": "string"
318
+ },
319
+ {
320
+ "name": "sun_azimuth_frequency",
321
+ "data_type": "frequency_distribution",
322
+ "frequency_distribution_data_type": "numeric"
323
+ },
324
+ {
325
+ "name": "off_nadir_frequency",
326
+ "data_type": "frequency_distribution",
327
+ "frequency_distribution_data_type": "numeric"
328
+ },
329
+ {
330
+ "name": "cloud_cover_frequency",
331
+ "data_type": "frequency_distribution",
332
+ "frequency_distribution_data_type": "numeric"
333
+ },
334
+ {
335
+ "name": "grid_code_frequency",
336
+ "data_type": "frequency_distribution",
337
+ "frequency_distribution_data_type": "string"
338
+ },
339
+ {
340
+ "name": "centroid_geohash_grid_frequency",
341
+ "data_type": "frequency_distribution",
342
+ "frequency_distribution_data_type": "string"
343
+ },
344
+ {
345
+ "name": "centroid_geohex_grid_frequency",
346
+ "data_type": "frequency_distribution",
347
+ "frequency_distribution_data_type": "string"
348
+ },
349
+ {
350
+ "name": "centroid_geotile_grid_frequency",
351
+ "data_type": "frequency_distribution",
352
+ "frequency_distribution_data_type": "string"
353
+ },
354
+ {
355
+ "name": "geometry_geohash_grid_frequency",
356
+ "data_type": "frequency_distribution",
357
+ "frequency_distribution_data_type": "numeric"
358
+ },
359
+ {
360
+ "name": "geometry_geotile_grid_frequency",
361
+ "data_type": "frequency_distribution",
362
+ "frequency_distribution_data_type": "string"
363
+ }
364
+ ]
365
+ ```
366
+
367
+ Available aggregations are:
368
+
369
+ - total_count (count of total items)
370
+ - collection_frequency (Item `collection` field)
371
+ - platform_frequency (Item.Properties.platform)
372
+ - cloud_cover_frequency (Item.Properties.eo:cloud_cover)
373
+ - datetime_frequency (Item.Properties.datetime, monthly interval)
374
+ - datetime_min (earliest Item.Properties.datetime)
375
+ - datetime_max (latest Item.Properties.datetime)
376
+ - sun_elevation_frequency (Item.Properties.view:sun_elevation)
377
+ - sun_azimuth_frequency (Item.Properties.view:sun_azimuth)
378
+ - off_nadir_frequency (Item.Properties.view:off_nadir)
379
+ - grid_code_frequency (Item.Properties.grid:code)
380
+ - centroid_geohash_grid_frequency ([geohash grid](https://opensearch.org/docs/latest/aggregations/bucket/geohash-grid/) on Item.Properties.proj:centroid)
381
+ - centroid_geohex_grid_frequency ([geohex grid](https://opensearch.org/docs/latest/aggregations/bucket/geohex-grid/) on Item.Properties.proj:centroid)
382
+ - centroid_geotile_grid_frequency (geotile on Item.Properties.proj:centroid)
383
+ - geometry_geohash_grid_frequency ([geohash grid](https://opensearch.org/docs/latest/aggregations/bucket/geohash-grid/) on Item.geometry)
384
+ - geometry_geotile_grid_frequency ([geotile grid](https://opensearch.org/docs/latest/aggregations/bucket/geotile-grid/) on Item.geometry)
385
+
386
+ Support for additional fields and new aggregations can be added in the associated `database_logic.py` file.
@@ -10,14 +10,15 @@ install_requires = [
10
10
  "attrs>=23.2.0",
11
11
  "pydantic[dotenv]",
12
12
  "stac_pydantic>=3",
13
- "stac-fastapi.types==3.0.0a3",
14
- "stac-fastapi.api==3.0.0a3",
15
- "stac-fastapi.extensions==3.0.0a3",
13
+ "stac-fastapi.types==3.0.0",
14
+ "stac-fastapi.api==3.0.0",
15
+ "stac-fastapi.extensions==3.0.0",
16
16
  "orjson",
17
17
  "overrides",
18
18
  "geojson-pydantic",
19
19
  "pygeofilter==0.2.1",
20
20
  "typing_extensions==4.8.0",
21
+ "jsonschema",
21
22
  ]
22
23
 
23
24
  setup(