2. Reading API documentation

Reading documentation is the most skippable-feeling part of integration, and skipping it is the fastest way to write broken code. Before writing any implementation, get four things out of the docs: what endpoint to hit, what parameters to send, what response shape to expect, and what errors might come back. This page walks that extraction process on Open-Meteo, so the rest of the chapter has a concrete specification to implement.

The goal here isn't to memorise Open-Meteo specifics. It's to practise a repeatable process you can run against any unfamiliar API in ten minutes, and come out with implementation notes that save you an hour later.

Where the docs live

Open-Meteo splits its documentation across two pages, one for each service you'll use. Open both in tabs now; the rest of this section reads from them.

Weather forecast API: https://open-meteo.com/en/docs --current conditions and multi-day predictions.
Geocoding API: https://open-meteo.com/en/docs/geocoding-api --converts location names to coordinates.

Professional API docs tend to expose the same five sections, though the labels vary. Scroll each page looking for them: the endpoint URL (sometimes buried in an example link, in which case the real endpoint is everything before the ?), the parameter tables separating required from optional, the response examples showing the JSON shape, the error documentation listing the status codes this specific API returns, and the rate limits. With those located, you can switch from browsing to analysis. Start with the geocoding API, because the weather API depends on its output.

Extracting geocoding requirements

Four questions in order. What's the endpoint? What parameters are required? What optional parameters improve results? What does the response look like?

Base endpoint

Endpoint URL

https://geocoding-api.open-meteo.com/v1/search

All geocoding requests go to this URL with query parameters appended.

Required parameters

The docs list one required parameter:

name --the location to search for (minimum 2 characters).

Useful optional parameters

Three more that are worth setting explicitly:

count --number of results to return (default 10, max 100).
language --response language (default English).
format --use "json" explicitly.

Response structure

Responses contain a results array of location objects. Each location includes:

name --city or location name.
latitude --geographic latitude.
longitude --geographic longitude.
country --country name.
admin1 --state or region (when available).

That's the geocoding specification in one page. You know what to send, what to expect, and which fields to extract. Other response fields exist (timezone, elevation, population) but aren't needed for a weather dashboard. Focus on the minimum.

Extracting weather API requirements

The forecast API exposes dozens of parameters covering temperature, humidity, pressure, wind, solar, marine conditions, and more. The task is picking the minimum set that supports a weather dashboard: current conditions now, plus a multi-day outlook.

Base endpoint

Endpoint URL

https://api.open-meteo.com/v1/forecast

Required parameters

latitude --geographic latitude, sourced from the geocoding API.
longitude --geographic longitude, from the same place.

Current-weather parameters

Choose from the current parameter group. For the dashboard:

temperature_2m --air temperature at 2 metres.
relative_humidity_2m --humidity percentage.
apparent_temperature --"feels like" temperature.
weather_code --standardised weather condition code.
wind_speed_10m --wind speed at 10 metres.
wind_direction_10m --wind direction in degrees.

Daily-forecast parameters

Choose from the daily parameter group:

temperature_2m_max --daily maximum temperature.
temperature_2m_min --daily minimum temperature.
weather_code --daily weather condition.
precipitation_sum --total daily precipitation.
wind_speed_10m_max --maximum daily wind speed.

Configuration parameters

timezone --"auto" gives location-appropriate timestamps.
forecast_days --number of days to forecast (1 to 16).

That's the selection habit worth carrying forward: rather than request everything, pick the minimum set that supports the user-visible thing you're building. Current temperature and conditions for right now; daily min/max and weather codes for planning. Smaller requests, smaller responses, simpler extraction.

Understanding response formats

Documentation typically includes example responses showing the actual JSON structure you'll receive. These examples are critical for writing data extraction code.

Sample response (geocoding)

