feat: ✨ Coordinate format documented, date format specified, fields parameter explained and zipcode approach changed

Author: marcvergees

app/api/routes/weather.py

@@ -28,12 +28,10 @@ def get_weather_forecast(
     fields: str | None = None,
 ):
     """
-    Fetch weather forecast data for the given coordinates.
+    Fetch hourly weather forecast data for the given coordinates and date range.
 
-    Query params:
-      - latitude, longitude: required floats
-      - fields: optional comma-separated list of hourly variables to include.
-                Defaults to all supported fields when omitted.
+    Coordinates must be supplied as **decimal degrees** — not degree/minute/second notation. E.g. -122.4194, 37.7749.
+    Dates must use the **YYYY-MM-DD** format (ISO 8601).
     """
     controller = Controller()
     try:

app/api/routes/zipcode.py

@@ -5,38 +5,24 @@
 
 router = APIRouter(prefix="/zipcode", tags=["zipcode"])
 
-@router.get("/postal-code")
-def get_postal_code(
-    country: str,
-    postal_code: str,
-):
-    """
-    Fetch data for the given postal code.
 
-    Query params:
-      - country: required string
-      - postal_code: required string
+@router.get("/lookup-address")
+def lookup_address(address: str):
     """
-    controller = Controller()
-    try:
-        return controller.get_postal_code(country, postal_code)
-    except Exception as e:
-        raise AppError(str(e), status_code=500)
+    Resolve a free-form address to one or more geographic locations including
+    postal code, latitude, longitude, place name, state, county, and country.
 
-@router.get("/location")
-def get_location(
-    country: str,
-    city: str,
-):
-    """
-    Fetch data for the given location.
+    Returns a list of matching results ordered by relevance (most relevant first).
+    Each result is guaranteed to include `latitude` and `longitude`; `postal_code`
+    is present when the geocoding service can determine it for the given address.
 
-    Query params:
-      - country: required string
-      - city: required string
+    Example: 
+        address = "1600 Amphitheatre Parkway, Mountain View, CA, US"
     """
     controller = Controller()
     try:
-        return controller.get_location(country, city)
+        return controller.lookup_address(address)
+    except TimeoutError as e:
+        raise AppError(str(e), status_code=504)
     except Exception as e:
         raise AppError(str(e), status_code=500)

app/services/controller.py

@@ -16,8 +16,5 @@ def prepare_fillable(self, pdf_path: str):
     def get_weather(self, latitude: float, longitude: float, start_date: str, end_date: str, hourly_fields: list = None):
         return self.external_apis_coordinator.get_weather(latitude, longitude, start_date, end_date, hourly_fields)
 
-    def get_postal_code(self, country: str, postal_code: str):
-        return self.external_apis_coordinator.get_postal_code(country, postal_code)
-        
-    def get_location(self, country: str, city: str):
-        return self.external_apis_coordinator.get_location(country, city)
+    def lookup_address(self, address: str) -> list[dict]:
+        return self.external_apis_coordinator.lookup_address(address)

app/services/external_apis/weather_api.py

