weather

README

weather-can

Introduction

weather-can is a simple api written in go for accessing weather information published by the Meteorological Service of Canada.

Usage

weather-can can be installed using go modules:

go get -u github.com/shauncampbell/weather-can

Retrieving the current conditions in a particular city

Firstly, create a new weather object. There are no arguments required to do this.

w, err := weather.New()
if err != nil {
   // do something.
   return
}

The weather data is split into sites/cities. The API allows matching on the site/city by either its english or its french name. For convenience the API contains constants for each of the provinces and territories as well as codes for the english and french languages.

The example below retrieves the site for burlington, ontario matching on its english name (in this case the english and french are the same anyway). The capitalisation of the city doesn't matter either.

f, err := w.GetSite("Burlington", weather.Ontario, weather.English)
if err != nil {
    // do something.
    return
}

Finally, once there is a site then the data for that city/site can be retrieved. The function called GetSiteData returns data about the site including current conditions and expected forecast conditions.

c, err := f.GetSiteData(weather.English)
if err != nil {
    // do something.
    return
}

With the site data retrieved the information can be put to some use. The following example prints out the current temperature for Burlington, ON.

fmt.Printf("in %s, %s it is currently %.2f %s\n", f.EnglishName, f.Province, c.CurrentConditions.Temperature.Value, c.CurrentConditions.Temperature.Units)

Documentation

Index

• type AirPressure
• type CurrentConditions
• type DateTime
  • func (d DateTime) ToTime() time.Time
• type IconCode
• type Language
• type Location
• type MetricWithUnits
• type MetricWithUnitsAndType
• type NameCodedItem
• type NameCodedLocation
• type Province
• type RiseSet
• type Site
  • func (s *Site) GetSiteData(language Language) (*SiteData, error)
• type SiteData
• type SiteList
• type Weather
  • func New() (*Weather, error)
  • func (w *Weather) GetSite(name string, province Province, language Language) (*Site, error)
• type Wind

Types

type AirPressure

type AirPressure struct {
	UnitType string  `xml:"unitType,attr"` //	UnitType the type of units associated with the value (e.g. Metric or imperial).
	Units    string  `xml:"units,attr"`    // Units is the actual unit of measurement of the value (e.g. kPa)
	Change   float64 `xml:"change,attr"`   //	Change is a measure of how much the value has changed since the last reading.
	Tendency string  `xml:"tendency,attr"` // Tendency is the trend of the measurement (is it going up or going down).
	Value    float64 `xml:",chardata"`     // Value is the actual value of the measurement.
}

AirPressure provides information about air pressure.

type CurrentConditions

type CurrentConditions struct {
	Station          NameCodedLocation      `xml:"station"`          // Station provides information about where the current conditions were recorded.
	Dates            []DateTime             `xml:"dateTime"`         // Dates provides an array of times about when the current conditions were recorded.
	IconCode         IconCode               `xml:"iconCode"`         // IconCode
	Temperature      MetricWithUnitsAndType `xml:"temperature"`      // Temperature provides information on the current temperature.
	DewPoint         MetricWithUnitsAndType `xml:"dewpoint"`         // DewPoint provides information on the current dew point.
	Humidex          MetricWithUnitsAndType `xml:"humidex"`          // Humidex provides information on the current humidex.
	AirPressure      AirPressure            `xml:"pressure"`         // AirPressure provides information on air pressure.
	Visibility       MetricWithUnitsAndType `xml:"visibility"`       // Visibility provides information on current visibility.
	RelativeHumidity MetricWithUnits        `xml:"relativeHumidity"` // RelativeHumidity provides information on the current humidity.
	Wind             Wind                   `xml:"wind"`             // Wind provides current wind speeds and gusts.
}

CurrentConditions represent the most recently recorded weather conditions.

type DateTime

type DateTime struct {
	Name      string  `xml:"name,attr"`      // Name is the title of what the DateTime object represents.
	Zone      string  `xml:"zone,attr"`      // Zone is the name of the timezone that the DateTime object is relative to.
	UTCOffset float64 `xml:"UTCOffset,attr"` // UTCOffset is the number of hours that the specified timezone differs from UTC.
	Year      int     `xml:"year"`           // Year is the year in which the event occurred.
	Month     struct {
		Number int    `xml:",chardata"` // Number is the month represented as an integer, e.g. february = 2
		Name   string `xml:"name,attr"` // Name is the month represented as a text string in english or french.
	} `xml:"month"` // Month is month in which the event occurred.
	Day struct {
		Number int    `xml:",chardata"` // Number is the day of the month represented as an integer, e.g. 25
		Name   string `xml:"name,attr"` // Name is the day of the month represented as a text string in english or french, e.g. Friday
	} `xml:"day"` // Day is the day of the month on which the event occurred.
	Hour      int    `xml:"hour"`        // Hour is the hour of the day when the event occurred.
	Minute    int    `xml:"minute"`      // Minute is the minute of the day when the event occurred.
	Timestamp string `xml:"timeStamp"`   // TimeStamp is a timestamp in the form of yyyymmddhhiiss where all times are UTC.
	Summary   string `xml:"textSummary"` // Summary is a text summary of the DateTime e.g. Thursday June 11, 2020 at 19:30 UTC
}

