search

willasm / obsidian-open-weather

Obsidian plugin for OpenWeather API
MIT License
47 stars 3 forks source link

readme

OpenWeather Plugin for Obsidian

IMPORTANT NOTICE - THIS PLUGIN IS NOW DISCONTINUED!

(Continue reading though - I have good news to announce as well)

Open Weather has discontinued API 2.5 on which this plugin is based. They do offer API 3.0 which is free, but it requires a credit card to subscribe to the API. I'm not interested in giving some company a way to automatically charge me for something in the future when/if they decide to. I'm pretty sure that would never actually happen, but I can say that I am positively sure it can not happen if they do not have my credit card info. Also if they did start charging the users of this plugin (around 10,000 users) for some unforseen reason, that would have a lot of people very unhappy with me and that would be unpleasant to say the least...

One other point is that there are enough differences between the two API's that it would basically require a complete re-write of the plugin which leads into my good news... I have very nearly completed a new weather plugin based on the Visual Crossing Weather API. It is free to subscribe to and does not require anything other than your email address. You can sign up here. It offers many great features that were not included with Open Weather. For example, 15 complete forecast days while Open Weather only had 5 and for 21 hours out of every 24, day 1 and 5 did not return the full data for those days. VCW API also returns hourly data for every one of those 15 days while OW only returns the data in 3 hour blocks. Other nice features that VCW API offers and OW API is missing is weather alerts, data is returned in local time rather than GMT (No conversions needed). The API documentation is also much better and it has an active support forum. Overall it is just a nicer API to work with.

If you want to try the new plugin now you can find the Visual Crossing Weather plugin here. It has some big improvements over the old plugin. It now has 5 locations you can get the weather data for as opposed to just one. I have doubled the number of weather templates from 4 to 8. There are now 2 statusbar strings which can be cycled every 30 seconds. The defaults are the first one has info on todays weather, the second displays info for tommorows weather. Note while this is still a work in progress it has almost every feature working now (Two feature that I still want to add are not yet completed). The documentation is also basically non-existent at the moment although I do have the complete list of current macros created (nearly 4000 already) and it is displayed in an easy to read table format. I have uploaded the main.js file as well if you would like to do a manual install or you could use the BRAT plugin to do the work for you. Anyone willing to Beta test it would be a huge help if they could provide any feedback.

Please note that the API was supposed to be discontinued 3 weeks ago, but as right now it is still returnig data. This could stop at any time!!! It is fortunate that it has continued this long as it has given me the time to write the new plugin. I will request the removal of this plugin from community plugins list when the API stops working or I have added the new plugin to community plugins list.

Thank you to all the plugins users since its creation, William McKeever

Features

Default Weather Strings with Example Screenshots

Statusbar String

' | %desc% | Current Temp: %temp%°C | Feels Like: %feels%°C | '

Statusbar

Weather String One

'%desc% • Current Temp: %temp%°C • Feels Like: %feels%°C\n'

Format One

Weather String Two

'%name%: %dateMonth4% %dateDay2% - %timeH2%:%timeM% %ampm1%\nCurrent Temp: %temp%°C • Feels Like: %feels%°C\nWind: %wind-speed% km/h from the %wind-dir%^ with gusts up to %wind-gust% km/h^\nSunrise: %sunrise% • Sunset: %sunset%\n'

Format Two

Weather String Three

'%icon%&nbsp;%dateMonth4% %dateDay2% %dateYear1% • %timeH2%:%timeM% %ampm1% • %desc%<br>&nbsp;Recorded Temp: %temp% • Felt like: %feels%<br>&nbsp;Wind: %wind-speed% km/h from the %wind-dir%^ with gusts up to %wind-gust% km/h^<br>&nbsp;Sunrise: %sunrise% • Sunset: %sunset%'

Format Three

Weather String Four

'%icon%&nbsp;%dateMonth4% %dateDay2% %dateYear1% • %timeH2%:%timeM% %ampm1% • %desc%<br>&nbsp;Current Temp: %temp% • Feels like: %feels%<br>&nbsp;Wind: %wind-speed% km/h from the %wind-dir%^ with gusts up to %wind-gust% km/h^<br>&nbsp;Sunrise: %sunrise% • Sunset: %sunset%'

Format Four

Format Strings Three & Four within DIV's and styled wih CSS

Format String Three...

Format Three

Format String Four...