@@ -55,9 +55,6 @@ def get_weather(self, latitude: float, longitude: float, start_date: str, end_da
         responses = openmeteo.weather_api(url, params=params)
 
         response = responses[0]
-        print(f"Coordinates: {response.Latitude()}°N {response.Longitude()}°E")
-        print(f"Elevation: {response.Elevation()} m asl")
-        print(f"Timezone difference to GMT+0: {response.UtcOffsetSeconds()}s")
 
         hourly = response.Hourly()
 

app/services/external_apis/zipcode_api.py

@@ -1,23 +1,72 @@
-import pgeocode
-import numpy as np
-import pandas as pd
+from geopy.geocoders import Nominatim
+from geopy.exc import GeocoderTimedOut, GeocoderServiceError
+
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+_GEOLOCATOR = Nominatim(user_agent="fireform", timeout=10)
+
 
 class ZipCodeAPI:
     def __init__(self):
         pass
 
-    def get_postal_code(self, country: str, postal_code: str):
-        res = pgeocode.Nominatim(country).query_postal_code(postal_code)
-        if isinstance(res, pd.Series):
-            res = res.replace({np.nan: None}).to_dict()
-        elif isinstance(res, pd.DataFrame):
-            res = res.replace({np.nan: None}).to_dict(orient='records')
-        return res
-
-    def get_location(self, country: str, city: str):
-        res = pgeocode.Nominatim(country).query_location(city)
-        if isinstance(res, pd.Series):
-            res = res.replace({np.nan: None}).to_dict()
-        elif isinstance(res, pd.DataFrame):
-            res = res.replace({np.nan: None}).to_dict(orient='records')
-        return res
+    def lookup_address(self, address: str) -> list[dict]:
+        """
+        Look up an address string via OpenStreetMap Nominatim and return a list
+        of matching locations with their postal codes, coordinates, and names.
+
+        Args:
+            address: Full address string, e.g. "1600 Amphitheatre Parkway, Mountain View, CA, US"
+
+        Returns:
+            A list of dicts, each containing:
+              - postal_code (str | None)
+              - place_name (str)
+              - latitude (float)
+              - longitude (float)
+              - display_name (str)
+              - country (str | None)
+              - state (str | None)
+              - county (str | None)
+        """
+        try:
+            locations = _GEOLOCATOR.geocode(
+                address,
+                exactly_one=False,
+                addressdetails=True,
+                limit=10,
+            )
+        except GeocoderTimedOut:
+            logger.error("Nominatim geocoding timed out for address: %s", address)
+            raise TimeoutError(f"Geocoding service timed out for address: '{address}'")
+        except GeocoderServiceError as exc:
+            logger.error("Nominatim geocoding service error: %s", exc)
+            raise RuntimeError(f"Geocoding service error: {exc}")
+
+        if not locations:
+            logger.info("No results found for address: %s", address)
+            return []
+
+        results = []
+        for loc in locations:
+            addr = loc.raw.get("address", {})
+            results.append({
+                "postal_code": addr.get("postcode"),
+                "place_name": addr.get("city")
+                    or addr.get("town")
+                    or addr.get("village")
+                    or addr.get("hamlet")
+                    or addr.get("municipality")
+                    or "",
+                "latitude": loc.latitude,
+                "longitude": loc.longitude,
+                "display_name": loc.address,
+                "country": addr.get("country"),
+                "state": addr.get("state"),
+                "county": addr.get("county"),
+            })
+            logger.debug("Geocoded result: %s", results[-1])
+
+        return results

app/services/external_apis_coordinator.py

@@ -9,8 +9,5 @@ def __init__(self):
     def get_weather(self, latitude: float, longitude: float, start_date: str, end_date: str, hourly_fields: list[str] | None = None):
         return self.weather_api.get_weather(latitude, longitude, start_date, end_date, hourly_fields)
 
-    def get_postal_code(self, country: str, postal_code: str):
-        return self.zipcode_api.get_postal_code(country, postal_code)
-        
-    def get_location(self, country: str, city: str):
-        return self.zipcode_api.get_location(country, city)
+    def lookup_address(self, address: str) -> list[dict]:
+        return self.zipcode_api.lookup_address(address)

contracts/path/weather.yaml

@@ -1,47 +1,108 @@
 forecast:
   get:
     summary: Fetch weather forecast
-    description: Fetch weather data for the given location and fields.
+    description: >
+      Fetch hourly weather data for the given location and date range.
+      Coordinates must be provided as decimal degrees (e.g. `40.7128` for latitude, `-74.0060` for longitude).
     tags:
       - external-apis
     parameters:
       - name: latitude
         in: query
         required: true
+        description: >
+          Latitude of the location in decimal degrees. Valid range: -90.0 to 90.0.
+          Example: `40.7128` (New York City). Do NOT use degree/minute/second notation.
         schema:
           type: number
           format: float
+          minimum: -90.0
+          maximum: 90.0
+          example: 40.7128
       - name: longitude
         in: query
         required: true
+        description: >
+          Longitude of the location in decimal degrees. Valid range: -180.0 to 180.0.
+          Example: `-74.0060` (New York City). Do NOT use degree/minute/second notation.
         schema:
           type: number
           format: float
+          minimum: -180.0
+          maximum: 180.0
+          example: -74.0060
       - name: start_date
         in: query
         required: true
+        description: >
+          Start date of the forecast period. Format: `YYYY-MM-DD` (ISO 8601).
+          Example: `2024-06-01`.
         schema:
           type: string
           format: date
+          example: "2024-06-01"
       - name: end_date
         in: query
         required: true
+        description: >
+          End date of the forecast period (inclusive). Format: `YYYY-MM-DD` (ISO 8601).
+          Example: `2024-06-07`. Must be >= start_date.
         schema:
           type: string
           format: date
+          example: "2024-06-07"
       - name: fields
         in: query
         required: false
+        description: >
+          Comma-separated list of hourly variables to include in the response.
+          When omitted, all supported variables are returned.
+          Supported values: `temperature_2m`, `relative_humidity_2m`, `rain`,
+          `apparent_temperature`, `precipitation_probability`, `precipitation`,
+          `wind_direction_10m`, `wind_speed_10m`, `soil_temperature_0cm`, `uv_index`.
+          Example: `temperature_2m,rain,wind_speed_10m`.
         schema:
           type: string
-        description: Comma-separated list of hourly variables to request.
+          example: "temperature_2m,rain,wind_speed_10m"
     responses:
       '200':
         description: Weather data retrieved successfully
         content:
           application/json:
             schema:
               type: object
-              additionalProperties: true
+              properties:
+                latitude:
+                  type: number
+                  description: Actual latitude used by the weather model (may differ slightly from input).
+                longitude:
+                  type: number
+                  description: Actual longitude used by the weather model.
+                elevation:
+                  type: number
+                  description: Elevation of the location in metres above sea level.
+                timezone:
+                  type: string
+                  description: Timezone name (e.g. "GMT").
+                timezone_abbreviation:
+                  type: string
+                hourly:
+                  type: object
+                  description: >
+                    Object containing hourly time series. The `date` key holds an array
+                    of ISO 8601 timestamps; all other keys correspond to the requested
+                    fields and contain arrays of the same length.
+                  properties:
+                    date:
+                      type: array
+                      items:
+                        type: string
+                        format: date-time
+                  additionalProperties:
+                    type: array
+                    items:
+                      type: number
+      '422':
+        description: Validation error (e.g. coordinates out of range, invalid date format)
       '500':
         description: Internal server error