{
  "results": [
    {
      "id": 2964574,
      "name": "Dublin",
      "latitude": 53.33306,
      "longitude": -6.24889,
      "elevation": 17.0,
      "timezone": "Europe/Dublin",
      "country": "Ireland",
      "country_id": 372,
      "admin1": "Leinster",
      "admin1_id": 7521314
    }
  ],
  "generationtime_ms": 0.48708916
}

Key observations: Results come in an array even for single matches. Each result is a dictionary with many fields. You need latitude, longitude, and name for your use case. Other fields can be ignored.

Sample response (weather)

{
  "latitude": 53.33,
  "longitude": -6.25,
  "timezone": "Europe/Dublin",
  "current": {
    "time": "2026-05-05T14:00",
    "temperature_2m": 8.3,
    "relative_humidity_2m": 87,
    "apparent_temperature": 6.1,
    "weather_code": 3,
    "wind_speed_10m": 11.2,
    "wind_direction_10m": 225
  },
  "current_units": {
    "temperature_2m": "°C",
    "relative_humidity_2m": "%",
    "wind_speed_10m": "km/h",
    "wind_direction_10m": "°"
  },
  "daily": {
    "time": ["2026-05-05", "2026-05-06", "2026-05-07"],
    "temperature_2m_max": [10.2, 9.8, 12.1],
    "temperature_2m_min": [5.8, 4.2, 7.3],
    "weather_code": [3, 61, 2],
    "precipitation_sum": [0.0, 2.4, 0.1]
  },
  "daily_units": {
    "temperature_2m_max": "°C",
    "precipitation_sum": "mm"
  }
}

Two observations worth pinning down. Current conditions live in a current object keyed by field name. Daily forecasts use parallel arrays: one array per field, with index [0] for day one across all of them. That's a different access pattern than geocoding's array-of-dicts, and the weather layer will have to handle both shapes.

Documenting your findings

Translate the documentation into implementation notes you can keep open next to your editor. This last step stops you context-switching back to the browser every few minutes while the code is fresh.

geocoding_spec.txt

# Geocoding API Implementation
# Endpoint: https://geocoding-api.open-meteo.com/v1/search
# 
# Required parameters:
#   name: city name string (min 2 chars)
#
# Recommended parameters:
#   count: 5 (limit results)
#   language: "en"
#   format: "json"
#
# Response structure:
#   data["results"][0]["latitude"]  -> float
#   data["results"][0]["longitude"] -> float
#   data["results"][0]["name"]      -> string
#   data["results"][0]["admin1"]    -> string (may be absent)
#   data["results"][0]["country"]   -> string
#
# Error cases:
#   - Empty results array if city not found
#   - Network errors (timeout, connection)
#   - Malformed responses (missing keys)

weather_spec.txt

# Weather Forecast API Implementation
# Endpoint: https://api.open-meteo.com/v1/forecast
#
# Required parameters:
#   latitude: float from geocoding
#   longitude: float from geocoding
#
# Weather data parameters:
#   current: ["temperature_2m", "relative_humidity_2m", 
#            "apparent_temperature", "weather_code",
#            "wind_speed_10m", "wind_direction_10m"]
#   daily: ["temperature_2m_max", "temperature_2m_min",
#          "weather_code", "precipitation_sum"]
#
# Configuration:
#   timezone: "auto"
#   forecast_days: 5
#
# Response structure:
#   data["current"]["temperature_2m"] -> float
#   data["current_units"]["temperature_2m"] -> "°C"
#   data["daily"]["time"] -> ["2026-05-05", "2026-05-06", ...]
#   data["daily"]["temperature_2m_max"] -> [10.2, 9.8, ...]
#
# Weather codes:
#   0: Clear sky, 1-3: Cloudy, 61-65: Rain, 71-75: Snow
#   Need lookup table for user-friendly descriptions

Those two notes files capture the endpoints, the parameters worth setting, the response navigation paths, and the edge cases. With that in hand, the next page builds the geocoding layer without needing to bounce back to a browser tab.