Go API Weather

Go-Weather is a simple and efficient Go library for fetching weather information from WeatherAPI. This library allows developers to seamlessly integrate weather data into their applications.

Features

• Fetch current weather for any location.
• Retrieve forecast data for up to 14 days, with optional air quality and alerts.
• Historical weather data from 2010-01-01 onwards.
• Location search/autocomplete, astronomy, timezone, IP geolocation, and marine (tides/swell) lookups.
• Lightweight, context-aware (all calls take a context.Context).

Installation

In order to use Go-Weather, you need to have Go installed on your system. The library requires Go version 1.25.0 or higher.

go get github.com/kashifkhan0771/go-weather/v2

Usage

Import the library in your Go application. Each API resource is exposed as a service on the Client — client.Current, client.Forecast, etc.

package main

import (
    "context"
    "fmt"

    weather "github.com/kashifkhan0771/go-weather/v2"
)

func main() {
    client, err := weather.NewClient("YOUR_API_KEY")
    if err != nil {
        fmt.Println("Error creating client:", err)
        return
    }

    currentWeather, err := client.Current.Get(context.Background(), "London")
    if err != nil {
        fmt.Println("Error fetching weather:", err)
        return
    }

    fmt.Printf("Current temperature in London: %.1f°C\n", currentWeather.Current.TempC)
}

Configuration

Set up your client with the API key provided by the weather service:

client, err := weather.NewClient("YOUR_API_KEY")

Configure the client with functional options:

client, err := weather.NewClient(
    "YOUR_API_KEY",
    weather.WithTimeout(10*time.Second),
    weather.WithHTTPClient(customHTTPClient),
    weather.WithBaseURL("https://api.weatherapi.com/v1"), // mainly for testing
)

Supported Services

client.Current.Get

func (s *CurrentService) Get(ctx context.Context, query string) (*models.WeatherResponse, error)

Fetches current weather for query (city name, postal code, lat/lon, or IP).

client.Forecast.Get

func (s *ForecastService) Get(ctx context.Context, req ForecastRequest) (*models.ForecastResponse, error)

Forecast for req.Query, req.Days (1-14, defaults to 1), with req.AQI / req.Alerts to include air quality and alert data.

client.History.Get

func (s *HistoryService) Get(ctx context.Context, req HistoryRequest) (*models.HistoryResponse, error)

Historical weather for req.Query on req.Date (must be on/after 2010-01-01).

client.Search.Get

func (s *SearchService) Get(ctx context.Context, query string) ([]models.SearchResult, error)

Location search/autocomplete matches for query.

client.Astronomy.Get

func (s *AstronomyService) Get(ctx context.Context, req AstronomyRequest) (*models.AstronomyResponse, error)

Sunrise/sunset/moon data for req.Query (and optional req.Date).

client.Timezone.Get

func (s *TimezoneService) Get(ctx context.Context, query string) (*models.TimezoneResponse, error)

Time zone and local time for query.

client.IP.Get

func (s *IPService) Get(ctx context.Context, ip string) (*models.IPResponse, error)

Geographic and timezone data for an IP address (pass "auto:ip" for the caller's own IP).

client.Marine.Get

func (s *MarineService) Get(ctx context.Context, req MarineRequest) (*models.MarineResponse, error)

Marine forecast (tides, swell, sea temperature) for req.Query, req.Days (1-7, defaults to 1).

Examples

Detailed usage examples for each function are provided in the EXAMPLES.md file.

Contributing

Contributions are welcome! Please follow the steps below:

• Fork the repository.
• Create a feature branch: git checkout -b feature-name.
• Commit your changes: git commit -m 'Add new feature'.
• Push to your branch: git push origin feature-name.
• Open a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

Thanks to WeatherAPI for data integration.