@hestia-earth/caching-api 0.1.2 → 0.1.4

package/README.md

@@ -2,4 +2,68 @@
 
 ## Getting started
 
-TODO
+To use this API and querying the raster files, you need to download the assets first:
+
+### 1. Download the HESTIA assets (~1.9 GB, required)
+
+```bash
+mkdir -p assets
+curl -O https://hestia.earth/data/hestia-geospatial-assets.zip
+unzip hestia-geospatial-assets.zip -d assets
+```
+
+### 2. Download GADM boundaries (only for `gadm-ids` queries)
+
+**HESTIA cannot redistribute GADM**, so it comes from the source. Below is a script to run in your terminal to download the files:
+```bash
+mkdir -p assets/gadm
+
+for country in \
+  ABW AFG AGO AIA ALA ALB AND ARE ARG ARM ASM ATA ATF ATG AUS AUT AZE \
+  BDI BEL BEN BES BFA BGD BGR BHR BHS BIH BLM BLR BLZ BMU BOL BRA BRB \
+  BRN BTN BVT BWA CAF CAN CCK CHE CHL CHN CIV CMR COD COG COK COL COM \
+  CPV CRI CUB CUW CXR CYM CYP CZE DEU DJI DMA DNK DOM DZA ECU EGY ERI \
+  ESH ESP EST ETH FIN FJI FLK FRA FRO FSM GAB GBR GEO GGY GHA GIB GIN \
+  GLP GMB GNB GNQ GRC GRD GRL GTM GUF GUM GUY HKG HMD HND HRV HTI HUN \
+  IDN IMN IND IOT IRL IRN IRQ ISL ISR ITA JAM JEY JOR JPN KAZ KEN KGZ \
+  KHM KIR KNA KOR KWT LAO LBN LBR LBY LCA LIE LKA LSO LTU LUX LVA MAC \
+  MAF MAR MCO MDA MDG MDV MEX MHL MKD MLI MLT MMR MNE MNG MNP MOZ MRT \
+  MSR MTQ MUS MWI MYS MYT NAM NCL NER NFK NGA NIC NIU NLD NOR NPL NRU \
+  NZL OMN PAK PAN PCN PER PHL PLW PNG POL PRI PRK PRT PRY PSE PYF QAT \
+  REU ROU RUS RWA SAU SDN SEN SGP SGS SHN SJM SLB SLE SLV SMR SOM SPM \
+  SRB SSD STP SUR SVK SVN SWE SWZ SXM SYC SYR TCA TCD TGO THA TJK TKL \
+  TKM TLS TON TTO TUN TUR TUV TWN TZA UGA UKR UMI URY USA UZB VAT VCT \
+  VEN VGB VIR VNM VUT WLF WSM XAD XCA XCL XKO XNC XPI XSP YEM ZAF ZMB \
+  ZWE
+do
+  archive="assets/gadm/gadm36_${country}_shp.zip"
+  [ -f "$archive" ] && continue
+  curl -fsS -o "$archive" \
+    "https://geodata.ucdavis.edu/gadm/gadm3.6/shp/gadm36_${country}_shp.zip" \
+    || echo "failed: $country"
+done
+```
+
+You can also download the files on https://gadm.org/download_country36.html (the "Shapefile").
+
+### 3. Run the container
+
+```bash
+docker run -p 8000:80 \
+  -e API_TOKEN=<token> \
+  -e DATABASE_URL=<postgres-url> \
+  -v "$(pwd)/assets:/app/assets:ro" \
+  hestiae/hestia-caching-api
+```
+
+Allow ~800 MB of memory.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `API_TOKEN` | — | Admin token. Used to limit access to the whole API. Sent as the `X-API-KEY` header |
+| `DATABASE_URL` | — | PostgreSQL connection string |
+| `GEOSPATIAL_FOLDER` | `assets/ee` | Where the rasters are |
+| `GADM_FOLDER` | `assets/gadm` | Where the GADM archives are |
+| `GDAL_CACHEMAX` | `64` | Tile cache, MB. Left unset, GDAL takes 5% of *host* RAM and ignores the container limit |
+
+Note: the `docker-compose.yml` file is available to get started locally quicker.

