Skip to content

API Docs

Jump to bottom
2raymoori edited this page Dec 12, 2025 · 4 revisions

Welcome to the EKAPEx-Demo wiki!

Weather API Documentation

Weather API Routes

FastAPI endpoints from app/api/routes.py, documented in a Swagger-like layout with request/response examples.

Conventions

  • model_type: "graphcast", "cerrora".
  • base_time, validTime values: Unix timestamps (seconds).
  • Image URLs are relative to settings.BASE_URL and saved under settings.IMAGE_OUTPUT_DIR/{model}/{variable}/.

GET /temp_compare/{city_name}/{base_time}

Summary: Compare 2 m temperature across GraphCast, CERRa, and ground truth for a city.

  • Path params
    • city_name (string, required) — key in country_details_loader()
    • base_time (integer, required) — Unix timestamp (s)
  • Response 200
    • ground_truth / cerrora / graphcast: dicts of forecast_time and temperature_2m.
  • Example request
    • GET /temp_compare/paris/1704067200
  • Example response 
    {
  "ground_truth": {
    "forecast_time": { "0": 1704088800, "1": 1704110400 },
    "temperature_2m": { "0": 281.4, "1": 282.1 }
  },
  "cerrora": {
    "forecast_time": { "0": 1704088800, "1": 1704110400 },
    "temperature_2m": { "0": 280.9, "1": 281.7 }
  },
  "graphcast": {
    "forecast_time": { "0": 1704088800, "1": 1704110400 },
    "temperature_2m": { "0": 281.2, "1": 281.9 }
  }
}

GET /data/{model_variable}/{base_time}

Summary: Retrieve cached/generated visualization image filenames for a base time across models.

  • Path params
    • model_variable (temp_wind | geo | sea_level)
    • base_time (integer timestamp)
  • Behavior: Reads streaming/{model}/{variable}/; triggers get_images when missing; includes ground-truth.
  • Example request: GET /data/temp_wind/1704067200
  • Response 200 
    [
  ["1704067200_1704088800_image.webp", "1704067200_1704110400_image.webp"],
  " :: ",
  ["1704067200_1704088800_image.webp", "1704067200_1704110400_image.webp"],
  " :: ",
  ["1704067200_1704088800_gt.webp", "1704067200_1704110400_gt.webp"]
]

POST /data/temp_wind/{model_type}

Summary: Generate or fetch temperature/wind images for a time range.

  • Path params
    • model_type (graphcast | cerrora | experimental)
  • Body (TimeRange) 
    {
  "baseTime": 1704067200,
  "validTime": [1704088800, 1704110400, 1704132000]
}
  • Response 200 
    {
  "images": [
    {
      "timestamp": "1704067200_1704088800",
      "url": "/graphcast/tempWind/1704067200_1704088800_image.webp"
    },
    {
      "timestamp": "1704067200_1704110400",
      "url": "/graphcast/tempWind/1704067200_1704110400_image.webp"
    }
  ]
}

POST /data/geo/{model_type}

Summary: Generate geopotential images for a time range.

  • Path params
    • model_type
  • Body (TimeRange) 
    {
  "baseTime": 1704067200,
  "validTime": [1704088800, 1704110400]
}
  • Response 200 
    {
  "images": [
    {
      "timestamp": "1704067200_1704088800",
      "url": "/cerrora/geopotential/1704067200_1704088800_image.webp"
    },
    {
      "timestamp": "1704067200_1704110400",
      "url": "/cerrora/geopotential/1704067200_1704110400_image.webp"
    }
  ]
}

POST /data/rain

Summary: Generate or return cached precipitation images for the active model (DI).

  • Body (TimeRange) 
    {
  "baseTime": 1704067200,
  "validTime": [1704088800, 1704110400, 1704132000]
}
  • Behavior: Checks cache, loads rain variable (total_precipitation_6hr or tp), generates missing plots via visualizer.create_rain_plot.
  • Response 200 
    {
  "images": [
    {
      "timestamp": "1704067200_1704088800",
      "url": "/cerrora/rain/1704067200_1704088800_image.webp"
    },
    {
      "timestamp": "1704067200_1704110400",
      "url": "/cerrora/rain/1704067200_1704110400_image.webp"
    }
  ]
}

POST /data/sea_level/{model_type}

Summary: Generate mean sea level pressure images for a time range.

  • Path params
    • model_type
  • Body (TimeRange) 
    {
  "baseTime": 1704067200,
  "validTime": [1704088800, 1704110400]
}
  • Response 200 
    {
  "images": [
    {
      "timestamp": "1704067200_1704088800",
      "url": "/graphcast/seaLevelPressure/1704067200_1704088800_image.webp"
    }
  ]
}

GET /base-times/{model_type}

Summary: List available base times for a variable.

  • Path params
    • model_type
  • Query params
    • variableType (required): temp_wind, geo, rain, sea_level
    • queryTime (optional): ISO datetime or timestamp
  • Example request: GET /base-times/cerrora?variableType=geo&queryTime=2021-01-05T00:00:00
  • Response 200 
    [
  { "label": "Tue 05 Jan 2021 00 UTC", "value": "1609804800" },
  { "label": "Wed 06 Jan 2021 00 UTC", "value": "1609891200" }
]
  • Errors: 400 invalid variable; 500 dataset issues.

GET /valid-times/{model_type}

Summary: Return valid forecast times for a given variable/base time.

  • Path params
    • model_type
  • Query params
    • variableType: logical variable name
    • queryTime: base time (timestamp or ISO)
  • Example request: GET /valid-times/graphcast?variableType=temp_wind&queryTime=1704067200
  • Response 200 
    [
  [
    { "label": "Wed 01 Jan 2025 06 UTC", "value": "1704088800" },
    { "label": "Wed 01 Jan 2025 12 UTC", "value": "1704110400" }
  ]
]

Internal Helper (not exposed)

get_images(model_type, var_type, base_time) calls fetch_valid_times, builds a TimeRange, dispatches to the fetcher (fetch_temp_wind_data, fetch_sea_level_data, fetch_geo_data), and returns image filenames. Used to backfill missing images for /data/{model_variable}/{base_time}.

Key Dependencies

  • Data access: DataLoader (app/core/data_loader.py) for zarr datasets (local or GCS) with model-specific defaults.
  • Visualization: CerroraVisualizer, CerroraVisualizer_graphcast, GraphCastVisualizer, ExperimentalVisualizer write plots under IMAGE_OUTPUT_DIR.
  • Utilities: process_url, filter_images, fetch_valid_times, fetch_temp_wind_data, fetch_geo_data, fetch_sea_level_data, temp_compare, country_details_loader, etc.

Clone this wiki locally