ConkyForecast help (en)

From Conky PitStop

Jump to: navigation, search

Contents help

 Language   English   Français   

Author: Mark Buck (Kaivalagi)

NOTE: have removed developer support and as such most will have great difficulty using the service through the conkyForecast script in the future.

Please note however that there is an "alpha" version of the script called conkyForecastWU which is also included in the latest conkyWeather package and is detailed towards the end of this thread which works with wunderground...this is a good alternative but has not been documented for here as yet.

conkyForecast is probably the most popular of his scripts, fighting for first place with ConkyEmail.

Instructions en français: La météo avec conkyForecast

New Link for OpenSuse (coming soon)


It is expected that the user is already familiar with Conky.

Any conky specific help can be found by either visiting the conky website or alternatively various helpful posts are available on various Linux forums. Check out our Links page for some locations.

If you are not familiar with conky we have a Conky Setup Guide to get you started.

You need to install conkyForecast, pay particular attention to getting your City code. It will be a 4-letter-4number code that is NOT to be confused with your LOCALE (language), it is your DEFAULT_LOCATION!

OK, you have it, you've made the conky file, and template if you chose that route. Everything looks good but it doesn’t work! I’ve seen enough of this to ask: Did you copy /usr/share/conkyforecast/conkyForecast.config to ~/.conkyForecast.config and make the changes necessary?

Another note that is important: When using this script, call for the info with ${execpi}

There is a help file:

conkyForecast -help

... and It is obvious from the questions being repeatedly asked in the forums that people are NOT reading the help file so here it is with minor modifications by me to make it easier to identify the varuous uses of HT and LT for one:

Example Usage

In the /usr/share/conkyforecast/example folder you'll find 2 files, conkyrc and conkyForecast.template

Conky can be run using these example files as follows:

conky -c /usr/share/conkyforecast/example/conkyrc &

By running this you should see some output in a conky dialog, detailing all sorts of weather information. This is a test script for use with new releases.

Command Options

A break down of all the options available are below. The same details can be found by running conkyForecast --help

Usage: conkyForecast [options]

-h, --help            show this help message and exit

-C FILE, --config=FILE
[default: ~/.conkyForecast.config] The path to the
configuration file, allowing multiple config files to
be used.

  -l CODE, --location=CODE
location code for weather data [default set in
config]. Use the following url to determine your
location code by city name:

Change NORWICH for your city name!

-d DATATYPE, --datatype=DATATYPE
[default: HT] The data type options are:

Today: LT – Feels Like Temp – WITHOUT: “–startday=0″ [--datatype LT]
Today: HT – Current Temp – WITHOUT: “–startday=0″ [--datatype HT]

Today: LT – Forcasted Low Temp: – WITH: “–startday=0″ [-- startday=0 --datatype LT]
Today: HT – Forecasted High Temp: – WITH: “–startday=0″ [-- startday=0 --datatype HT]

Forecast: LT – Low Temp – use with –startday=1 to 4 [-- startday=1 --datatype LT]
Forecast: HT – High Temp – use with –startday=1 to 4 [-- startday=1 --datatype HT]

Font commands:

BF (Bearing Font)
BS (Bearing font with Speed)
MF (Moon Font)
WF (Weather Font output)

Images commands (conky v1.7.1 or greater)
- Usage:
BI (Bearing Icon Path)
- ${image [--datatype=BI] -p xx,xx -s yyxyy}
- ${image [--datatype=BI --startday=1] -p xx,xx -s yyxyy}
MI (Moon Icon Path)
- ${image [--datatype=MI] -p xx,xx -s yyxyy}
WI (Weather Icon Path) -
- ${image [--datatype=WI] -p xx,xx -s yyxyy}
- ${image [--datatype=WI --startday=1] -p xx,xx -s yyxyy}