Format Four

Note: The \n's are not required when editing these in the settings. Simply enter a return to add a new line and the \n will be added to the saved settings file. The <br>'s in string formats 3 & 4 are required for use in HTML.

See EXAMPLE.md for a demonstration of how I use this in my Daily Template.

Settings

OpenWeather API Key

Enter your OpenWeather API Key here (Required)

A free OpenWeather API key is required for the plugin to work. Go to https://openweathermap.org to register and get a key. Direct link to signup page https://home.openweathermap.org/users/sign_up.

Note: You will need to verify your email address, then your API key will be emailed to you. The key itself may take a couple of hours before it is activated. All this information will be included in the email they send to you.

Use Geocoding API to get location (recommended)

This Geocoding API returns the requested locations name, state, country, latitude and longitude allowing you to choose the correct location. This is beneficial in cases where your city has a common name shared by other cities. To use this, enter your cities name in the text field and press the Get location button. You will be prompted with a list of up to 5 locations to choose from.

Enter Location

Note: It is recommended to use the new Use Geocoding API to get location (recommended) command to fill this in for you.

Enter your city's name (This setting is required unless latitude and longitude are defined) Note: If you are getting the wrong data try including your state and country codes. They can be entered as {city name},{state code},{country code}. Eg. South Bend, WA, US (The commas are required). If you are still having issues getting the correct data, then use the Latitude and Longitude settings instead.

Enter Latitude

Note: It is recommended to use the new Use Geocoding API to get location (recommended) command to fill this in for you.

Enter your city's latitude (Setting Latitude and Longitude will override the Location setting)

Please note that API requests by city name have been deprecated although they are still available for use. The preferred method is to use latitude and longitude.

Enter Longitude

Note: It is recommended to use the new Use Geocoding API to get location (recommended) command to fill this in for you.

Enter your city's longitude (Setting Latitude and Longitude will override the Location setting)

Please note that API requests by city name have been deprecated although they are still available for use. The preferred method is to use latitude and longitude.

Units of Measurement

Metric, Imperial and Standard units can be selected here. (Note: Standard is in Kelvin, not really useful in most cases)

Language

Supported languages available (46 languages total) Note: This only applies to text that is returned by the Open Weather API. This does not change the text in the defined weather strings. If you want the text in the default weather strings in another language you will need to edit them directly in the settings.

Exclude Folder

Folder to exclude from automatic Template strings replacement. This should be set to your vaults template folder. The exclusion includes any subfolders within the selected folder.

Weather Strings

Define your weather strings here (4 strings are available + 1 for the statusbar)

Tip: These strings can contain anything you want, not just weather information.

Show Weather in Statusbar Note: This will not be displayed on mobile app

Toggle display of the current weather in the statusbar on or off

Weather String Format Statusbar Note: This will not be displayed on mobile app

Define your statusbar weather string here

Update Frequency

Time interval to update the weather displayed in the statusbar and DIV's (1, 5, 10, 15, 20, 30 or 60 minutes)

Weather String Placeholders

These macros contained within the weather string will be replaced with the appropiate data.

Current Weather Placeholders

Forecast Weather Placeholders

Note: The 5 day forecast is returned in 3 hour increments (total of 40 data objects). This means that the data returned by the API does not start at 12:00 am tommorow, but for the next 3 hour slice of available data. This means that only once a day can you get the full forecast for 5 days (just before midnight). At all other times you will recieve partial data for today and partial data for the last day. You will need to account for this when defining your weather strings. To make it easier for you I have included the placeholders %next12%, %next24%, and %next48% (see placeholder example) and will add more in the future.

Note: The placeholders represent the 3 hour forecast objects and are numbered 00, 01, 02, ... 39 in the placeholders.

OpenWeather Plugin Commands

All these commands are available from the command palette and the ribbon icon

Template support

You can place the following strings in your templates and when creating a new document using the template, they will automatically be replaced with the corresponding weather strings.

DIV support

You can insert the following DIV inside your documents to provide dynamic weather which is updated at the frequency set in the settings Update Frequency setting. The weather_historical_3 is the static temperature at the time the document is created and the weather_current_1 is dynamic. See EXAMPLE.md for a demonstration of how I use these in my Daily Template.

<div class="weather_historical_3">%weather3%</div>
<div class="weather_current_1"></div>

You can use the following class's to insert the corresponding weather strings

and...