metservice

README

metservice-go

A go library for reading weather data from Metservice. Unfortunately this API isn't documented and probably not even intended for public usage. Reading through the godocs documentation will give you an idea of the values the API will return, but the best way to figure it out is just messing with it a bit.

For a longer more practical example see metweather a cli app built with this library.

Discussion and patches can be found here.

Example

import (
	"context"
	"fmt"

	"git.sr.ht/~kota/metservice-go"
)

func main() {
	client := NewClient()
	ctx := context.Background()

	forecast, _, err := client.GetForecast(ctx, "Dunedin")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(*forecast.LocationIPS)
	for _, day := range forecast.Days {
		fmt.Printf("%v\nforecast: %v\nmax: %vC\nmin: %vC\n\n",
			*day.Date,
			*day.ForecastWord,
			*day.Max,
			*day.Min)
	}
}

Documentation

Overview

metservice is a library for reading weather data from Metservice.

Index

• Constants
• func Bool(v bool) *bool
• func Float64(v float64) *float64
• func Int(v int) *int
• func String(v string) *string
• type Client
  • func NewClient() *Client
  • func (c *Client) Do(ctx context.Context, path string, v interface{}) (*http.Response, error)
  • func (c *Client) GetForecast(ctx context.Context, location string) (*Forecast, *http.Response, error)
  • func (c *Client) GetObservation(ctx context.Context, location string) (*Observation, *http.Response, error)
  • func (c *Client) GetObservationForecastHours(ctx context.Context, location string) (*ObservationForecastHours, *http.Response, error)
  • func (c *Client) GetObservationOneMin(ctx context.Context, location string) (*ObservationOneMin, *http.Response, error)
  • func (c *Client) GetPollen(ctx context.Context, location string) (*Pollen, *http.Response, error)
  • func (c *Client) GetRiseSet(ctx context.Context, location string) (*RiseSet, *http.Response, error)
• type DayPart
• type DayPartTime
• type Forecast
• type ForecastDay
• type ForecastHour
• type Observation
• type ObservationForecastHours
• type ObservationHour
• type ObservationOneMin
• type ObservationThreeHour
• type ObservationTwentyFourHour
• type Pollen
• type PollenDay
• type RiseSet
• type StatusError
  • func (e StatusError) Error() string
• type Timestamp
  • func (t Timestamp) Equal(u Timestamp) bool
  • func (t Timestamp) String() string
  • func (t *Timestamp) UnmarshalJSON(data []byte) (err error)

Examples

• Forecast
• RiseSet

Constants

const BaseURL = "https://www.metservice.com/publicData/"

BaseURL is the default base URL for the metservice JSON API.

Functions

func Bool

func Bool(v bool) *bool

Bool is a helper routine that allocates a new bool value to store v and returns a pointer to it.

func Float64

func Float64(v float64) *float64

Float64 is a helper routine that allocates a new float64 value to store v and returns a pointer to it.

func Int

func Int(v int) *int

Int is a helper routine that allocates a new int value to store v and returns a pointer to it.

func String

func String(v string) *string

String is a helper routine that allocates a new string value to store v and returns a pointer to it.

Types

type Client

type Client struct {
	HTTPClient *http.Client
	BaseURL    string
}

Client used for metservice-go.

func NewClient

func NewClient() *Client

NewClient constructs a client using http.DefaultClient and the default base URL. The returned client is ready for use.

func (*Client) Do

func (c *Client) Do(ctx context.Context, path string, v interface{}) (*http.Response, error)

Do sends an API request and returns the API responce. The API responce is JSON decoded and stored in the value pointed to by v, or returned as an error if an API error has occured. If v is nil, and no error happens, the responce is returned as is.

func (*Client) GetForecast

func (c *Client) GetForecast(ctx context.Context, location string) (*Forecast, *http.Response, error)

GetForecast gets a Forecast for a given location using a context. The location string should be capitalized - i.e. Dunedin. A list of possible locations can be found here https://www.metservice.com/towns-cities/

func (*Client) GetObservation

func (c *Client) GetObservation(ctx context.Context, location string) (*Observation, *http.Response, error)

GetObservation gets an Observation for a given location. The location string should be capitalized - i.e. Dunedin. A list of possible locations can be found here https://www.metservice.com/towns-cities/

func (*Client) GetObservationForecastHours

func (c *Client) GetObservationForecastHours(ctx context.Context, location string) (*ObservationForecastHours, *http.Response, error)