package/index.d.ts

@@ -177,6 +177,61 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/geospatial/collections": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List Collections
+         * @description The collections this API can answer for.
+         *
+         *     Callers hold a mix: the ones HESTIA owns are served here, the public Earth
+         *     Engine ones are not. Since `/run` rejects a query it cannot answer *in
+         *     full*, a caller batching collections together needs to know the split up
+         *     front rather than discovering it from a 422.
+         */
+        get: operations["list_collections_geospatial_collections_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/geospatial/run": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Run Query
+         * @description Samples the exported geospatial assets at coordinates, or reduces them over
+         *     boundaries or GADM regions.
+         *
+         *     Accepts the same payload as ``hestia_earth.earth_engine.run`` so the models
+         *     can call this instead, and returns the values in the same order:
+         *     geometry-major, one value per collection.
+         *
+         *     Only collections HESTIA owns are served here. Public Earth Engine
+         *     collections (ERA5, TERRACLIMATE, GMTED2010) are rejected rather than
+         *     silently returning nothing -- the caller is expected to route those to
+         *     Earth Engine.
+         */
+        post: operations["run_query_geospatial_run_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/version": {
         parameters: {
             query?: never;
@@ -215,6 +270,61 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
+        /**
+         * Collection
+         * @description One collection to sample.
+         *
+         *     Mirrors the payload ``hestia_earth.earth_engine`` accepts so the models can
+         *     swap one for the other without reshaping the query. Fields beyond
+         *     ``collection`` (``band_name``, ``reducer``, ``name``, depth bounds) are
+         *     carried for compatibility and ignored when sampling by coordinates -- a
+         *     point needs no reduction, and the soil depth is already encoded in the
+         *     collection name.
+         */
+        Collection: {
+            /** Collection */
+            collection: string;
+        } & {
+            [key: string]: unknown;
+        };
+        /** Coordinate */
+        Coordinate: {
+            /** Latitude */
+            latitude: number;
+            /** Longitude */
+            longitude: number;
+        };
+        /**
+         * GeospatialQuery
+         * @description One of ``coordinates``, ``boundaries`` or ``gadm-ids``.
+         *
+         *     ``hestia_earth.earth_engine.run`` picks its mode from whichever key is
+         *     present, so the same payload works against either backend.
+         */
+        GeospatialQuery: {
+            /** Ee Type */
+            ee_type?: string | null;
+            /** Collections */
+            collections: components["schemas"]["Collection"][];
+            /** Coordinates */
+            coordinates?: components["schemas"]["Coordinate"][] | null;
+            /** Boundaries */
+            boundaries?: {
+                [key: string]: unknown;
+            }[] | null;
+            /** Gadm-Ids */
+            "gadm-ids"?: string[] | null;
+            /** Scale */
+            scale?: number | null;
+        };
+        /**
+         * GeospatialResults
+         * @description Values ordered coordinate-major: per coordinate, one per collection.
+         */
+        GeospatialResults: {
+            /** Results */
+            results: (number | null)[];
+        };
         /** HTTPValidationError */
         HTTPValidationError: {
             /** Detail */
@@ -822,6 +932,59 @@ export interface operations {
             };
         };
     };
+    list_collections_geospatial_collections_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": unknown;
+                };
+            };
+        };
+    };
+    run_query_geospatial_run_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["GeospatialQuery"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GeospatialResults"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     version_version_get: {
         parameters: {
             query?: never;

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "HESTIA Caching API",
-    "version": "0.1.2"
+    "version": "0.1.4"
   },
   "paths": {
     "/sites/{key}": {
@@ -700,6 +700,78 @@
         }
       }
     },
