Add API Readme.md, disclaimer, fastapi lifespan for package upgrade

Pipfile

@@ -4,26 +4,26 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-basemap = "==1.3.8"
+basemap = "==1.4.0"
 basemap-data = "==1.3.2"
 basemap-data-hires = "==1.3.2"
-dask = "==2023.12.1"
-fastapi = "==0.108.0"
-matplotlib = "==3.7.4"
+dask = "==2024.1.1"
+fastapi = "==0.109.2"
+matplotlib = "==3.8.2"
 netcdf4 = "==1.6.5"
 numcodecs = "==0.12.1"
-numpy = "==1.26.2"
-pandas = "==2.1.4"
-polars = "==0.20.3"
+numpy = "==1.26.3"
+pandas = "==2.2.0"
+polars = "==0.20.5"
 pydantic = "==2.5.2"
-pytmd = "==2.0.9"
+pytmd = "==2.1.0"
 requests = "==2.31.0"
-scipy = "==1.11.4"
-xarray = "==2023.12.0"
+scipy = "==1.12.0"
+xarray = "==2024.1.1"
 zarr = "==2.16.1"
 src = {file = ".", editable = true}
 gunicorn = "==21.2.0"
-uvicorn = "==0.25.0"
+uvicorn = "==0.27.0.post1"
 
 [dev-packages]
 

README.md

