Data Schemas

{
  "meta": {
    "unit_system": "si",
    "forecast": "Spire Operational Forecast"
  },
  "data": [
    {
      "location": {
        "coordinates": {
          "lat": 40.0,
          "lon": -105.0
        }
      },
      "times": {
        "issuance_time": "2024-01-15T00:00:00",
        "valid_time": "2024-01-15T06:00:00"
      },
      "values": {
        "air_temperature": 275.5,
        "relative_humidity": 65.0,
        "wind_speed": 5.2,
        "wind_direction": 225
      }
    }
  ]
}

{
  "meta": {
    "count": 29
  },
  "files": [
    "sof-d.20240115.t00z.0p25.basic.global.f000.grib2",
    "sof-d.20240115.t00z.0p25.basic.global.f006.grib2"
  ]
}

{
  "route": {
    "name": "my_route",
    "waypoints": [
      {
        "lat": 40.7,
        "lon": -74.0,
        "time": "2024-01-15T12:00:00Z"
      },
      {
        "lat": 38.5,
        "lon": -70.0,
        "time": "2024-01-16T00:00:00Z"
      }
    ]
  },
  "bundles": "basic,maritime"
}

[
  {
    "atcf_id": "AL022024",
    "storm_name": "Beryl",
    "basin": "NA",
    "subbasin": "CS",
    "season": 2024,
    "is_active": false,
    "advisory_number": null,
    "advisory_issuance_time": null,
    "max_development_category": "TC5",
    "max_sustained_wind": 143.0,
    "min_mslp": 934.0,
    "dates_active": {
      "start": "2024-06-28",
      "end": "2024-07-09"
    },
    "observed_track": [
      {
        "lat": 10.5,
        "lon": -45.2,
        "category_code": "TD",
        "basin": "NA",
        "subbasin": "MM",
        "wind_gusts": null,
        "max_sustained_wind": 30.0,
        "min_mslp": 1006.0,
        "movement_direction": 280.0,
        "movement_speed": 18.0,
        "wind_extent_radii": {},
        "time": "2024-06-28T00:00:00+00:00"
      }
    ],
    "forecast_track": []
  }
]

{
  "meta": {
    "unit_system": "si",
    "message": null
  },
  "data": [
    {
      "date": "2024-01-15",
      "high": {
        "time": "2024-01-15T03:24:00",
        "values": {
          "tide_height": 1.52
        }
      },
      "low": {
        "time": "2024-01-15T09:47:00",
        "values": {
          "tide_height": -0.35
        }
      }
    }
  ]
}

{
  "status": "available",
  "issuance_time": "2024-01-15T00:00:00Z",
  "bundles": ["basic", "maritime"]
}

{
  "job_uuid": "abc123-def456-789xyz",
  "status": "pending"
}

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Latitude must be between -90 and 90"
  }
}

from dataclasses import dataclass
from typing import List, Optional
from datetime import datetime

@dataclass
class Coordinates:
    lat: float
    lon: float

@dataclass
class Location:
    coordinates: Coordinates

@dataclass
class Times:
    issuance_time: datetime
    valid_time: datetime

@dataclass
class ForecastRecord:
    location: Location
    times: Times
    values: dict

@dataclass
class ForecastResponse:
    meta: dict
    data: List[ForecastRecord]

def parse_forecast_response(json_data: dict) -> ForecastResponse:
    """Parse JSON response into typed data structure."""
    records = []
    for item in json_data['data']:
        record = ForecastRecord(
            location=Location(
                coordinates=Coordinates(
                    lat=item['location']['coordinates']['lat'],
                    lon=item['location']['coordinates']['lon']
                )
            ),
            times=Times(
                issuance_time=datetime.fromisoformat(item['times']['issuance_time']),
                valid_time=datetime.fromisoformat(item['times']['valid_time'])
            ),
            values=item['values']
        )
        records.append(record)

    return ForecastResponse(
        meta=json_data['meta'],
        data=records
    )