GetObservationForecastHours gets an ObservationForecastHours containing hourly observations and forecasts for about a 48 hour period for a specific location.

func (*Client) GetObservationOneMin

func (c *Client) GetObservationOneMin(ctx context.Context, location string) (*ObservationOneMin, *http.Response, error)

GetObservationOneMin gets an Observation for a given location. The location string should be capitalized - i.e. Dunedin. A list of possible locations can be found here https://www.metservice.com/towns-cities/

func (*Client) GetPollen

func (c *Client) GetPollen(ctx context.Context, location string) (*Pollen, *http.Response, error)

GetPollen gets a Pollen representing the pollen/alergy data for the next few days for a given location. The location string should be capitalized - i.e. Dunedin. A list of possible locations can be found here https://www.metservice.com/towns-cities/

func (*Client) GetRiseSet

func (c *Client) GetRiseSet(ctx context.Context, location string) (*RiseSet, *http.Response, error)

GetRiseSet gets a RiseSet representing the sun/moon rise and set times for the current day for a given location. The location string should be capitalized - i.e. Dunedin. A list of possible locations can be found here https://www.metservice.com/towns-cities/

type DayPart

type DayPart struct {
	Afternoon *DayPartTime `json:"afternoon"`
	Evening   *DayPartTime `json:"evening"`
	Morning   *DayPartTime `json:"morning"`
	Overnight *DayPartTime `json:"overnight"`
}

DayPart contains DayPartTimes for parts of a ForecastDay.

type DayPartTime

type DayPartTime struct {
	ForecastWord *string `json:"forecastWord"`
	IconType     *string `json:"iconType"`
}

DayPartTime contains a forecast word and icon type.

type Forecast

type Forecast struct {
	// TODO: Implement targeting field
	Days                 []ForecastDay `json:"days"`
	LocationGFS          *int          `json:"locationGFS,string"`
	LocationIPS          *string       `json:"locationIPS"`
	LocationWASP         *string       `json:"locationWASP"`
	SaturdayForecastWord *string       `json:"saturdayForecastWord"`
	SundayForcastWord    *string       `json:"sundayForecastWord"`
}

Forecast represents a metservice forecast.

Example

client := NewClient()
ctx := context.Background()

forecast, _, err := client.GetForecast(ctx, "Dunedin")
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(*forecast.LocationIPS)
for _, day := range forecast.Days {
	fmt.Printf("%v\nforecast: %v\nmax: %vC\nmin: %vC\n\n",
		*day.Date,
		*day.ForecastWord,
		*day.Max,
		*day.Min)
}

type ForecastDay

type ForecastDay struct {
	Date         *Timestamp `json:"dateISO"`
	Forecast     *string    `json:"forecast"`
	ForecastWord *string    `json:"forecastWord"`
	IssuedAt     *Timestamp `json:"issuedAtISO"`
	Max          *int       `json:"max,string"`
	Min          *int       `json:"min,string"`
	Part         *DayPart   `json:"partDayData"`
	RiseSet      *RiseSet   `json:"riseSet"`
	Source       *string    `json:"source"`
	SourceTemps  *string    `json:"sourceTemps"`
}

ForecastDay represents a day in a Forecast.

type ForecastHour

type ForecastHour struct {
	Date          *Timestamp `json:"dateISO"`
	Humidity      *int       `json:"humidity,string"`
	Offset        *int       `json:"offset"`
	Rainfall      *float64   `json:"rainfall,string"`
	Temp          *int       `json:"temperature,string"`
	WindDirection *string    `json:"windDir"`
	WindSpeed     *int       `json:"windSpeed,string"`
}

ForecastHour represents forecast data for a specific hour. This data is obtained from GetObservationForecastHours.

type Observation

type Observation struct {
	ID             *string                    `json:"id"`
	Location       *string                    `json:"location"`
	LocationID     *int                       `json:"locationId,string"`
	ThreeHour      *ObservationThreeHour      `json:"threeHour"`
	TwentyFourHour *ObservationTwentyFourHour `json:"twentyFourHour"`
}

Observation represents a recent metservice observation.

type ObservationForecastHours

type ObservationForecastHours struct {
	Observations          []ObservationHour `json:"actualData"`
	Forecasts             []ForecastHour    `json:"forecastData"`
	Count                 *int              `json:"dataPointCount"`
	WindSpeed             *int              `json:"latestObsWindSpeed"`
	Location              *string           `json:"location"`
	LocationName          *string           `json:"locationName"`
	RainfallTotalForecast *float64          `json:"rainfallTotalForecast"`
	RainfallTotalObserved *float64          `json:"rainfallTotalObserved"`
}