@@ -1 +1,37 @@
-# Tide
+# Open API to query TPXO9-v5 global tide models
+
+#### Swagger API doc
+
+https://eco.odb.ntu.edu.tw/api/swagger/tide
+
+#### Usage
+
+1. Query tide height and tidal current
+
+* One-point tide height with time-span limitation (<= 30 days, hourly data): e.g. /tide?lon0=125&lat0=15&start=2023-07-25&end=2023-07-26T01:30:00.000
+
+* Get current in bounding-box <= 45x45 in degrees at one time moment(in ISOstring): e.g. /tide?lon0=125&lon1&=135&lat0=15&lat1=30&start=2023-07-25T01:30:00.000
+
+2. Get harmonic constituents of TPXO9 model
+
+* e.g. /tide/const?lon=122.36,122.47&lat=25.02,24.82&constituent=k1,m2,n2,o1,p1,s2&complex=amp,ph,hc&append=z,u,v
+
+#### Attribution
+
+* Data source
+
+    Egbert, Gary D., and Svetlana Y. Erofeeva. "Efficient inverse modeling of barotropic ocean tides." Journal of Atmospheric and Oceanic Technology 19.2 (2002): 183-204.
+
+* Parts of this API utilize functions provided by pyTMD (https://github.com/tsutterley/pyTMD). We acknowledge and thank the original authors for their contributions.
+
+#### Disclaimer
+
+* The tide model predictions provided by this API are for reference purposes only and are intended to serve as a preliminary resource, not to be considered as definitive for scientific research or risk assessment. Users should understand that no legal liability or responsibility is assumed by the provider of this API for any decisions made based on reliance on this data. Users should conduct their own independent analysis and verification before relying on the data.
+
+* 本API提供的模型預測數據僅供參考之用，旨在做為初步的資訊來源，而不應被視為科學研究或風險評估的決定性依據。使用者須理解，對於依賴這些數據所做出的任何決策，本API提供者不承擔任何法律責任或義務。使用者在依賴這些數據前，應進行獨立分析和驗證。
+
+#### Citation
+
+* This API is compiled by [Ocean Data Bank](https://www.odb.ntu.edu.tw) (ODB), and can be cited as:
+
+    Ocean Data Bank, National Science and Technology Council, Taiwan. https://doi.org/10.5281/zenodo.7512112. Accessed DAY/MONTH/YEAR from eco.odb.ntu.edu.tw/api/tide. v1.0.

change_log.md

@@ -30,3 +30,5 @@
     -- fix bounding box convert to (0,360) bug
     -- fill 2x2 neighbor NA. Note that trouble to mix tpxo9.zarr/_fillna.zarr should be avoided
     -- small package upgrade/fill_NA trials(15th --> 18th)
+
+#### ver 0.1.0 Add API Readme.md, disclaimer, fastapi lifespan for package upgrade

dev/zarr_fillna_savefile.py

@@ -70,7 +70,7 @@ def resave_fillna_dataset(method1, method2):
 
 
 if __name__ == "__main__":
-    method1_file = "../data/tpxo9_bak17.zarr" #"tpxo9_method1.zarr" #All_NA_CONDITION set False 
+    method1_file = "../data/tpxo9_bak20.zarr" #"tpxo9_method1.zarr" #All_NA_CONDITION set False 
     method2_file = "../data/tpxo9_new.zarr" #"tpxo9_method2.zarr"
     zarr.convenience.consolidate_metadata(method2_file)
     resave_fillna_dataset(method1_file, method2_file)

requirements.txt

@@ -1,20 +1,20 @@
-basemap==1.3.9
+basemap==1.4.0
 basemap_data==1.3.2
 basemap_data_hires==1.3.2
-dask==2023.12.1
-fastapi==0.108.0
+dask==2024.1.1
+fastapi==0.109.2
 gunicorn==21.2.0
-matplotlib==3.7.4
+matplotlib==3.8.2
 netCDF4==1.6.5
 numcodecs==0.12.1
 numpy==1.26.3
-pandas==2.1.4
-polars==0.20.3
+pandas==2.2.0
+polars==0.20.5
 pydantic==2.5.2
-pyTMD==2.0.9
+pyTMD==2.1.0
 Requests==2.31.0
-scipy==1.11.4
+scipy==1.12.0
 setuptools==69.0.3
-uvicorn==0.25.0
-xarray==2023.12.0
+uvicorn==0.27.0.post1
+xarray==2024.1.1
 zarr==2.16.1

tide_app.py

@@ -7,6 +7,7 @@
 from fastapi.openapi.utils import get_openapi
 from fastapi.responses import JSONResponse, ORJSONResponse
 from fastapi.encoders import jsonable_encoder
+from contextlib import asynccontextmanager
 from typing import Optional, List, Union
 from pydantic import BaseModel
 import requests
@@ -24,7 +25,10 @@ def generate_custom_openapi():
     openapi_schema = get_openapi(
         title="ODB Tide API",
         version="1.0.0",
-        description='Open API to query TPXO9-v5 global tide models, compiled by ODB. Reference: Egbert, Gary D., and Svetlana Y. Erofeeva. "Efficient inverse modeling of barotropic ocean tides." Journal of Atmospheric and Oceanic Technology 19.2 (2002): 183-204.',
+        description=('Open API to query TPXO9-v5 global tide models, compiled by ODB. Reference: Egbert, Gary D., and Svetlana Y. Erofeeva. "Efficient inverse modeling of barotropic ocean tides." Journal of Atmospheric and Oceanic Technology 19.2 (2002): 183-204.\n' +
+                     '* The tide model predictions provided by this API are for reference purposes only and are intended to serve as a preliminary resource, not to be considered as definitive for scientific research or risk assessment. Users should understand that no legal liability or responsibility is assumed by the provider of this API for any decisions made based on reliance on this data. Users should conduct their own independent analysis and verification before relying on the data.\n' +
+                     '* 本API提供的模型預測數據僅供參考之用，旨在做為初步的資訊來源，而不應被視為科學研究或風險評估的決定性依據。使用者須理解，對於依賴這些數據所做出的任何決策，本API提供者不承擔任何法律責任或義務。使用者在依賴這些數據前，應進行獨立分析和驗證。\n' +
+                     '* Parts of this API utilize functions provided by pyTMD (https://github.com/tsutterley/pyTMD). We acknowledge and thank the original authors for their contributions.'),
         routes=app.routes,
     )
     openapi_schema["servers"] = [
@@ -36,7 +40,23 @@ def generate_custom_openapi():
     return app.openapi_schema
 
 
-app = FastAPI(root_path="/api/tide", docs_url=None, default_response_class=ORJSONResponse)
+# @app.on_event("startup")
+# async def startup():
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    config.dz = xr.open_zarr('data/tpxo9.zarr', chunks='auto', decode_times=False)
+    config.gridSz = 1/30
+    config.timeLimit = 30
+    config.LON_RANGE_LIMIT = 45
+    config.LAT_RANGE_LIMIT = 45
+    config.AREA_LIMIT = config.LON_RANGE_LIMIT * config.LAT_RANGE_LIMIT
+    config.cons = config.dz.coords['constituents'].values
+    yield
+    # below code to execute when app is shutting down
+    config.dz.close()
+
+
+app = FastAPI(lifespan=lifespan, docs_url=None, default_response_class=ORJSONResponse)
 
 
 @app.get("/api/swagger/tide/openapi.json", include_in_schema=False)
@@ -130,17 +150,6 @@ def tide_to_output(tide, lon, lat, dtime, variables, mode="time", absmax=-1):
     # return df
 
 
-@app.on_event("startup")
-async def startup():
-    config.dz = xr.open_zarr('data/tpxo9.zarr', chunks='auto', decode_times=False)
-    config.gridSz = 1/30
-    config.timeLimit = 30
-    config.LON_RANGE_LIMIT = 45
-    config.LAT_RANGE_LIMIT = 45
-    config.AREA_LIMIT = config.LON_RANGE_LIMIT * config.LAT_RANGE_LIMIT
-    config.cons = config.dz.coords['constituents'].values
-
-
 class TideResponse(BaseModel):
     longitude: float
     latitude: float
@@ -593,8 +602,10 @@ async def get_tide_const(
 ):
     """
     Query harmonic constituents from TPXO9-atlas-v5 model by longitude/latitude.
-    """
 
+    #### Usage
+    * e.g. /tide/const?lon=122.36,122.47&lat=25.02,24.82&constituent=k1,m2,n2,o1,p1,s2&complex=amp,ph,hc&append=z,u,v
+    """
     try:
         if jsonsrc:
             # Validate it's a URL
@@ -631,7 +642,7 @@ async def get_tide_const(
                             content={"Error": str(e)})
 
     if len(loni) != len(lati):
-        config.dz.close()
+        # config.dz.close()
         return JSONResponse(status_code=status.HTTP_400_BAD_REQUEST,
                             content=jsonable_encoder({"Error": "Check your input of lon/lat should be in equal length"}))
     onlyOnePt = False