A lightweight FastAPI service that exposes endpoints to interact with Zarr datasets stored in a Simple Storage Service (S3):
- a datasets endpoint to explore available multi-dimensional arrays,
- an extraction endpoint to slice and dice data,
- a probe endpoint to query specific values at given coordinates,
- an isoline endpoint to compute contour lines dynamically.
Tip
You can find auto-generated documentation about API at endpoints /docs or /redoc
Check for service's health, return a json object with a single member status.
Return a list of all available Zarr datasets with their id and description.
Return metadata (dimensions, variables, attributes) for a specific Zarr dataset.
The dataset parameter is expected to be the dataset id, that can be found with the previous endpoint.
Extracts a subset of the data based on a bounding box and a specific variable.
Warning
Large extractions may impact performance. Be mindful of the bounding box size for high-resolution datasets.
The extract endpoint accepts the following query parameters:
| Name | Description | Optional |
|---|---|---|
variable |
The variable to extract. | ✗ |
lon_min |
Minimum longitude of the bounding box. | ✓ |
lat_min |
Minimum latitude of the bounding box. | ✓ |
lon_max |
Maximum longitude of the bounding box. | ✓ |
lat_max |
Maximum latitude of the bounding box. | ✓ |
time |
The time value/slice to extract. | ✓ |
Important
You may need to specify additional non-generic variables or dimensions according to your dataset. To do so, you can add query parameters with &my_additional_variable={VALUE}
Retrieves the values of specified variables at a specific geographical location (point query).
The probe endpoint accepts the following query parameters:
| Name | Description | Optional |
|---|---|---|
variables |
The list of variables to probe. | ✗ |
lon |
The longitude coordinate to probe. | ✗ |
lat |
The latitude coordinate to probe. | ✗ |
height |
The height coordinate to probe (if 3D data). | ✓ |
Important
You may need to specify additional non-generic variables or dimensions according to your dataset. To do so, you can add query parameters with &my_additional_variable={VALUE}
Tip
You can request multiple variables at once by repeating the variables parameter in the query string (e.g., ?variables=temp&variables=wind).
Computes isolines (contour lines) for a given variable and specific levels.
The isoline endpoint accepts the following query parameters:
| Name | Description | Optional |
|---|---|---|
variable |
The variable to generate isolines for. | ✗ |
levels |
Comma-separated list of levels for isoline generation. | ✗ |
time |
The time value to use for isoline generation. | ✓ |
Important
You may need to specify additional non-generic variables or dimensions according to your dataset. To do so, you can add query parameters with &my_additional_variable={VALUE}
| Variable | Description | Default value |
|---|---|---|
| PORT | The port to be used when exposing the service | 8000 |
| HOSTNAME | The hostname to be used when exposing the service | localhost |
| AWS_ACCESS_KEY_ID | Access key ID of the S3 in which zarr data is stored | |
| AWS_SECRET_ACCESS_KEY | Secret access key of the S3 in which zarr data is stored | |
| AWS_REGION | Region of the S3 in which zarr data is stored | |
| AWS_ENDPOINT_URL | Endpoint URL of the S3 in which zarr data is stored | |
| BUCKET_NAME | The name of the bucket in which zarr data is stored |
You can build the image with the following command:
docker build -t <your-image-name> .And then start the service with:
docker run -p 8000:8000 <your-image-name>You will need to install multiple Python packages to run this app. To simplify, you can install Anaconda and run these commands :
conda create -y -n kazarr_env python=3.11conda install -y -n kazarr_env -c conda-forge \
fastapi \
uvicorn \
xarray \
zarr \
cfgrib \
numpy \
pyproj \
dask \
s3fs \
matplotlib \
pyvistaconda activate kazarr_envpython main.py start-apiPlease read the Contributing file for details on our code of conduct, and the process for submitting pull requests to us.
We use SemVer for versioning. For the versions available, see the tags on this repository.
This project is sponsored by
This project is licensed under the MIT License - see the license file for details.