+    "/geospatial/collections": {
+      "get": {
+        "tags": [
+          "geospatial"
+        ],
+        "summary": "List Collections",
+        "description": "The collections this API can answer for.\n\nCallers hold a mix: the ones HESTIA owns are served here, the public Earth\nEngine ones are not. Since `/run` rejects a query it cannot answer *in\nfull*, a caller batching collections together needs to know the split up\nfront rather than discovering it from a 422.",
+        "operationId": "list_collections_geospatial_collections_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "APIKeyHeader": []
+          }
+        ]
+      }
+    },
+    "/geospatial/run": {
+      "post": {
+        "tags": [
+          "geospatial"
+        ],
+        "summary": "Run Query",
+        "description": "Samples the exported geospatial assets at coordinates, or reduces them over\nboundaries or GADM regions.\n\nAccepts the same payload as ``hestia_earth.earth_engine.run`` so the models\ncan call this instead, and returns the values in the same order:\ngeometry-major, one value per collection.\n\nOnly collections HESTIA owns are served here. Public Earth Engine\ncollections (ERA5, TERRACLIMATE, GMTED2010) are rejected rather than\nsilently returning nothing -- the caller is expected to route those to\nEarth Engine.",
+        "operationId": "run_query_geospatial_run_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GeospatialQuery"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GeospatialResults"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "APIKeyHeader": []
+          }
+        ]
+      }
+    },
     "/version": {
       "get": {
         "tags": [
@@ -738,6 +810,154 @@
   },
   "components": {
     "schemas": {
+      "Collection": {
+        "properties": {
+          "collection": {
+            "type": "string",
+            "title": "Collection"
+          }
+        },
+        "additionalProperties": true,
+        "type": "object",
+        "required": [
+          "collection"
+        ],
+        "title": "Collection",
+        "description": "One collection to sample.\n\nMirrors the payload ``hestia_earth.earth_engine`` accepts so the models can\nswap one for the other without reshaping the query. Fields beyond\n``collection`` (``band_name``, ``reducer``, ``name``, depth bounds) are\ncarried for compatibility and ignored when sampling by coordinates -- a\npoint needs no reduction, and the soil depth is already encoded in the\ncollection name."
+      },
+      "Coordinate": {
+        "properties": {
+          "latitude": {
+            "type": "number",
+            "maximum": 90.0,
+            "minimum": -90.0,
+            "title": "Latitude"
+          },
+          "longitude": {
+            "type": "number",
+            "maximum": 180.0,
+            "minimum": -180.0,
+            "title": "Longitude"
+          }
+        },
+        "type": "object",
+        "required": [
+          "latitude",
+          "longitude"
+        ],
+        "title": "Coordinate"
+      },
+      "GeospatialQuery": {
+        "properties": {
+          "ee_type": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Ee Type"
+          },
+          "collections": {
+            "items": {
+              "$ref": "#/components/schemas/Collection"
+            },
+            "type": "array",
+            "minItems": 1,
+            "title": "Collections"
+          },
+          "coordinates": {
+            "anyOf": [
+              {
+                "items": {
+                  "$ref": "#/components/schemas/Coordinate"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Coordinates"
+          },
+          "boundaries": {
+            "anyOf": [
+              {
+                "items": {
+                  "additionalProperties": true,
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Boundaries"
+          },
+          "gadm-ids": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Gadm-Ids"
+          },
+          "scale": {
+            "anyOf": [
+              {
+                "type": "number",
+                "exclusiveMinimum": 0.0
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Scale"
+          }
+        },
+        "type": "object",
+        "required": [
+          "collections"
+        ],
+        "title": "GeospatialQuery",
+        "description": "One of ``coordinates``, ``boundaries`` or ``gadm-ids``.\n\n``hestia_earth.earth_engine.run`` picks its mode from whichever key is\npresent, so the same payload works against either backend."
+      },
+      "GeospatialResults": {
+        "properties": {
+          "results": {
+            "items": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "type": "array",
+            "title": "Results"
+          }
+        },
+        "type": "object",
+        "required": [
+          "results"
+        ],
+        "title": "GeospatialResults",
+        "description": "Values ordered coordinate-major: per coordinate, one per collection."
+      },
       "HTTPValidationError": {
         "properties": {
           "detail": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hestia-earth/caching-api",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "FastAPI application for caching Site data",
   "main": "index.js",
   "types": "index.d.ts",