DateTime represents a point in time specified in the response

func (DateTime) ToTime

func (d DateTime) ToTime() time.Time

ToTime creates a new time object from the current object.

type IconCode

type IconCode struct {
	Format string `xml:"format,attr"` // Format describes the format of the IconCode.
}

IconCode

type Language

type Language string

const (
	English Language = "e"
	French  Language = "f"
)

type Location

type Location struct {
	Continent string            `xml:"continent"` // Continent is the name of the continent that the site is located.
	Country   NameCodedItem     `xml:"country"`   // Country is the name of the country that the site is located.
	Province  NameCodedItem     `xml:"province"`  // Province is the name of the province/state that the site is located.
	Site      NameCodedLocation `xml:"name"`      // Site provides information about the site such as site code, name and lat long coordinates.
	Region    string            `xml:"region"`    // Region provides a textual description of the area in which the site is located.
}

Location represents a specific place.

type MetricWithUnits

type MetricWithUnits struct {
	Units string  `xml:"units,attr"` // Units is the actual units being used (km/h)
	Value float64 `xml:",chardata"`  // Value is the value of the reading.
}

MetricWithUnitsAndType describes an item which has a value, but also contains its units and assumed to be metric type.

type MetricWithUnitsAndType

type MetricWithUnitsAndType struct {
	UnitType string  `xml:"unitType,attr"` // UnitType is the type of the unit being used (e.g. Metric or imperial)
	Units    string  `xml:"units,attr"`    // Units is the actual units being used (km/h)
	Value    float64 `xml:",chardata"`     // Value is the value of the reading.
}

MetricWithUnitsAndType describes an item which has a value, but also contains its units and unit type.

type NameCodedItem

type NameCodedItem struct {
	Code string `xml:"code,attr"` // Code is the code which represents this item.
	Name string `xml:",chardata"` // Name is the friendly name which represents this item.
}

NameCodedItem describes an item which is identified by both a human friendly name and also a code.

type NameCodedLocation

type NameCodedLocation struct {
	Code      string `xml:"code,attr"` // Code is a code to describe the location.
	Latitude  string `xml:"lat,attr"`  // Latitude is the latitude coordinates of the location.
	Longitude string `xml:"lon,attr"`  // Longitude is the longitude coordinates of the location.
	Name      string `xml:",chardata"` // Name is a name given to the location.
}

NamedCodedLocation represents a location with a name, code and coordinates.

type Province

type Province string

const (
	NewfoundLandAndLabrador Province = "NL"
	PrinceEdwardIsland      Province = "PEI"
	NovaScotia              Province = "NS"
	NewBrunswick            Province = "NB"
	Quebec                  Province = "QC"
	Ontario                 Province = "ON"
	Manitoba                Province = "MB"
	Saskatchewan            Province = "SK"
	Alberta                 Province = "AB"
	BritishColumbia         Province = "BC"
	Yukon                   Province = "YT"
	NorthwestTerritories    Province = "NT"
	Nunavut                 Province = "NU"
)

type RiseSet

type RiseSet struct {
	Disclaimer string     `xml:"disclaimer"` // Legal disclaimer included with the sunrise/sunset data.
	DateTime   []DateTime `xml:"dateTime"`   // List of date and times associated with the rising and setting of the sun.
}

type Site

type Site struct {
	Code        string   `xml:"code,attr"`
	EnglishName string   `xml:"nameEn"`
	FrenchName  string   `xml:"nameFr"`
	Province    Province `xml:"provinceCode"`
}

func (*Site) GetSiteData

func (s *Site) GetSiteData(language Language) (*SiteData, error)

type SiteData

type SiteData struct {
	License           string            `xml:"license"`           //	License contains licensing information
	Dates             []DateTime        `xml:"dateTime"`          // Dates describes some important dates and times associated with the data.
	Location          Location          `xml:"location"`          // Location describes the location that this data relates to.
	CurrentConditions CurrentConditions `xml:"currentConditions"` // CurrentConditions describes the current weather conditions at the location.
	RiseSet           RiseSet           `xml:"riseSet"`           // RiseSet describes the sunrise and sunset times for the location
}

SiteData represents all the information about a site. TODO: Pull in forecasts.

type SiteList

type SiteList struct {
	Sites []Site `xml:"site"`
}

type Weather

type Weather struct {
	Sites *SiteList
}

func New

func New() (*Weather, error)

func (*Weather) GetSite

func (w *Weather) GetSite(name string, province Province, language Language) (*Site, error)

type Wind

type Wind struct {
	Speed     MetricWithUnitsAndType `xml:"speed"`     // Speed describes the current sustained wind speed.
	Gust      MetricWithUnitsAndType `xml:"gust"`      // Gust describes the speed of periodic wind gusts.
	Direction string                 `xml:"direction"` //	Direction describes the direction that the wind is coming from.
	Bearing   MetricWithUnits        `xml:"bearing"`   // Bearing provides a compass bearing for the wind direction.
}

Wind provides information about wind speeds.