stac-fastapi.core 3.2.0__tar.gz → 3.2.2__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.2.0/stac_fastapi.core.egg-info → stac_fastapi.core-3.2.2}/PKG-INFO +44 -110
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/README.md +42 -108
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/setup.py +1 -1
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/version.py +1 -1
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2/stac_fastapi.core.egg-info}/PKG-INFO +43 -109
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/setup.cfg +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/__init__.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/base_database_logic.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/base_settings.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/basic_auth.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/core.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/datetime_utils.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/extensions/__init__.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/extensions/aggregation.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/extensions/fields.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/extensions/filter.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/extensions/query.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/models/__init__.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/models/links.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/models/search.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/rate_limit.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/route_dependencies.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/serializers.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/session.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/utilities.py +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi.core.egg-info/SOURCES.txt +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi.core.egg-info/dependency_links.txt +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi.core.egg-info/not-zip-safe +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi.core.egg-info/requires.txt +0 -0
- {stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi.core.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
|
-
Name:
|
|
3
|
-
Version: 3.2.
|
|
2
|
+
Name: stac_fastapi.core
|
|
3
|
+
Version: 3.2.2
|
|
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
|
|
@@ -61,17 +61,24 @@ or
|
|
|
61
61
|
pip install stac_fastapi.opensearch
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
-
|
|
64
|
+
### To install and run via pre-built Docker Images
|
|
65
|
+
|
|
66
|
+
We provide ready-to-use Docker images through GitHub Container Registry ([ElasticSearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pkgs/container/stac-fastapi-es) and [OpenSearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pkgs/container/stac-fastapi-os) backends). You can easily pull and run these images:
|
|
65
67
|
|
|
66
68
|
```shell
|
|
67
|
-
|
|
68
|
-
docker
|
|
69
|
+
# For Elasticsearch backend
|
|
70
|
+
docker pull ghcr.io/stac-utils/stac-fastapi-es:latest
|
|
71
|
+
|
|
72
|
+
# For OpenSearch backend
|
|
73
|
+
docker pull ghcr.io/stac-utils/stac-fastapi-os:latest
|
|
69
74
|
```
|
|
70
75
|
|
|
71
|
-
##
|
|
76
|
+
## Run Elasticsearch API backend on localhost:8080
|
|
77
|
+
|
|
78
|
+
You need to ensure [**Docker Compose**](https://docs.docker.com/compose/install/) or [**Podman Compose**](https://podman-desktop.io/docs/compose) installed and running on your machine. In the follwoing command instead of `docker-compose` you can use `podman-compose` as well.
|
|
72
79
|
|
|
73
80
|
```shell
|
|
74
|
-
docker-compose up app-elasticsearch
|
|
81
|
+
docker-compose up elasticsearch app-elasticsearch
|
|
75
82
|
```
|
|
76
83
|
|
|
77
84
|
By default, docker-compose uses Elasticsearch 8.x and OpenSearch 2.11.1.
|
|
@@ -84,6 +91,35 @@ OPENSEARCH_VERSION=2.11.0
|
|
|
84
91
|
```
|
|
85
92
|
The most recent Elasticsearch 7.x versions should also work. See the [opensearch-py docs](https://github.com/opensearch-project/opensearch-py/blob/main/COMPATIBILITY.md) for compatibility information.
|
|
86
93
|
|
|
94
|
+
#### **Configuration reference keys:**
|
|
95
|
+
|
|
96
|
+
You can customize additional settings in your `.env` file:
|
|
97
|
+
###### Key variables to configure:
|
|
98
|
+
|
|
99
|
+
| Variable | Description | Default | Required |
|
|
100
|
+
|------------------------------|--------------------------------------------------------------------------------------|--------------------------|---------------------------------------------------------------------------------------------|
|
|
101
|
+
| `ES_HOST` | Hostname for external Elasticsearch/OpenSearch. | `localhost` | Optional |
|
|
102
|
+
| `ES_PORT` | Port for Elasticsearch/OpenSearch. | `9200` (ES) / `9202` (OS)| Optional |
|
|
103
|
+
| `ES_USE_SSL` | Use SSL for connecting to Elasticsearch/OpenSearch. | `false` | Optional |
|
|
104
|
+
| `ES_VERIFY_CERTS` | Verify SSL certificates when connecting. | `false` | Optional |
|
|
105
|
+
| `STAC_FASTAPI_TITLE` | Title of the API in the documentation. | `stac-fastapi-elasticsearch` or `stac-fastapi-opensearch` | Optional |
|
|
106
|
+
| `STAC_FASTAPI_DESCRIPTION` | Description of the API in the documentation. | N/A | Optional |
|
|
107
|
+
| `STAC_FASTAPI_VERSION` | API version. | `2.1` | Optional |
|
|
108
|
+
| `APP_HOST` | Server bind address. | `0.0.0.0` | Optional |
|
|
109
|
+
| `APP_PORT` | Server port. | `8080` | Optional |
|
|
110
|
+
| `ENVIRONMENT` | Runtime environment. | `local` | Optional |
|
|
111
|
+
| `WEB_CONCURRENCY` | Number of worker processes. | `10` | Optional |
|
|
112
|
+
| `RELOAD` | Enable auto-reload for development. | `true` | Optional |
|
|
113
|
+
| `STAC_FASTAPI_RATE_LIMIT` | API rate limit per client. | `200/minute` | Optional |
|
|
114
|
+
| `BACKEND` | Tests-related variable | `elasticsearch` or `opensearch` based on the backend | Optional |
|
|
115
|
+
| `ELASTICSEARCH_VERSION` | ElasticSearch version | `7.17.1` | Optional |
|
|
116
|
+
| `OPENSEARCH_VERSION` | OpenSearch version | `2.11.0` | Optional |
|
|
117
|
+
|
|
118
|
+
> [!NOTE]
|
|
119
|
+
> The variables `ES_HOST`, `ES_PORT`, `ES_USE_SSL`, and `ES_VERIFY_CERTS` apply to both Elasticsearch and OpenSearch backends, so there is no need to rename the key names to `OS_` even if you're using OpenSearch.
|
|
120
|
+
|
|
121
|
+
## Interacting with the API
|
|
122
|
+
|
|
87
123
|
To create a new Collection:
|
|
88
124
|
|
|
89
125
|
```shell
|
|
@@ -297,111 +333,9 @@ The modified Items with lowercase identifiers will now be visible to users acces
|
|
|
297
333
|
|
|
298
334
|
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).
|
|
299
335
|
|
|
300
|
-
|
|
301
336
|
## Aggregation
|
|
302
337
|
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
A field named `aggregations` should be added to the Collection object for the collection for which the aggregations are available, for example:
|
|
307
|
-
|
|
308
|
-
```json
|
|
309
|
-
"aggregations": [
|
|
310
|
-
{
|
|
311
|
-
"name": "total_count",
|
|
312
|
-
"data_type": "integer"
|
|
313
|
-
},
|
|
314
|
-
{
|
|
315
|
-
"name": "datetime_max",
|
|
316
|
-
"data_type": "datetime"
|
|
317
|
-
},
|
|
318
|
-
{
|
|
319
|
-
"name": "datetime_min",
|
|
320
|
-
"data_type": "datetime"
|
|
321
|
-
},
|
|
322
|
-
{
|
|
323
|
-
"name": "datetime_frequency",
|
|
324
|
-
"data_type": "frequency_distribution",
|
|
325
|
-
"frequency_distribution_data_type": "datetime"
|
|
326
|
-
},
|
|
327
|
-
{
|
|
328
|
-
"name": "sun_elevation_frequency",
|
|
329
|
-
"data_type": "frequency_distribution",
|
|
330
|
-
"frequency_distribution_data_type": "numeric"
|
|
331
|
-
},
|
|
332
|
-
{
|
|
333
|
-
"name": "platform_frequency",
|
|
334
|
-
"data_type": "frequency_distribution",
|
|
335
|
-
"frequency_distribution_data_type": "string"
|
|
336
|
-
},
|
|
337
|
-
{
|
|
338
|
-
"name": "sun_azimuth_frequency",
|
|
339
|
-
"data_type": "frequency_distribution",
|
|
340
|
-
"frequency_distribution_data_type": "numeric"
|
|
341
|
-
},
|
|
342
|
-
{
|
|
343
|
-
"name": "off_nadir_frequency",
|
|
344
|
-
"data_type": "frequency_distribution",
|
|
345
|
-
"frequency_distribution_data_type": "numeric"
|
|
346
|
-
},
|
|
347
|
-
{
|
|
348
|
-
"name": "cloud_cover_frequency",
|
|
349
|
-
"data_type": "frequency_distribution",
|
|
350
|
-
"frequency_distribution_data_type": "numeric"
|
|
351
|
-
},
|
|
352
|
-
{
|
|
353
|
-
"name": "grid_code_frequency",
|
|
354
|
-
"data_type": "frequency_distribution",
|
|
355
|
-
"frequency_distribution_data_type": "string"
|
|
356
|
-
},
|
|
357
|
-
{
|
|
358
|
-
"name": "centroid_geohash_grid_frequency",
|
|
359
|
-
"data_type": "frequency_distribution",
|
|
360
|
-
"frequency_distribution_data_type": "string"
|
|
361
|
-
},
|
|
362
|
-
{
|
|
363
|
-
"name": "centroid_geohex_grid_frequency",
|
|
364
|
-
"data_type": "frequency_distribution",
|
|
365
|
-
"frequency_distribution_data_type": "string"
|
|
366
|
-
},
|
|
367
|
-
{
|
|
368
|
-
"name": "centroid_geotile_grid_frequency",
|
|
369
|
-
"data_type": "frequency_distribution",
|
|
370
|
-
"frequency_distribution_data_type": "string"
|
|
371
|
-
},
|
|
372
|
-
{
|
|
373
|
-
"name": "geometry_geohash_grid_frequency",
|
|
374
|
-
"data_type": "frequency_distribution",
|
|
375
|
-
"frequency_distribution_data_type": "numeric"
|
|
376
|
-
},
|
|
377
|
-
{
|
|
378
|
-
"name": "geometry_geotile_grid_frequency",
|
|
379
|
-
"data_type": "frequency_distribution",
|
|
380
|
-
"frequency_distribution_data_type": "string"
|
|
381
|
-
}
|
|
382
|
-
]
|
|
383
|
-
```
|
|
384
|
-
|
|
385
|
-
Available aggregations are:
|
|
386
|
-
|
|
387
|
-
- total_count (count of total items)
|
|
388
|
-
- collection_frequency (Item `collection` field)
|
|
389
|
-
- platform_frequency (Item.Properties.platform)
|
|
390
|
-
- cloud_cover_frequency (Item.Properties.eo:cloud_cover)
|
|
391
|
-
- datetime_frequency (Item.Properties.datetime, monthly interval)
|
|
392
|
-
- datetime_min (earliest Item.Properties.datetime)
|
|
393
|
-
- datetime_max (latest Item.Properties.datetime)
|
|
394
|
-
- sun_elevation_frequency (Item.Properties.view:sun_elevation)
|
|
395
|
-
- sun_azimuth_frequency (Item.Properties.view:sun_azimuth)
|
|
396
|
-
- off_nadir_frequency (Item.Properties.view:off_nadir)
|
|
397
|
-
- grid_code_frequency (Item.Properties.grid:code)
|
|
398
|
-
- centroid_geohash_grid_frequency ([geohash grid](https://opensearch.org/docs/latest/aggregations/bucket/geohash-grid/) on Item.Properties.proj:centroid)
|
|
399
|
-
- centroid_geohex_grid_frequency ([geohex grid](https://opensearch.org/docs/latest/aggregations/bucket/geohex-grid/) on Item.Properties.proj:centroid)
|
|
400
|
-
- centroid_geotile_grid_frequency (geotile on Item.Properties.proj:centroid)
|
|
401
|
-
- geometry_geohash_grid_frequency ([geohash grid](https://opensearch.org/docs/latest/aggregations/bucket/geohash-grid/) on Item.geometry)
|
|
402
|
-
- geometry_geotile_grid_frequency ([geotile grid](https://opensearch.org/docs/latest/aggregations/bucket/geotile-grid/) on Item.geometry)
|
|
403
|
-
|
|
404
|
-
Support for additional fields and new aggregations can be added in the associated `database_logic.py` file.
|
|
338
|
+
Aggregation of points and geometries, as well as frequency distribution aggregation of any other property including dates is supported in stac-fatsapi-elasticsearch-opensearch. Aggregations can be defined at the root Catalog level (`/aggregations`) and at the Collection level (`/<collection_id>/aggregations`). Details for supported aggregations can be found at [./docs/src/aggregation.md](./docs/src/aggregation.md)
|
|
405
339
|
|
|
406
340
|
## Rate Limiting
|
|
407
341
|
|
|
@@ -43,17 +43,24 @@ or
|
|
|
43
43
|
pip install stac_fastapi.opensearch
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
### To install and run via pre-built Docker Images
|
|
47
|
+
|
|
48
|
+
We provide ready-to-use Docker images through GitHub Container Registry ([ElasticSearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pkgs/container/stac-fastapi-es) and [OpenSearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pkgs/container/stac-fastapi-os) backends). You can easily pull and run these images:
|
|
47
49
|
|
|
48
50
|
```shell
|
|
49
|
-
|
|
50
|
-
docker
|
|
51
|
+
# For Elasticsearch backend
|
|
52
|
+
docker pull ghcr.io/stac-utils/stac-fastapi-es:latest
|
|
53
|
+
|
|
54
|
+
# For OpenSearch backend
|
|
55
|
+
docker pull ghcr.io/stac-utils/stac-fastapi-os:latest
|
|
51
56
|
```
|
|
52
57
|
|
|
53
|
-
##
|
|
58
|
+
## Run Elasticsearch API backend on localhost:8080
|
|
59
|
+
|
|
60
|
+
You need to ensure [**Docker Compose**](https://docs.docker.com/compose/install/) or [**Podman Compose**](https://podman-desktop.io/docs/compose) installed and running on your machine. In the follwoing command instead of `docker-compose` you can use `podman-compose` as well.
|
|
54
61
|
|
|
55
62
|
```shell
|
|
56
|
-
docker-compose up app-elasticsearch
|
|
63
|
+
docker-compose up elasticsearch app-elasticsearch
|
|
57
64
|
```
|
|
58
65
|
|
|
59
66
|
By default, docker-compose uses Elasticsearch 8.x and OpenSearch 2.11.1.
|
|
@@ -66,6 +73,35 @@ OPENSEARCH_VERSION=2.11.0
|
|
|
66
73
|
```
|
|
67
74
|
The most recent Elasticsearch 7.x versions should also work. See the [opensearch-py docs](https://github.com/opensearch-project/opensearch-py/blob/main/COMPATIBILITY.md) for compatibility information.
|
|
68
75
|
|
|
76
|
+
#### **Configuration reference keys:**
|
|
77
|
+
|
|
78
|
+
You can customize additional settings in your `.env` file:
|
|
79
|
+
###### Key variables to configure:
|
|
80
|
+
|
|
81
|
+
| Variable | Description | Default | Required |
|
|
82
|
+
|------------------------------|--------------------------------------------------------------------------------------|--------------------------|---------------------------------------------------------------------------------------------|
|
|
83
|
+
| `ES_HOST` | Hostname for external Elasticsearch/OpenSearch. | `localhost` | Optional |
|
|
84
|
+
| `ES_PORT` | Port for Elasticsearch/OpenSearch. | `9200` (ES) / `9202` (OS)| Optional |
|
|
85
|
+
| `ES_USE_SSL` | Use SSL for connecting to Elasticsearch/OpenSearch. | `false` | Optional |
|
|
86
|
+
| `ES_VERIFY_CERTS` | Verify SSL certificates when connecting. | `false` | Optional |
|
|
87
|
+
| `STAC_FASTAPI_TITLE` | Title of the API in the documentation. | `stac-fastapi-elasticsearch` or `stac-fastapi-opensearch` | Optional |
|
|
88
|
+
| `STAC_FASTAPI_DESCRIPTION` | Description of the API in the documentation. | N/A | Optional |
|
|
89
|
+
| `STAC_FASTAPI_VERSION` | API version. | `2.1` | Optional |
|
|
90
|
+
| `APP_HOST` | Server bind address. | `0.0.0.0` | Optional |
|
|
91
|
+
| `APP_PORT` | Server port. | `8080` | Optional |
|
|
92
|
+
| `ENVIRONMENT` | Runtime environment. | `local` | Optional |
|
|
93
|
+
| `WEB_CONCURRENCY` | Number of worker processes. | `10` | Optional |
|
|
94
|
+
| `RELOAD` | Enable auto-reload for development. | `true` | Optional |
|
|
95
|
+
| `STAC_FASTAPI_RATE_LIMIT` | API rate limit per client. | `200/minute` | Optional |
|
|
96
|
+
| `BACKEND` | Tests-related variable | `elasticsearch` or `opensearch` based on the backend | Optional |
|
|
97
|
+
| `ELASTICSEARCH_VERSION` | ElasticSearch version | `7.17.1` | Optional |
|
|
98
|
+
| `OPENSEARCH_VERSION` | OpenSearch version | `2.11.0` | Optional |
|
|
99
|
+
|
|
100
|
+
> [!NOTE]
|
|
101
|
+
> The variables `ES_HOST`, `ES_PORT`, `ES_USE_SSL`, and `ES_VERIFY_CERTS` apply to both Elasticsearch and OpenSearch backends, so there is no need to rename the key names to `OS_` even if you're using OpenSearch.
|
|
102
|
+
|
|
103
|
+
## Interacting with the API
|
|
104
|
+
|
|
69
105
|
To create a new Collection:
|
|
70
106
|
|
|
71
107
|
```shell
|
|
@@ -279,111 +315,9 @@ The modified Items with lowercase identifiers will now be visible to users acces
|
|
|
279
315
|
|
|
280
316
|
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
317
|
|
|
282
|
-
|
|
283
318
|
## Aggregation
|
|
284
319
|
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
A field named `aggregations` should be added to the Collection object for the collection for which the aggregations are available, for example:
|
|
289
|
-
|
|
290
|
-
```json
|
|
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.
|
|
320
|
+
Aggregation of points and geometries, as well as frequency distribution aggregation of any other property including dates is supported in stac-fatsapi-elasticsearch-opensearch. Aggregations can be defined at the root Catalog level (`/aggregations`) and at the Collection level (`/<collection_id>/aggregations`). Details for supported aggregations can be found at [./docs/src/aggregation.md](./docs/src/aggregation.md)
|
|
387
321
|
|
|
388
322
|
## Rate Limiting
|
|
389
323
|
|
|
@@ -23,7 +23,7 @@ install_requires = [
|
|
|
23
23
|
]
|
|
24
24
|
|
|
25
25
|
setup(
|
|
26
|
-
name="
|
|
26
|
+
name="stac_fastapi.core",
|
|
27
27
|
description="Core library for the Elasticsearch and Opensearch stac-fastapi backends.",
|
|
28
28
|
long_description=desc,
|
|
29
29
|
long_description_content_type="text/markdown",
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
"""library version."""
|
|
2
|
-
__version__ = "3.2.
|
|
2
|
+
__version__ = "3.2.2"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: stac-fastapi.core
|
|
3
|
-
Version: 3.2.
|
|
3
|
+
Version: 3.2.2
|
|
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
|
|
@@ -61,17 +61,24 @@ or
|
|
|
61
61
|
pip install stac_fastapi.opensearch
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
-
|
|
64
|
+
### To install and run via pre-built Docker Images
|
|
65
|
+
|
|
66
|
+
We provide ready-to-use Docker images through GitHub Container Registry ([ElasticSearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pkgs/container/stac-fastapi-es) and [OpenSearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pkgs/container/stac-fastapi-os) backends). You can easily pull and run these images:
|
|
65
67
|
|
|
66
68
|
```shell
|
|
67
|
-
|
|
68
|
-
docker
|
|
69
|
+
# For Elasticsearch backend
|
|
70
|
+
docker pull ghcr.io/stac-utils/stac-fastapi-es:latest
|
|
71
|
+
|
|
72
|
+
# For OpenSearch backend
|
|
73
|
+
docker pull ghcr.io/stac-utils/stac-fastapi-os:latest
|
|
69
74
|
```
|
|
70
75
|
|
|
71
|
-
##
|
|
76
|
+
## Run Elasticsearch API backend on localhost:8080
|
|
77
|
+
|
|
78
|
+
You need to ensure [**Docker Compose**](https://docs.docker.com/compose/install/) or [**Podman Compose**](https://podman-desktop.io/docs/compose) installed and running on your machine. In the follwoing command instead of `docker-compose` you can use `podman-compose` as well.
|
|
72
79
|
|
|
73
80
|
```shell
|
|
74
|
-
docker-compose up app-elasticsearch
|
|
81
|
+
docker-compose up elasticsearch app-elasticsearch
|
|
75
82
|
```
|
|
76
83
|
|
|
77
84
|
By default, docker-compose uses Elasticsearch 8.x and OpenSearch 2.11.1.
|
|
@@ -84,6 +91,35 @@ OPENSEARCH_VERSION=2.11.0
|
|
|
84
91
|
```
|
|
85
92
|
The most recent Elasticsearch 7.x versions should also work. See the [opensearch-py docs](https://github.com/opensearch-project/opensearch-py/blob/main/COMPATIBILITY.md) for compatibility information.
|
|
86
93
|
|
|
94
|
+
#### **Configuration reference keys:**
|
|
95
|
+
|
|
96
|
+
You can customize additional settings in your `.env` file:
|
|
97
|
+
###### Key variables to configure:
|
|
98
|
+
|
|
99
|
+
| Variable | Description | Default | Required |
|
|
100
|
+
|------------------------------|--------------------------------------------------------------------------------------|--------------------------|---------------------------------------------------------------------------------------------|
|
|
101
|
+
| `ES_HOST` | Hostname for external Elasticsearch/OpenSearch. | `localhost` | Optional |
|
|
102
|
+
| `ES_PORT` | Port for Elasticsearch/OpenSearch. | `9200` (ES) / `9202` (OS)| Optional |
|
|
103
|
+
| `ES_USE_SSL` | Use SSL for connecting to Elasticsearch/OpenSearch. | `false` | Optional |
|
|
104
|
+
| `ES_VERIFY_CERTS` | Verify SSL certificates when connecting. | `false` | Optional |
|
|
105
|
+
| `STAC_FASTAPI_TITLE` | Title of the API in the documentation. | `stac-fastapi-elasticsearch` or `stac-fastapi-opensearch` | Optional |
|
|
106
|
+
| `STAC_FASTAPI_DESCRIPTION` | Description of the API in the documentation. | N/A | Optional |
|
|
107
|
+
| `STAC_FASTAPI_VERSION` | API version. | `2.1` | Optional |
|
|
108
|
+
| `APP_HOST` | Server bind address. | `0.0.0.0` | Optional |
|
|
109
|
+
| `APP_PORT` | Server port. | `8080` | Optional |
|
|
110
|
+
| `ENVIRONMENT` | Runtime environment. | `local` | Optional |
|
|
111
|
+
| `WEB_CONCURRENCY` | Number of worker processes. | `10` | Optional |
|
|
112
|
+
| `RELOAD` | Enable auto-reload for development. | `true` | Optional |
|
|
113
|
+
| `STAC_FASTAPI_RATE_LIMIT` | API rate limit per client. | `200/minute` | Optional |
|
|
114
|
+
| `BACKEND` | Tests-related variable | `elasticsearch` or `opensearch` based on the backend | Optional |
|
|
115
|
+
| `ELASTICSEARCH_VERSION` | ElasticSearch version | `7.17.1` | Optional |
|
|
116
|
+
| `OPENSEARCH_VERSION` | OpenSearch version | `2.11.0` | Optional |
|
|
117
|
+
|
|
118
|
+
> [!NOTE]
|
|
119
|
+
> The variables `ES_HOST`, `ES_PORT`, `ES_USE_SSL`, and `ES_VERIFY_CERTS` apply to both Elasticsearch and OpenSearch backends, so there is no need to rename the key names to `OS_` even if you're using OpenSearch.
|
|
120
|
+
|
|
121
|
+
## Interacting with the API
|
|
122
|
+
|
|
87
123
|
To create a new Collection:
|
|
88
124
|
|
|
89
125
|
```shell
|
|
@@ -297,111 +333,9 @@ The modified Items with lowercase identifiers will now be visible to users acces
|
|
|
297
333
|
|
|
298
334
|
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).
|
|
299
335
|
|
|
300
|
-
|
|
301
336
|
## Aggregation
|
|
302
337
|
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
A field named `aggregations` should be added to the Collection object for the collection for which the aggregations are available, for example:
|
|
307
|
-
|
|
308
|
-
```json
|
|
309
|
-
"aggregations": [
|
|
310
|
-
{
|
|
311
|
-
"name": "total_count",
|
|
312
|
-
"data_type": "integer"
|
|
313
|
-
},
|
|
314
|
-
{
|
|
315
|
-
"name": "datetime_max",
|
|
316
|
-
"data_type": "datetime"
|
|
317
|
-
},
|
|
318
|
-
{
|
|
319
|
-
"name": "datetime_min",
|
|
320
|
-
"data_type": "datetime"
|
|
321
|
-
},
|
|
322
|
-
{
|
|
323
|
-
"name": "datetime_frequency",
|
|
324
|
-
"data_type": "frequency_distribution",
|
|
325
|
-
"frequency_distribution_data_type": "datetime"
|
|
326
|
-
},
|
|
327
|
-
{
|
|
328
|
-
"name": "sun_elevation_frequency",
|
|
329
|
-
"data_type": "frequency_distribution",
|
|
330
|
-
"frequency_distribution_data_type": "numeric"
|
|
331
|
-
},
|
|
332
|
-
{
|
|
333
|
-
"name": "platform_frequency",
|
|
334
|
-
"data_type": "frequency_distribution",
|
|
335
|
-
"frequency_distribution_data_type": "string"
|
|
336
|
-
},
|
|
337
|
-
{
|
|
338
|
-
"name": "sun_azimuth_frequency",
|
|
339
|
-
"data_type": "frequency_distribution",
|
|
340
|
-
"frequency_distribution_data_type": "numeric"
|
|
341
|
-
},
|
|
342
|
-
{
|
|
343
|
-
"name": "off_nadir_frequency",
|
|
344
|
-
"data_type": "frequency_distribution",
|
|
345
|
-
"frequency_distribution_data_type": "numeric"
|
|
346
|
-
},
|
|
347
|
-
{
|
|
348
|
-
"name": "cloud_cover_frequency",
|
|
349
|
-
"data_type": "frequency_distribution",
|
|
350
|
-
"frequency_distribution_data_type": "numeric"
|
|
351
|
-
},
|
|
352
|
-
{
|
|
353
|
-
"name": "grid_code_frequency",
|
|
354
|
-
"data_type": "frequency_distribution",
|
|
355
|
-
"frequency_distribution_data_type": "string"
|
|
356
|
-
},
|
|
357
|
-
{
|
|
358
|
-
"name": "centroid_geohash_grid_frequency",
|
|
359
|
-
"data_type": "frequency_distribution",
|
|
360
|
-
"frequency_distribution_data_type": "string"
|
|
361
|
-
},
|
|
362
|
-
{
|
|
363
|
-
"name": "centroid_geohex_grid_frequency",
|
|
364
|
-
"data_type": "frequency_distribution",
|
|
365
|
-
"frequency_distribution_data_type": "string"
|
|
366
|
-
},
|
|
367
|
-
{
|
|
368
|
-
"name": "centroid_geotile_grid_frequency",
|
|
369
|
-
"data_type": "frequency_distribution",
|
|
370
|
-
"frequency_distribution_data_type": "string"
|
|
371
|
-
},
|
|
372
|
-
{
|
|
373
|
-
"name": "geometry_geohash_grid_frequency",
|
|
374
|
-
"data_type": "frequency_distribution",
|
|
375
|
-
"frequency_distribution_data_type": "numeric"
|
|
376
|
-
},
|
|
377
|
-
{
|
|
378
|
-
"name": "geometry_geotile_grid_frequency",
|
|
379
|
-
"data_type": "frequency_distribution",
|
|
380
|
-
"frequency_distribution_data_type": "string"
|
|
381
|
-
}
|
|
382
|
-
]
|
|
383
|
-
```
|
|
384
|
-
|
|
385
|
-
Available aggregations are:
|
|
386
|
-
|
|
387
|
-
- total_count (count of total items)
|
|
388
|
-
- collection_frequency (Item `collection` field)
|
|
389
|
-
- platform_frequency (Item.Properties.platform)
|
|
390
|
-
- cloud_cover_frequency (Item.Properties.eo:cloud_cover)
|
|
391
|
-
- datetime_frequency (Item.Properties.datetime, monthly interval)
|
|
392
|
-
- datetime_min (earliest Item.Properties.datetime)
|
|
393
|
-
- datetime_max (latest Item.Properties.datetime)
|
|
394
|
-
- sun_elevation_frequency (Item.Properties.view:sun_elevation)
|
|
395
|
-
- sun_azimuth_frequency (Item.Properties.view:sun_azimuth)
|
|
396
|
-
- off_nadir_frequency (Item.Properties.view:off_nadir)
|
|
397
|
-
- grid_code_frequency (Item.Properties.grid:code)
|
|
398
|
-
- centroid_geohash_grid_frequency ([geohash grid](https://opensearch.org/docs/latest/aggregations/bucket/geohash-grid/) on Item.Properties.proj:centroid)
|
|
399
|
-
- centroid_geohex_grid_frequency ([geohex grid](https://opensearch.org/docs/latest/aggregations/bucket/geohex-grid/) on Item.Properties.proj:centroid)
|
|
400
|
-
- centroid_geotile_grid_frequency (geotile on Item.Properties.proj:centroid)
|
|
401
|
-
- geometry_geohash_grid_frequency ([geohash grid](https://opensearch.org/docs/latest/aggregations/bucket/geohash-grid/) on Item.geometry)
|
|
402
|
-
- geometry_geotile_grid_frequency ([geotile grid](https://opensearch.org/docs/latest/aggregations/bucket/geotile-grid/) on Item.geometry)
|
|
403
|
-
|
|
404
|
-
Support for additional fields and new aggregations can be added in the associated `database_logic.py` file.
|
|
338
|
+
Aggregation of points and geometries, as well as frequency distribution aggregation of any other property including dates is supported in stac-fatsapi-elasticsearch-opensearch. Aggregations can be defined at the root Catalog level (`/aggregations`) and at the Collection level (`/<collection_id>/aggregations`). Details for supported aggregations can be found at [./docs/src/aggregation.md](./docs/src/aggregation.md)
|
|
405
339
|
|
|
406
340
|
## Rate Limiting
|
|
407
341
|
|
|
File without changes
|
|
File without changes
|
{stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/base_database_logic.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/extensions/__init__.py
RENAMED
|
File without changes
|
{stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi/core/extensions/aggregation.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi.core.egg-info/dependency_links.txt
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
{stac-fastapi.core-3.2.0 → stac_fastapi.core-3.2.2}/stac_fastapi.core.egg-info/top_level.txt
RENAMED
|
File without changes
|