gowm

gowm

A Go OpenWeatherMap API client.

Getting Started

First, make sure you have all of the below prerequisites:

• Installation of Go, e.g., from go.dev.
• API key from OpenWeatherMap
  • Sign up for free at openweathermap.org
  • Get your API key after having signed in
  • Note: API key activation may take some time

Now, you should be able to either use this project's packages in your project, or clone this repo and contribute/run the examples provided.

Examples of basic as well as advanced usage are located in the examples dir. To run any of the examples (having cloned this repo):

# e.g., the owm_basic example
go run examples/owm_basic/main.go

APIs

One Call API 3.0

The One Call API 3.0 client is implemented in onecall/client.go. The available methods are:

• CurrentAndForecast: To get access to current weather, minute forecast for 1 hour, hourly forecast for 48 hours, daily forecast for 8 days and government weather alerts.
  • CurrentAndForecastRaw is available and returns a direct mapping of the API response, e.g., not parsing timestamps to time.Time but rather leaving them as ints.

Geocoding API

The Geocoding API client is implemented in geo/client.go. The available methods are:

• Direct: Allows you to get geographical coordinates (lat, lon) by using name of the location (city name or area name).
• Reverse: Allows you to get name of the location (city name or area name) by using geographical coordinates (lat, lon).

Features

Static Types

Leveraging Go's type system, as well as generating better go enums using zarldev/goenums, using the clients is straight-forward. You don't need to worry about guessing the input format of the API calls, of for example languages and units. Rather than:

// from briandowns/openweathermap (another great OpenWeatherMap Go client and the inspiration for this project)
w, err := owm.NewOneCall("F", "EN", apiKey, []string{})
if err != nil {
  log.Fatalln(err)
}

err = w.OneCallByCoordinates(
  &Coordinates{
    Latitude:  33.45,
    Longitude: -112.07,
  },
)
if err != nil {
  t.Error(err)
}

We can instead do:

client := onecall.NewClient(&onecall.ClientOptions{
  AppID: apiKey
  Units: onecall.Units.IMPERIAL,
})

resp, err := client.CurrentAndForecast(33.45, -112.07, &onecall.OneCallOptions{
  Lang: onecall.Langs.ENGLISH,
})
if err != nil {
  log.Fatalln(err)
}

Custom http.Clients and slog.Loggers

You can pass custom HTTP clients and loggers to the API Client to make the most of Go's std lib features like rate limiting and structured logging with configurable logging levels.

Contributing

Contributions are welcome.

Disclaimer

This library is an unofficial Go client for the OpenWeather API. It is not affiliated with or endorsed by OpenWeather. See the license at LICENSE.

Use of this client requires a valid API key from OpenWeather, and use of OpenWeather data is subject to their license terms. Please ensure you comply with their data licensing conditions, particularly around attribution and share-alike requirements.