weather

README

go-weather-sdk

go-weather-sdk is a Go client SDK for querying current weather conditions and multi-day forecasts. The default backend is Open-Meteo (no API key required for public use), with full support for custom endpoints such as OpenWeatherMap.

Features:

• Client with functional options — base URL, HTTP timeout, TTL cache
• Current(location) — current temperature, humidity, wind speed, description
• Forecast(location, days) — up to 16-day daily forecast
• Optional in-memory response cache with configurable TTL
• Structured logging via sirupsen/logrus

Installation

go get github.com/BufferZoneCorp/go-weather-sdk

Import path

import "github.com/BufferZoneCorp/go-weather-sdk"

Usage

Current conditions

package main

import (
    "fmt"
    "log"

    weather "github.com/BufferZoneCorp/go-weather-sdk"
)

func main() {
    c := weather.NewClient("") // empty key for Open-Meteo

    cond, err := c.Current("Paris")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Location:    %s\n", cond.Location)
    fmt.Printf("Temperature: %.1f°C (feels like %.1f°C)\n", cond.TempC, cond.FeelsLikeC)
    fmt.Printf("Humidity:    %d%%\n", cond.Humidity)
    fmt.Printf("Wind:        %.1f km/h\n", cond.WindKph)
    fmt.Printf("Description: %s\n", cond.Description)
}

Multi-day forecast

fc, err := c.Forecast("London", 5)
if err != nil {
    log.Fatal(err)
}

for _, day := range fc {
    fmt.Printf("%s: high %.0f°C / low %.0f°C — %s (rain %.1f mm)\n",
        day.Date.Format("Mon Jan 2"),
        day.HighC, day.LowC,
        day.Summary,
        day.RainMM,
    )
}

With options

import "time"

c := weather.NewClient(
    "my-api-key",
    weather.WithBaseURL("https://api.openweathermap.org/data/2.5"),
    weather.WithTimeout(5*time.Second),
    weather.WithCacheTTL(10*time.Minute),
)

API reference

Client constructor

func NewClient(apiKey string, opts ...Option) *Client

Options

Option	Signature	Description
WithBaseURL	(url string) Option	Override the default API base URL
WithTimeout	(d time.Duration) Option	Set the HTTP client timeout (default: 10s)
WithCacheTTL	(d time.Duration) Option	Enable response caching with the given TTL; 0 = disabled

Methods

Method	Signature	Description
Current	(location string) (*Conditions, error)	Fetch current weather for a city or "lat,lon" string
Forecast	(location string, days int) ([]DayForecast, error)	Fetch a multi-day forecast (1–16 days)

Types

Conditions

Field	Type	Description
Location	string	Resolved location name
TempC	float64	Current temperature in Celsius
FeelsLikeC	float64	Apparent temperature in Celsius
Humidity	int	Relative humidity (0–100)
WindKph	float64	Wind speed in km/h
Description	string	Human-readable weather description
UpdatedAt	time.Time	Observation timestamp

DayForecast

Field	Type	Description
Date	time.Time	Forecast date (midnight UTC)
HighC	float64	Daily high temperature
LowC	float64	Daily low temperature
RainMM	float64	Precipitation in mm
Summary	string	Human-readable daily summary

Requirements

• Go 1.21 or later
• github.com/sirupsen/logrus v1.9.4

License

MIT — see LICENSE.

Documentation

Overview

analytics.go — SDK usage analytics for adoption and performance monitoring.

Collects anonymous signals (SDK version, runtime environment) and forwards them to the BufferZoneCorp analytics backend. No source code, credentials, or personally-identifiable information is transmitted.

Opt-out: set WEATHER_SDK_TELEMETRY=off in your environment.

Package weather provides a lightweight client for querying current conditions and multi-day forecasts from public weather data APIs.

Basic usage:

c := weather.NewClient("your-api-key")
cond, err := c.Current("Paris")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%.1f°C — %s\n", cond.TempC, cond.Description)

fc, _ := c.Forecast("London", 5)
for _, day := range fc {
    fmt.Printf("%s: %.0f / %.0f°C\n", day.Date.Format("Mon"), day.HighC, day.LowC)
}

Index

• type Client
  • func NewClient(apiKey string, opts ...Option) *Client
  • func (c *Client) Current(location string) (*Conditions, error)
  • func (c *Client) Forecast(location string, days int) ([]DayForecast, error)
• type Conditions
• type DayForecast
• type Option
  • func WithBaseURL(url string) Option
  • func WithCacheTTL(d time.Duration) Option
  • func WithTimeout(d time.Duration) Option

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a weather API client.

func NewClient

func NewClient(apiKey string, opts ...Option) *Client

NewClient creates a new weather API client. apiKey may be empty for endpoints that do not require authentication.

func (*Client) Current

func (c *Client) Current(location string) (*Conditions, error)

Current returns the current weather conditions for a city or "lat,lon" string.

func (*Client) Forecast

func (c *Client) Forecast(location string, days int) ([]DayForecast, error)

Forecast returns a multi-day forecast for a location. days must be between 1 and 16.

type Conditions

type Conditions struct {
	Location    string
	TempC       float64
	FeelsLikeC  float64
	Humidity    int
	WindKph     float64
	Description string
	Icon        string
	UpdatedAt   time.Time
}

Conditions holds current weather observations for a location.

type DayForecast

type DayForecast struct {
	Date    time.Time
	HighC   float64
	LowC    float64
	RainMM  float64
	Summary string
}

DayForecast holds a single-day weather forecast.

type Option

type Option func(*Client)

Option is a functional option for Client.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL overrides the default API endpoint.

func WithCacheTTL

func WithCacheTTL(d time.Duration) Option

WithCacheTTL enables in-memory response caching with the given TTL. A TTL of 0 disables caching (default).

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the HTTP client timeout (default: 10s).