Weather

The weather API allows you to display weather information in your widget.

Getting Weather Data

Weather data is retrieved using Hologram's get method:

Hologram.get(this, 'weather', (weather) => {
    this.weather = weather
    console.log(weather)
})

The callback returns an object with weather information, described in detail below.


Weather Object Overview

The weather object returned by the weather callback contains three child objects:

current:

Contains the current weather information. Since Hologram throttles all weather API requests to a max of one request per hour, the current object will always be accurate to one hour or less.

weather.current.key
// For example, to show the temperature you use
// weather.current.temperature

daily:

Contains 8 child objects, representing the weather forecast for the next 7 days. The zero index represents today. The 1 index represents tomorrow, and so forth.

weather.daily.[n].key
// For example, to show the projected wind speed for tomorrow you use
// weather.daily[1].windSpeed

An example of the weather object is found below.


Weather Placeholder

Because weather data is fetched asynchronously, we recommend you use the weather placeholder object within your widget. That way, if the widget loads before the weather is available it will show valid data types and not null.

Hologram.weather.placeholder

See usage example below.


Remove Listener

All data getting methods are automatically removed when a widget is destroyed. However, there are cases where you might want to stop receiving data. For example, if your widget lets users show/hide information, it's a good practice to remove the listener when that particular data isn't being shown.

let id = Hologram.get(this, 'weather', (weather) => {
    console.log('get weather', weather)
})

// Stop getting the weather
Hologram.removeListener(this, id)

Simple Weather Widget Example

Here's a simple widget that displays the weather.

{
    extends: HologramWidget,
    data() {
        return {
            // When defining the initial value for weather,
            // use the weather placeholder. This will return
            // "zero" data so the weather widget won't be blank
            weather: Hologram.weather.placeholder
        }
    },
    mounted() {
        // Load the weather when the widget is created and
        // assign it to a class variable
        Hologram.get(this, 'weather', (weather) => {
            this.weather = weather
        })
    },
    methods: {
        // This function formats temperature according to
        // the user's celcius/fahrenheit system setting.
        // Check the Hologram Utility class page for more info
        formatTemp(temp) {
            return Hologram.util.formatTemp(temp)
        }
    },
    template: `
        <div>
            The weather is {{ weather.current.description }}<br>
            The temperature is {{ formatTemp(weather.current.temperature) }}
        </div>
    `
}

Weather Object Prototype

This is an example of the weather object returned by Hologram:


 {
    "status": 1, // 0: Weather data not available. 1: Weather data available

    "current": {
        "isNight": true,
        "sunrise": 1602940608, // Unix timestamp
        "temperature": 48
        "temperatureMax": 55, // Max daily temperature
        "temperatureMin": 44, // Min daily temperature
        "date": 1602984072,
        "dewPoint": 19.24,
        "uvi": 3.68,
        "sunset": 1602980282,
        "pressure": 1015, // Atmospheric pressure in hPa
        "rain": 0, // Rain volume in the last hour in mm
        "visibility": 10000, // In meters
        "clouds": 20, // Percentage of cloudiness
        "feelsLike": 34,
        "windDeg": 280, // Wind direction in degrees
        "windDir": "W", // Wind compass direction
        "windGust": 0,
        "windSpeed": 16.11,
        "humidity": 29, // Humidity percentage
        "icon": "clouds-few",
        "description": "Few Clouds",
    },

    "daily": [{
        "isNight": false,
        "date": 1602957600,
        "sunrise": 1602940608,
        "sunset": 1602980282,
        "windSpeed": 30.53,
        "windDeg": 268,
        "windDir": "SW",
        "rain": 0, // Rain volume in the last hour in mm
        "clouds": 74, // Percentage of cloudiness
        "humidity": 38,
        "pressure": 1009,
        "dewPoint": 25,
        "temperatureDay": 55,
        "temperatureNight": 46,
        "temperatureMin": 44,
        "temperatureMax": 55,
        "feelsLikeDay": 34,
        "feelsLikeNight": 36,
        "feelsLikeMorn": 32,
        "feelsLikeEve": 30,
        "uvi": 3.68,
        "icon": "clouds-broken",
        "description": "Broken Clouds"
    }, {
        "isNight": false,
        "date": 1603044000,
        "sunrise": 1603027076,
        "sunset": 1603066591,
        "feelsLikeEve": 37,
        "feelsLikeMorn": 31,
        "feelsLikeDay": 30,
        "feelsLikeNight": 34
        "dewPoint": 27,
        "windSpeed": 23.67,
        "rain": 0, // Rain volume in the last hour in mm
        "pressure": 1016,
        "windDeg": 256,
        "windDir": "SW",
        "clouds": 100,  // Percentage of cloudiness
        "uvi": 3.74,
        "temperatureDay": 47,
        "temperatureNight": 45,
        "temperatureMin": 35,
        "temperatureMax": 50,
        "humidity": 51,
        "icon": "clouds-overcast",
        "description": "Overcast Clouds",
    },
    {
     // Etc.
    }]
}

Weather Icon Codes

The weather object always returns a weather icon name corresponding to the weather condition. Below is a list of all possible icon names in the event you wish to create your own icon set. The list below contains only the day states. The weather object returns "isNight", which allows for a night state icon if you are so inclined.

not-available // Icon code returned when weather status = 0

clear-sky
clouds-few // 10-25% sky covered
clouds-scattered // 25-50% sky covered
clouds-broken // 50-85% sky covered
clouds-overcast // 85-100% sky covered

// The weather object does not currently return wind icon states
// but for future use we've reserved the following wind states:
wind-clear
wind-few
wind-scattered
wind-broken
wind-overcast

rain-drizzle
rain-light
rain-moderate
rain-heavy

rain-freezing
sleet

thunderstorms
thundershowers

snow-light
snow-moderate
snow-heavy

dust
haze
mist
fog
smoke
volcano
tornado
squall
hurricane
tropical-storm

// The weather object does not return these icon names, but
// we include them since they can be useful.
sunrise
sunset
hot
cold