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.
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/PKG-INFO +123 -91
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/README.md +118 -87
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/setup.py +4 -3
- stac_fastapi_core-3.1.0/stac_fastapi/core/basic_auth.py +61 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/core.py +39 -13
- stac_fastapi_core-3.1.0/stac_fastapi/core/extensions/aggregation.py +542 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/extensions/filter.py +25 -15
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/models/links.py +26 -0
- stac_fastapi_core-3.1.0/stac_fastapi/core/route_dependencies.py +176 -0
- stac_fastapi_core-3.1.0/stac_fastapi/core/version.py +2 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/PKG-INFO +123 -91
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/SOURCES.txt +2 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/requires.txt +4 -3
- stac_fastapi_core-3.0.0a2/stac_fastapi/core/basic_auth.py +0 -115
- stac_fastapi_core-3.0.0a2/stac_fastapi/core/version.py +0 -2
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/setup.cfg +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/__init__.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/base_database_logic.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/base_settings.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/datetime_utils.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/extensions/__init__.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/extensions/fields.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/extensions/query.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/models/__init__.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/models/search.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/serializers.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/session.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi/core/utilities.py +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/dependency_links.txt +0 -0
- {stac_fastapi_core-3.0.0a2 → stac_fastapi_core-3.1.0}/stac_fastapi.core.egg-info/not-zip-safe +0 -0
- {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
|
|
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.
|
|
23
|
-
Requires-Dist: stac-fastapi.api==3.0.
|
|
24
|
-
Requires-Dist: stac-fastapi.extensions==3.0.
|
|
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
|
-
[](https://badge.fury.io/py/stac-fastapi.elasticsearch)
|
|
43
|
+
[](https://badge.fury.io/py/stac-fastapi.elasticsearch)
|
|
43
44
|
[](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
|
-
##
|
|
309
|
+
## Auth
|
|
309
310
|
|
|
310
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
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
|
-
[](https://badge.fury.io/py/stac-fastapi.elasticsearch)
|
|
12
|
+
[](https://badge.fury.io/py/stac-fastapi.elasticsearch)
|
|
13
13
|
[](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
|
-
##
|
|
278
|
+
## Auth
|
|
279
279
|
|
|
280
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
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.
|
|
14
|
-
"stac-fastapi.api==3.0.
|
|
15
|
-
"stac-fastapi.extensions==3.0.
|
|
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(
|