BD (Barometer Description)
BR (Barometer Reading)
CC (Current Conditions)
CN (City Name)
CO (Country)
CT (Conditions Text)
DL (DayLight)
DP (Dew Point)
DW (Day of Week)
HM (Humidity)
LF (Last Fetch from Not applicable at command line when using templates.
LU (Last Update at
MP (Moon Phase)
OB (Observatory)
PC (Precipitation Chance)
SR (SunRise)
SS (SunSet)
UI (UV Index)
UT (UV Text)
VI (Visibility)
WA (Wind Angle - in degrees)
WD (Wind Direction)
WG (Wind Gusts)
WM (weather map fetch and image path returned)
WS (Wind Speed)

  -s NUMBER, --startday=NUMBER
define the starting day number, if omitted current
conditions are output. Not applicable at command line
when using templates.

  -e NUMBER, --endday=NUMBER
define the ending day number, if omitted only starting
day data is output. Not applicable at command line
when using templates.

  -S NUMBER, --spaces=NUMBER
[default: 1] Define the number of spaces between
ranged output. Not applicable at command line when
using templates.

  -t FILE, --template=FILE
define a template file to generate output in one call.
A displayable item in the file is in the form
[--datatype=HT --startday=1].

The following are possible options within each item:


Note that the short forms of the options are not
supported! If any of these options is set from the
commandline, it sets the default value of the
option for all template items.

  -L LOCALE, --locale=LOCALE
override the system locale for language output
(bg=bulgarian, cs=czech, de=german, es=spanish,
en=english, es=spanish, fj=fijian, fr=french,
it=italian, nl=dutch, pl=polish, ro=romanian,
sk=slovak, more to come)

  -i, --imperial        request imperial units, if omitted output is in

  -b, --beaufort        request beaufort scale for wind speeds, if omitted
output is either metric/imperial.

  -M, --metrespersecond
request metres per second for wind speeds, if omitted
output is either metric/imperial.

  -n, --night           switch output to night data, if omitted day output
will be output. ~/.conkyForecast.config now has: AUTO_NIGHT = True/False  Default: False

  -w, --shortweekday    Shorten the day of week data type to 3 characters.

  -u, --hideunits       Hide units such as mph or C, degree symbols (°) are
still shown.

  -x, --hidedegreesymbol
Hide the degree symbol used with temperature output,
this is only valid if used in conjunction with

  -m NUMBER, --minuteshide=NUMBER
Works only with LU and LF. If present, hides the date
part of the LU or LF timestamp if the day of the
timestamp is today. The time part is also hidden, if
the timestamp is older than minutes specified in this
argument. If set to 0, the time part is always shown.
If set to -1, the value EXPIRY_MINUTES from the config
file is used.

  -c WIDTH, --centeredwidth=WIDTH
If used the output will be centered in a string of the
set width, padded out with spaces, if the output width
is greater than the setting it will be truncated

  -r, --refetch         Fetch data regardless of data expiry.

  -v, --verbose         Request verbose output, not a good idea when running
through conky!

  -V, --version         Displays the version of the script.

  --errorlogfile=FILE   If a filepath is set, the script appends errors to the

  --infologfile=FILE    If a filepath is set, the script appends info to the

More useful information:


There are several fonts included in the release, these are installed to /usr/share/fonts/truetype/conkyforecast

They should be used as follows:

* ConkyWeather - should be used in conjunction with the WF (weather font) datatype
* Arrows - can used in conjunction with the BF (bearing font) datatype, to display a simeple wind direction arrow
* ConkyWind, ConkyWindN and ConkyWindNESW - should be used in conjunction with either the BF (bearing font) or BS (bearing font with speed) datatype
* Moon Phases - should be used in conjunction with the MF (moon font) datatype

~/.conkyForecast.config Settings

A template config file exists which holds all the settings used by the script, and most importantly, stores the partner id and registration code for the xoap service.

It can be found here "/usr/share/conkyforecast/conkyForecast.config"

For a working script you NEED to define, in the user specific config file, a partner id and registration code for the xoap service. For this purpose the config file should be copied to "~/.conkyForecast.config" and setup as required.

To copy and edit the config, using the command line , run the following two commands in a terminal:

cp /usr/share/conkyforecast/conkyForecast.config ~/.conkyForecast.config

and then edit it:

nano ~/.conkyForecast.config

nano can be replaced with any text editor, I use gedit.

More details on the xoap service registration, including how to register to obtain the required keys, is below in the XOAP_PARTNER_ID and XOAP_REGISTRATION_KEY config setting details. Treat your ID and KEY the same way you treat your email passwords!

Below is a breakdown of all the settings and their purpose.


This setting dictates where the "pickled" weather data is cached for further use by the script. There will be one pickled file per location with the name .conkyForecast-LOCATION.cache, with LOCATION replace with your used location codes.

Pickling the information retrieved means that it can be reused without needing a round trip to the XOAP service each time something is displayed through a script call.

The default folder used is /tmp which is fine in most cases. However it should be noted that the /tmp folder is emptied on reboot, so data will not be kept in this case and a will needs refetching from the web again.

In situations where reboots are common, you could change the path to your own home folder if desired, meaning that cached data will never be lost.

I use: ~/Conky/cache


This setting is just that, it defines the timeout period for the connection establishment. This setting probably will not need changing, however with poor connectivity a higher value may be required.


This setting defines how long the cached weather data remains valid for. When the script is called, if the datetime of the cached files is older than this setting in minutes, the script will refetch the weather data required, and refresh the cache.


DATE_FORMAT = %Y-%m-%d

These settings define the formatting of both date and datetime output. They follow standard strftime formatting conventions and are listed below.

| Value | Result                                                        |
|  %a   | Locale's abbreviated weekday name.                            |
|  %A   | Locale's full weekday name.                                   |
|  %b   | Locale's abbreviated month name.                              |
|  %B   | Locale's full month name.                                     |
|  %c   | Locale's appropriate date and time representation.            |
|  %d   | Day of the month as a decimal number [01,31].                 |
|  %H   | Hour (24-hour clock) as a decimal number [00,23].             |
|  %I   | Hour (12-hour clock) as a decimal number [01,12].             |
|  %j   | Day of the year as a decimal number [001,366].                |
|  %m   | Month as a decimal number [01,12].                            |
|  %M   | Minute as a decimal number [00,59].                           |
|  %p   | Locale's equivalent of either AM or PM.                       |
|  %S   | Second as a decimal number [00,61].                           |
|  %U   | Week number of the year (Sunday as the first day of the week) |
|       | as a decimal number [00,53]. All days in a new year preceding |
|       | the first Sunday are considered to be in week 0.              |
|  %w   | Weekday as a decimal number [0(Sunday),6].                    |
|  %W   | Week number of the year (Monday as the first day of the week) |
|       | as a decimal number [00,53]. All days in a new year preceding |
|       | the first Monday are considered to be in week 0.              |
|  %x   | Locale's appropriate date representation.                     |
|  %X   | Locale's appropriate time representation.                     |
|  %y   | Year without century as a decimal number [00,99].             |
|  %Y   | Year with century as a decimal number.                        |
|  %Z   | Time zone name (no characters if no time zone exists).        |
|  %%   | A literal "%" character.                                      |

For more details, see the section on strftime


NOTE: this is NOT for your city code you searched for. This concerns the "displayed language" conkyForecast will output to the screen.

This setting defines the locale to use. It is optional as the script will determine your systems locale it is not set. However if you tend to setup English as the default language in your OS but want all your weather output in another language you are best setting the locale here.

You also have the option to define locale via command line arguments, if these are set then this setting is ignored. This allows for output using a variety of languages in multiple script calls for example.

The locales currently supported are listed against the --locale option in the command options help below.



ID & KEY = THINK: PASSWORDS! Do not publish them on the forums.

These settings are required for a working script, they are used when fetching data from the XOAP service.

To register and obtain the necessary codes you need to visit the following url and fill out the form.

After successfully completing the form, you will then receive a couple of emails providing you with the necessary codes to update these settings with, along with the software development kit and terms and conditions. It may take up to 24 hiurs to get this email, do not panic

Template Files

A template file is included in the example files and there are also details on the template option in the command options listed above.

Note that you can combine standard font output with weather fonts in a single template by using the execp and execpi commands in conky. The example uses this so to see how this works take a look at the example.

A quick example of template file options and layout:

[--datatype=DW --startday=1 --shortweekday]
[--datatype=HT --startday=1 --hideunits]/[--datatype=LT --startday=1 --hideunits]

Anything inside the square brackets are options, anything outside standard text that will be output as conky would normally handle it.

The good thing about temoplates: one line in conky:

${execpi 1800 conkyForecast --location=ARBA0009 --template=~/path/to_your/weather.template}

weather.template can be called anything, ie: as long as you call it:

${execpi 1800 conkyForecast --location=ARBA0009 --template=~/path/to_your/}


Conky has a default limit of 128 bytes for any text output from a variable. If you are creating large templates with more characters than the default buffer size can handle, the output can get truncated.

If this happens you can override the default behaviour by setting as new buffer size before the TEXT section in your conkyrc file, as follows:

text_buffer_size 1024

Some weather templates typically use:

text_buffer_size 3048 # 256 is minimum

or more!

There is a limit to the maximum range for free forecasts, the startday and endday options cannot be set greater than 4. The following are the options to use to get the maximum forecast of high temps (including forecast data for today)

--datatype=HT --startday=0 --endday=4

For certain characters used in this script, such as degree symbols, it is required that the UTF8 character set is enabled in Conky. If UTF8 is not enabled you can end up seeing something like 66ðF rather than 66°F.

To enable UTF8 the following should be added before the TEXT section in your conkyrc file.

# Force UTF8? note that UTF8 support required XFT
override_utf8_locale yes

Further Help

If you have an issue and are not sure, try running the same command in the terminal window and add the option --verbose, you should then see lots of information about what the script is doing, any warnings or errors should also be displayed.

If after doing the above you are still stuck, further help can be found by visiting the Weather Forecast Python Script support thread.

Note that it is best to post --verbose output of your script call, as well as the conkyrc you are using. This way the issue can be understood quickly and easily.

  14:33 ~
         $ conkyForecast -d HT --verbose
    config: ~/.conkyForecast.config
    location: None
    datatype: HT
    start day: None
    end day: None
    spaces: 1
    template: None
    locale: None
    imperial: False
    beaufort: False
    metrespersecond: False
    night: False
    shortweekday: False
    hideunits: False
    hidedegreesymbol: False
    minuteshide: None
    centeredwidth: None
    refetch: False
    verbose: True
    errorlogfile: None
    infologfile: None
    CACHE_FOLDERPATH: /home/IBCold/Conky/cache/
    DATE_FORMAT: %Y-%m-%d
    LOCALE: en
INFO: Locale set to en
INFO: Looking for translation file for 'en' under /usr/share/conkyforecast/locale
INFO: Translation file found for 'en'
INFO: Translation installed for 'en'
INFO: Not using a proxy as none is defined
INFO: Loading cache file /home/IBCold/Conky/cache/.conkyForecast-CAXX0829.cache

  14:34 ~


Personal tools