Skip to main content

How to Type OpenWeather Query Items in a Swift API Client

Updated 6 min readMarkdown
Part of seriesOpenWeather tutorial
How to Type OpenWeather Query Items in a Swift API Client

In this tutorial we will learn how to replace a stringly typed OpenWeather query dictionary with a small Swift struct. In How to Build a Bare-Bones Async JSON Client in Swift we passed appid, lat, lon, and units as a [String: String] into response. That works, but the keys are magic strings and every value is already a String—even latitude and longitude. We will teach the client to accept any value that can produce [URLQueryItem], then model Current Weather’s query as a named type.

Getting Started

The earlier client post left the call site looking like this:

let apiKey = "YOUR_API_KEY"
let path = "data/2.5/weather"
let queryItems = [
  "appid": apiKey,
  "lat": "40.6501",
  "lon": "-73.9496",
  "units": "imperial",
]

let forecast: CurrentWeather = try await client.response(
  endpoint: .init(path: path),
  queryItems: queryItems
)

The endpoint is still only a path and a method. The query rides on response, the same place a request body would. Nothing about that division changes. What changes is the type of queryItems: instead of always demanding [String: String], the client will ask for something that can produce [URLQueryItem]—the same values URLComponents already understands.

Naming the Query Type

Introduce a tiny protocol whose only job is to expose query items the URL builder can attach as-is:

protocol QueryItemsConvertible {
  var queryItems: [URLQueryItem] { get }
}

extension [String: String]: QueryItemsConvertible {
  var queryItems: [URLQueryItem] {
    map { URLQueryItem(name: $0.key, value: $0.value) }
  }
}

Dictionary literals keep working: [String: String] conforms by mapping each entry to a URLQueryItem, so existing call sites compile. Custom types opt in by returning [URLQueryItem] directly. Going through URLQueryItem instead of a second dictionary means repeated names, bare keys, and source order can survive into the URL when an API needs them.

Endpoint gains a third generic parameter so each endpoint can name the query type it expects, alongside the request and response body types you already had:

struct Endpoint<QueryItems, RequestBody, ResponseBody> {
  let method: String
  let path: String

  init(
    path: String,
    method: String = "GET"
  ) {
    self.path = path
    self.method = method
  }
}

typealias VoidRequestBodyEndpoint<QueryItems, ResponseBody> =
  Endpoint<QueryItems, Void, ResponseBody>

The GET overload now constrains QueryItems to QueryItemsConvertible and takes a value of that type instead of a bare dictionary:

extension APIClient {
  func response<QueryItems: QueryItemsConvertible, ResponseBody: Decodable>(
    endpoint: VoidRequestBodyEndpoint<QueryItems, ResponseBody>,
    queryItems: QueryItems
  ) async throws -> ResponseBody {
    let url = url(for: endpoint.path, queryItems: queryItems)
    let request = request(url: url, method: endpoint.method)
    let data = try await performRequest(request)
    return try decoder.decode(ResponseBody.self, from: data)
  }
}

The earlier client post mapped a [String: String] into URLQueryItem values inside url(for:queryItems:). With QueryItemsConvertible, that helper takes the convertible value, asks it for [URLQueryItem], and assigns the array straight onto URLComponents:

extension APIClient {
  private func url(for path: String, queryItems: some QueryItemsConvertible) -> URL {
    let items = queryItems.queryItems
    let url = baseURL.appending(path: path)
    guard !items.isEmpty,
          var components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
      return url
    }

    components.queryItems = items
    return components.url ?? url
  }
}

Dictionary call sites still go through the [String: String] conformance’s map. Typed queries skip that hop and hand the client the wire-ready items. The networking core does not learn about OpenWeather; it only learns how to ask any query value for [URLQueryItem].

A Current Weather Query Struct

Current Weather always wants the same four parameters. Give them a home:

struct CurrentWeatherQuery: QueryItemsConvertible {
  let appid: String
  let lat: Double
  let lon: Double
  let units: String

  var queryItems: [URLQueryItem] {
    [
      URLQueryItem(name: "appid", value: appid),
      URLQueryItem(name: "lat", value: String(lat)),
      URLQueryItem(name: "lon", value: String(lon)),
      URLQueryItem(name: "units", value: units),
    ]
  }
}

appid and units stay strings because that is how OpenWeather’s query string spells them. lat and lon can be Double in your model; the computed queryItems property is where they become the decimal strings the API expects. Forgetting a field is now a compile error. Typos in key names—“appId” instead of “appid”—stop living at every call site and live in one array of URLQueryItem values inside the type.

Pin the endpoint’s query generic to that struct when you want the type system to enforce it:

let weatherEndpoint = Endpoint<CurrentWeatherQuery, Void, CurrentWeather>(
  path: "data/2.5/weather"
)

Or keep using VoidRequestBodyEndpoint<CurrentWeatherQuery, CurrentWeather> if you prefer the alias. A call that passes a plain [String: String] no longer type-checks against that endpoint; a call that passes CurrentWeatherQuery does.

Wiring the Call Site

Build the query value, then hand it to response the same way you used to hand over the dictionary:

let query = CurrentWeatherQuery(
  appid: "YOUR_API_KEY",
  lat: 40.6501,
  lon: -73.9496,
  units: "imperial"
)

let forecast: CurrentWeather = try await client.response(
  endpoint: weatherEndpoint,
  queryItems: query
)

Use your own coordinates; the numbers above are only a sample. Replace YOUR_API_KEY with the key from your OpenWeather account—the loading strategy (hard-coded placeholder, scheme environment variable, or .xcconfig) is independent of how the query is typed. Dictionary call sites remain available for endpoints that have not earned a struct yet, because [String: String] still conforms to QueryItemsConvertible.

Why Bother

A dictionary is the right first step: it matches how query strings look on the wire, and it kept the first client tutorial small. A struct earns its keep when the same parameter set shows up at more than one call site, or when a wrong key would fail only at runtime against OpenWeather.

Typed queries give you:

  • Required fields — omit units and the compiler complains before you hit the network.

  • Real types at the edge — lat / lon as Double in app code; stringification stays in queryItems.

  • One spelling of each key — OpenWeather’s appid lives in a single URLQueryItem list inside the type, not in every screen that loads a forecast.

  • Endpoint-shaped documentation — Endpoint<CurrentWeatherQuery, Void, CurrentWeather> reads as “this GET takes that query and returns that body,” the same way request-body generics already document POST shapes.

You do not need a struct for every endpoint on day one. Start with Current Weather, leave quieter calls on dictionaries, and promote a query type when the parameter list stabilizes.

Conclusion

We’ve taken the bare-bones client from How to Build a Bare-Bones Async JSON Client in Swift and typed its query parameter the way the body types were already typed: a QueryItemsConvertible value on response, and an Endpoint generic that names which query belongs with which path. A CurrentWeatherQuery struct turns appid, lat, lon, and units into fields instead of dictionary keys, while dictionaries remain a valid escape hatch. From here you can add a 5-day query type with its own fields, or keep Stations-style appid-only calls as a one-property struct when you want the same pattern everywhere.

Cover: Black pen and peach sticky notes rest on a silver laptop keyboard by Rashed Hossain, CC0 1.0.

No comments yet. Be the first to comment.