Local Installation Guide

To run the GGST FastAPI application locally, follow these steps.

1. Clone the Repository

clone the latest repo, like:

git clone https://github.com/<your-org-or-username>/ggst-api.git
cd ggst-api

2. Create and Activate a Conda Environment

Create a clean environment (recommended Python 3.10+):

conda create --name ggst-env
conda activate ggst-env

3. Setup Environment Variables

Two .env files are required:

• One in the root directory
• One inside the thredds_service/ subdirectory

Copy the example files:

cp .env.example .env
cp thredds/.env.example thredds/.env

Open both .env files in a text editor and fill in all required fields.

GLOBAL_OUTPUT_DIR and GRACE_THREDDS_DIR are Mandatory. Where as in GLOBAL_OUTPUT_DIR gldas and mascon folders will we created and in GRACE_THREDDS_DIR storage files are stored.

Make sure no values are left blank.

4. Run Using Docker Compose

Build the Docker images and start all containers in detached mode:

docker compose up -d --build

You may see a warning about the version field in docker-compose.yml. It's safe to ignore, but removing it is recommended.

Once the build is complete, Docker Compose will start the following services and containers:

Services Defined in docker-compose.yml:

Service Name	Description
ggst	Main FastAPI backend for GGST
redis	Caching layer for async tasks
thredds	THREDDS Data Server for NetCDF

🐳 Containers Started:

Container Name	Role
ggst_backend	Runs the FastAPI server
ggst_backend-thredds-1	Hosts THREDDS server
redis	Caching backend

Once running, the API server will be available locally:

See the API Documentation section below to explore available endpoints and interactive testing interfaces.

NOTE : ✅ Use docker compose ps to verify all services are up and healthy.

Application Programming Interface (API)

The Python Fast API for the GGST allows users to retrieve ground water information about a point or region without having administrative privileges to the GGST web application. The GGST API has the following functions. Each of these functions requires different inputs and returns different results as desired by the user. The name of each function gives a glimpse of what each accomplishes. These functions are:

API Routes

- Auth Routes

• POST /register
• POST /jwt/login
• POST /jwt/logout
• POST /request-verify-token

- Protected Routes

• GET /getStorageOptions
• GET /getPointValues
• GET /getRegionTimeseries
• POST /subsetRegionZipfile
• POST /zipRegionTimeseries

- Admin Routes

• POST /startUpdateGlobalfiles
• GET /job_status/{job_id}
• GET /download_status/{job_id}
• POST /reset/download/{job_id}
• POST /addRegion
• GET /listRegions
• GET /regionCoordinates/{region_name}/{storage_type}
• DELETE /deleteRegion/{region_name}
• GET /saveRegionTimeseries
• GET /listRegionFiles/{region_name}
• GET /downloadRegion/{region_name}
• GET /downloadRegionFile/{region_name}/{filename}

- Admin Dashboard

• /admin

Now let us explore each of the GGST API methods in the following section.

Accessing FastAPI Docs

FastAPI provides interactive API documentation interfaces at two endpoints by default:

1. Swagger UI

You can access the Swagger UI by visiting the /docs endpoint of your FastAPI app.

For example, if your FastAPI app is hosted at https://localhost, the Swagger UI can be accessed at:

https://localhost/docs

The Swagger UI displays all available API endpoints, request and response formats, and allows you to test endpoints directly from the browser.

Example Swagger UI Screenshot:

2. ReDoc UI

FastAPI also provides an alternative documentation interface using ReDoc, accessible at the /redoc endpoint.

For the same https://localhost domain, you can access ReDoc at:

https://localhost/redoc

ReDoc offers a more structured and clean layout, especially useful for reading through large APIs.

You can use either interface depending on your preference. Both are automatically generated based on the OpenAPI schema defined by FastAPI.

API Endpoints Overview

To test the API, the user will need a zip file of the region of interest. We have provided a set of sample files in the appropriate format. You may use your own files if you choose so.

API_Fileset.zip.

Let's explore each API method individually and offer an example:

Protected Routes

1. Get-Storage-Options — /api/getStorageOptions/

To view the result on an endpoint first click here on Try it Out and then click on Execute.

for reference go through the images provided in a sequence

Follow this link to inspect the JSON returned which lists the list of the storage options available:

http://apps.geoglows.org/apps/ggst/api/getStorageOptions/

For simplicity, the options are given a variable name. For instance, the "Total Water Storage (GRACE)" has a variable name of "grace", and similarly the "Soil Moisture Storage (GLDAS)" is shortened to "sm".

