Go Dark Sky API

Powered by Dark Sky

GoDoc Build Status Coverage Status

A #golang package to consume Dark Sky Forecast and Time Machine API calls.

Getting Started with the Dark Sky API

All usage requires a Dark Sky API key, which you can obtain from the Dark Sky developer site.

To use the Go libary client, instantiate a darksky.Client with your Dark Sky API key:

lat := "47.202"
lng := "-123.4167"

client := darksky.NewClient("APIKEYHERE")
f, err := client.GetForecast(lat, lng, darksky.Defaults)
if err != nil {
  // Handle error

See the Forecast, DataBlock, and DataPoint structs to get a picture of the shape of the returned data.

You may also want to explore the Dark Sky Response Format documentation, which explains when each property is expected to be populated (note that DataPoint) will be very sparse for certain kinds of output.

Chances are, you're looking for the current temperature and a weather summary. Get those thusly:

fmt.Println("Summary:     " + f.Currently.Summary)
fmt.Printf("Temperature: %.2f\n",f.Currently.Temperature)
fmt.Println("Icon:        " + f.Currently.Icon)

Dark Sky Time Machine Usage

The Dark Sky API supports requests for retrieving weather data in the past and the future through time machine calls. Use GetTimeMachineForecast(lat, lng, time, args) to retrieve time machine data.

lat := "47.202"
lng := "-123.4167"
lastYear := time.Now().AddDate(-1,0,0)

client := darksky.Client("APIKEYHERE")
f, err := client.GetTimeMachineForecast(lat, lng, lastYear, darksky.Defaults)
if err != nil {
  // Handle error

API Arguments

The Dark Sky API accepts a few modification parameters. Set these via a darksky.Arguments. If you want the default behavior, use darksky.Defaults. If you're looking only for the Currently data object, then you should use darksky.CurrentOnly instead. Examples:

// No query string parameters (i.e. URL ends with /lat,lng)
f, err := client.GetForecast(lat,lng,darksky.Defaults)

// Currently block only (i.e URL ends with /lat,lng?excludes=minutely,hourly,daily,alerts,flags)
f, err := client.GetForecast(lat,lng,darksky.CurrentOnly)

If you'd like to set your own excludes= list, or set other arguments, you'll need to construct a darksky.Arguments directly. The type is a simple map[string]string:

// Custom query string parameters (/lat,lng?excludes=minutely&units=si&extend=hourly)
f, err := client.GetForecast(lat,lng,darksky.Arguments{"excludes":"minutely","units": "si", "extend": "hourly"})

A Note About time.Time and darksky.Time

The Dark Sky API uses Unix timestamps everywhere times are represented. For #golang developer convenience, this package uses time.Time where possible. The time values inside Forecast, however, are of type darksky.Time, which wraps time.Time. You can use .Time to get the underlying time.Time value, and you can call Time methods directly as well.

f, err := client.GetTimeMachineForecast(lat, lng, lastYear, darksky.Defaults)

actualTime := f.Currently.Time.Time

fmt.Sprintf("Temp: %.2f\n", f.Currently.Temperature)
fmt.Sprintf("Time: %s\n", f.Currently.Time.Format("2006-01-02 15:04:05"))
fmt.Sprintf("Time: %s\n", actualTime.String())




View Source


View Source
var CurrentOnly = Arguments{"exclude": "minutely,hourly,daily,alerts,flags"}
View Source
var CurrentWithAlerts = Arguments{"exclude": "minutely,hourly,daily,flags"}
View Source
var Defaults = make(Arguments)


This section is empty.


type Alert

type Alert struct {
	Title       string `json:"title"`
	Description string `json:"description"`
	URI         string `json:"uri"`
	Expires     int    `json:"expires"`

type Arguments

type Arguments map[string]string

func (Arguments) ToURLValues

func (args Arguments) ToURLValues() url.Values

type Client

type Client struct {
	BaseURL string
	APIKey  string
	// contains filtered or unexported fields

func NewClient

func NewClient(apiKey string) *Client

func (*Client) Get

func (c *Client) Get(path string, args Arguments) (Forecast *Forecast, err error)

func (*Client) GetCtx

func (c *Client) GetCtx(ctx context.Context, path string, args Arguments) (forecast *Forecast, err error)

func (*Client) GetForecast

func (c *Client) GetForecast(lat, lng string, args Arguments) (forecast *Forecast, err error)

func (*Client) GetForecastCtx

func (c *Client) GetForecastCtx(ctx context.Context, lat, lng string, args Arguments) (forecast *Forecast, err error)

func (*Client) GetTimeMachineForecast

func (c *Client) GetTimeMachineForecast(lat, lng string, t time.Time, args Arguments) (forecast *Forecast, err error)

func (*Client) GetTimeMachineForecastCtx

func (c *Client) GetTimeMachineForecastCtx(ctx context.Context, lat, lng string, t time.Time, args Arguments) (forecast *Forecast, err error)

type DataBlock

type DataBlock struct {
	Summary string      `json:"summary"`
	Icon    string      `json:"icon"`
	Data    []DataPoint `json:"data"`

type DataPoint

type DataPoint struct {
	ApparentTemperature        float64 `json:"apparentTemperature,omitempty"`
	ApparentTemperatureMax     float64 `json:"apparentTemperatureMax,omitempty"`
	ApparentTemperatureMaxTime *Time   `json:"apparentTemperatureMaxTime,omitempty"`
	ApparentTemperatureMin     float64 `json:"apparentTemperatureMin,omitempty"`
	ApparentTemperatureMinTime *Time   `json:"apparentTemperatureMinTime,omitempty"`
	CloudCover                 float64 `json:"cloudCover,omitempty"`
	DewPoint                   float64 `json:"dewPoint,omitempty"`
	Humidity                   float64 `json:"humidity,omitempty"`
	Icon                       string  `json:"icon,omitempty"`
	MoonPhase                  float64 `json:"moonPhase,omitempty"`
	NearestStormBearing        float64 `json:"nearestStormBearing,omitempty"`
	NearestStormDistance       float64 `json:"nearestStormDistance,omitempty"`
	Ozone                      float64 `json:"ozone,omitempty"`
	PrecipAccumulation         float64 `json:"precipAccumulation"`
	PrecipIntensity            float64 `json:"precipIntensity"`
	PrecipIntensityMax         float64 `json:"precipIntensityMax"`
	PrecipIntensityMaxTime     *Time   `json:"precipIntensityMaxTime,omitempty"`
	PrecipProbability          float64 `json:"precipProbability"`
	PrecipType                 string  `json:"precipType"`
	Pressure                   float64 `json:"pressure"`
	Summary                    string  `json:"summary"`
	SunriseTime                float64 `json:"sunriseTime"`
	SunsetTime                 float64 `json:"sunsetTime"`
	Temperature                float64 `json:"temperature"`
	TemperatureMax             float64 `json:"temperatureMax"`
	TemperatureMaxTime         float64 `json:"temperatureMaxTime"`
	TemperatureMin             float64 `json:"temperatureMin"`
	TemperatureMinTime         float64 `json:"temperatureMinTime"`
	Time                       Time    `json:"time"`
	Visibility                 float64 `json:"visibility"`
	WindBearing                float64 `json:"windBearing"`
	WindSpeed                  float64 `json:"windSpeed"`

type Flags

type Flags struct {
	DarkSkyUnavailable string   `json:"darksky-unavailable"`
	Sources            []string `json:"sources"`
	Units              string   `json:"units"`

type Forecast

type Forecast struct {
	Latitude  float64    `json:"latitude"`
	Longitude float64    `json:"longitude"`
	Timezone  string     `json:"timezone"`
	Currently *DataPoint `json:"currently,omitempty"`
	Minutely  *DataBlock `json:"minutely,omitempty"`
	Hourly    *DataBlock `json:"hourly,omitempty"`
	Daily     *DataBlock `json:"daily,omitempty"`
	Alerts    []Alert    `json:"alerts,omitempty"`
	Flags     *Flags     `json:"flags,omitempty"`

type Time

type Time struct {

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(b []byte) (err error)