ObservationForecastHours represents observation and forecast data hourly, usually for around 48 hours with 9 or 10 observations and the rest being forecasts. I felt some fields were redundant so I ignored them.

type ObservationHour

type ObservationHour struct {
	Date          *Timestamp `json:"dateISO"`
	Offset        *int       `json:"offset"`
	Rainfall      *float64   `json:"rainfall,string"`
	Temp          *float64   `json:"temperature,string"`
	WindDirection *string    `json:"windDir"`
	WindSpeed     *int       `json:"windSpeed,string"`
}

ObservationHour represents observation data for a specific hour. This data is obtained from GetObservationForecastHours.

type ObservationOneMin

type ObservationOneMin struct {
	ClothingLayers   *string    `json:"clothingLayers"`
	Current          *bool      `json:"isObservationCurrent"`
	Past             *string    `json:"past"`
	Rainfall         *float64   `json:"rainfall,string"`
	RelativeHumidity *int       `json:"relativeHumidity,string"`
	Status           *string    `json:"status"`
	Date             *Timestamp `json:"timeISO"`
	WindProofLayers  *int       `json:"windProofLayers,string"`
}

ObservationOneMin represents observation data updated to the minute. It has less detail than the daily observations.

type ObservationThreeHour

type ObservationThreeHour struct {
	ClothingLayers  *string    `json:"clothingLayers"`
	Date            *Timestamp `json:"dateTimeISO"`
	Humidity        *int       `json:"humidity,string"`
	Pressure        *string    `json:"pressure"`
	Rainfall        *float64   `json:"rainfall,string"`
	Temp            *int       `json:"temp,string"`
	WindChill       *int       `json:"windChill,string"`
	WindDirection   *string    `json:"windDirection"`
	WindProofLayers *int       `json:"windProofLayers,string"`
	WindSpeed       *int       `json:"windSpeed,string"`
}

ObservationThreeHour represents observation data updated every 3 hours.

type ObservationTwentyFourHour

type ObservationTwentyFourHour struct {
	DatePretty *string  `json:"dateTime"`
	Max        *int     `json:"maxTemp"`
	Min        *int     `json:"minTemp"`
	Rainfall   *float64 `json:"rainfall,string"`
}

ObservationTwentyFourHour represents observation data updated day.

type Pollen

type Pollen struct {
	Location   *string     `json:"location"`
	PollenDays []PollenDay `json:"pollen"`
	Enabled    *bool       `json:"pollenEnabled"`
}

Pollen represents the pollen/alergy data for the next few days.

type PollenDay

type PollenDay struct {
	DayDescriptor *string    `json:"dayDescriptor"`
	Level         *string    `json:"level"`
	Type          *string    `json:"type"`
	ValidFrom     *Timestamp `json:"validFromISO"`
	ValidTo       *Timestamp `json:"validToISO"`
}

PollenDay represents the pollen data for a single day.

type RiseSet

type RiseSet struct {
	Date       *Timestamp `json:"dayISO"`
	FirstLight *Timestamp `json:"firstLightISO"`
	ID         *string    `json:"id"`
	LastLight  *Timestamp `json:"lastLightISO"`
	Location   *string    `json:"location"`
	MoonRise   *Timestamp `json:"moonRiseISO"`
	MoonSet    *Timestamp `json:"moonSetISO"`
	SunRise    *Timestamp `json:"sunRiseISO"`
	SunSet     *Timestamp `json:"sunSetISO"`
}

RiseSet represents the sun/moon rise and set times for a day.

Example

client := NewClient()
ctx := context.Background()

riseSet, _, err := client.GetRiseSet(ctx, "Dunedin")
if err != nil {
	fmt.Println(err)
	return
}
fmt.Printf("sunrise at %v\n", *riseSet.SunRise)

type StatusError

type StatusError struct {
	Code int
}

StatusError is returned when a bad responce code is received from the API.

func (StatusError) Error

func (e StatusError) Error() string

type Timestamp

type Timestamp struct {
	time.Time
}

Timestamp represents a time that can be unmarshalled from a JSON string formatted as either an RFC3339 or Unix timestamp.

func (Timestamp) Equal

func (t Timestamp) Equal(u Timestamp) bool

Equal reports whether t and u are equal based on time.Equal

func (Timestamp) String

func (t Timestamp) String() string

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON implements the json.Unmarshaler interface. Time is expected in RFC3339 or Unix format.