2. Get-Point-Values — /api/getPointValues/

Parent Application	GGST
Supported Methods	GET
Returns	A JSON object with a timeseries for a given point

Parameters

Name	Description	Valid Value	Required
Longitude	long in WGS 84 Proj	Any value on land with the GRACE Explorer Domain (-60,180)	Yes
Latitude	lat in WGS 84 Proj	Any value on land with the GRACE Explorer Domain (-60,90)	Yes
storage_type	Storage type of interest	One of the abbreviated values from the first function. eg. grace, sw, sm or gw	Yes

As you have seen how to access a GET request without passing an input, now let's see how to provide inputs through this example screenshots.

Sample Inputs:

Longitude : 20.7

Latitude : 80.2

Storage Type : gw

Click Execute in the Swagger UI to view the output.

You can also verify the response using the example link below, which directly calls the API and returns the JSON data in a new browser tab:

https://apps.geoglows.org/apps/ggst/api/getPointValues/?latitude=20.7&longitude=80.2&storage_type=gw

3. Get-Region-Timeseries — /api/getRegionTimeseries/

Get timeseries data for a region.

Parameters

Name	Type	Location	Description	Required	Example
name	string	query	Region name	Yes	India
geometry	string	query	GeoJSON geometry object (WGS 84)	Yes	{"type": "Point", "coordinates": [13.7, 51.0]}

---

Curl Example

curl -X 'GET' \
  'http://127.0.0.1:8000/api/getRegionTimeseries/?name=India&geometry=%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B13.7%2C51.0%5D%7D' \
  -H 'accept: application/json'

Refer to the below image for more clarity:

4. Subset-Region-Zipfile — /api/subsetRegionZipfile/

Parent application	GGST
Supported Methods	POST
Returns	A zip file with regional netCDF files for each storage option clipped to the uploaded shapefile.

Parameters (Params)

Name	Description	Valid Value	Required
Region name	Name for the subset region. All files will have this name as prefix	String	Yes
files	A zipped folder	A zipped folder with .shp, .shx, .prj, and .dbf files	Yes
API token	Token from the Tethys portal	Token from a Tethys user account on the portal	Yes

---

Example Query (Python)

files = {'shapefile': ('response.zip', uploaded[''.join(uploaded)], 'application/zip')}
subset_region_request = requests.post(
    "https://apps.geoglows.org/apps/ggst/api/subsetRegionZipfile/",
    headers={"Authorization": f"Token {api_token}"},
    data={"name": "api_test"},
    files=files
)
z = ZipFile(BytesIO(subset_region_request.content))
z.extractall()

5. Zip-Region-Zipfile — /api/zipRegionTimeseries/

Generate timeseries data from a zip file for a region.

Parameters

Name	Type	Location	Description	Required
file	file (binary)	body	A zipped shapefile (.zip containing .shp, .shx, .prj, .dbf)	Yes
name	string / null	body	Name to use as prefix for the region	No
storage_type	string / null	body	Storage type of interest (e.g. grace, sw, sm, or gw)	No

---

Example Curl Request

curl -X 'POST' \
  'http://127.0.0.1:8000/api/zipRegionTimeseries/' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@shapefiles_dresden.zip;type=application/x-zip-compressed' \
  -F 'name=dresden' \
  -F 'storage_type=sw'

Sample Response:

{
  "values": [
    ["2000-01-01", -6.573],
    ["2008-05-01", -2.064, 8.111],
    ["2025-03-01", -1.654, 5.769]
  ],
  "area": 2312162298.3204136,
  "success": "success"
}

Admin Routes

1. Start -Update-Global-Files — /api/startUpdateGlobalFiles/

Starting updating global files asynchronously, returns a job ID which is required for accessing the further endpoints.

Parameters

None

Example Curl Request

curl -X 'POST' \
  'http://127.0.0.1:8000/api/startUpdateGlobalFiles' \
  -H 'accept: application/json' \
  -d ''

Sample Responses:

{
 "job_id": "271a8cd3-****-5f3b-ac90-****",
 "message": "Job started. Use /api/jobStatus/271a8cd3-****-5f3b-ac90-**** to check progress."
}

2. Stream Job Logs — /api/jobStatus/{job_id}

Fetch the live status and logs of a background job initiated via /api/startUpdateGlobalFiles.

Path Parameters

Name	Description	Type	Required
job_id	The UUID of the job to track ( output of /api/startUpdateGlobalFiles/ )	string	Yes

---

Example Curl Request

curl -X 'GET' \
  'http://127.0.0.1:8000/api/jobStatus/271a8cd3-****-5f3b-ac90-****' \
  -H 'accept: application/json'

Sample Response:

data: {"timestamp":"2025-06-26T11:17:04Z","status":"Job started..."}

data: {"timestamp":"2025-06-26T11:18:10Z","status":"Downloading GRACE files (3/8)..."}

...

3. Get Download Status — /api/downloadStatus/{job_id}

Retrieve the download progress and metadata for a specific job_id associated with global file updates.

Path Parameters

Name	Description	Type	Required
job_id	output of /api/startUpdateGlobalFiles/	string	Yes

---

Example Curl Request

curl -X 'GET' \
  'http://127.0.0.1:8000/api/downloadStatus/271a8cd3-****-5f3b-ac90-****' \
  -H 'accept: application/json'

Sample Response:

Note:
The null values for start_time, end_time, and duration_minutes indicate that the download process for those files has not started or is still in progress.

These values will be updated automatically once the file download completes.

4. Reset Download — /api/resetDownload/{job_id}

Reset a download task associated with a given job ID. This endpoint clears previous logs and allows the download process to start fresh.

Path Parameters

Name	Description	Type	Required
job_id	The ID of the job to be reset (output of /api/startUpdateGlobalFiles/)	string	Yes

---

Example Curl Request

curl -X 'GET' \
  'http://127.0.0.1:8000/api/resetDownload/271a8cd3-****-5f3b-ac90-****' \
  -H 'accept: application/json'

Sample Response:

{
  "message": "Reset successful.",
  "log_file_deleted": true,
  "job_id": "271a8cd3-****-5f3b-ac90-****"
}

5. Add Region — /api/addRegion

Upload and extract a .zip file to create a new region folder in the GRACE THREDDS directory.

Query Parameters

Name	Description	Type	Required
region_name	Name of the region to add	string	Yes

Form Data

Name	Description	Type	Required
file	A .zip file with region content	file	Yes

---

6. List Regions — /api/listRegions

List all regions except the saved_region_time_series directory.

Sample Response

[
  {
    "label": "India Region",
    "value": "india_region"
  }
]

---

7. Region Coordinates — /api/regionCoordinates/{region_name}/{storage_type}

Return the center coordinates and zoom level of a region's NetCDF file.

Path Parameters

Name	Description	Type	Required
region_name	Name of the region	string	Yes
storage_type	Storage file identifier (e.g., grace, griac)	string	Yes

---

8. Delete Region — /api/deleteRegion/{region_name}

Delete a region and its associated files.

Path Parameters

Name	Description	Type	Required
region_name	Region folder name	string	Yes

---

9. Save Region Timeseries — /api/saveRegionTimeseries/

Generate timeseries .zip for a region from its geometry and save it.

Query Parameters

Name	Description	Type	Required
name	Output filename	string	Yes
geometry	GeoJSON-formatted polygon geometry	string	Yes

---

10. List Region Files — /api/listRegionFiles/{region_name}

List all files present in a specific region folder.

Path Parameters

Name	Description	Type	Required
region_name	Folder of the region	string	Yes

---

11. Download Region — /api/downloadRegion/{region_name}

Download a zipped archive of the entire region folder.

Path Parameters

Name	Description	Type	Required
region_name	Region folder name	string	Yes

---

12. Download Region File — /api/downloadRegionFile/{region_name}/{filename}

Download a specific file from a given region folder.

Path Parameters

Name	Description	Type	Required
region_name	Region folder name	string	Yes
filename	File to download	string	Yes

Admin Dashboard & Auth System Documentation

Dashboard Access

The Admin Dashboard can be accessed at:

http://127.0.0.1:8081/admin/

This panel allows admin users to view, edit, or delete users, and manage permissions.

Login Page

To access the dashboard, navigate to the login screen:

You must log in with your admin credentials to proceed.

---

Admin Panel View

After successful login, the dashboard lists all users with their metadata:

Column	Description
id	UUID of the user
name	Name of the user
email	User email
is_active	Indicates if the account is active
is_verified	Email verification status
role	Role assigned (ADMIN or USER)
is_superuser	Superuser flag
created_at	Account creation timestamp

Actions include:

• 👁️ View user
• ✏️ Edit user
• 🗑️ Delete user

---