MythWeather Grabber Script Format
MythWeather grabber scripts are small executable perl, python, or binary applications which query online sources of weather and return it in a format parseable by MythWeather. This page documents the current format required of the grabber scripts to function.
MythWeather has six different types of pages. Grabbers are categorized into these types by the data they specify as capable of providing. Grabbers can seamlessly provide data for multiple pages by making sure to meet all the requirements for each.
Three Day Forecast
- date-0 through date-2
- icon-0 through icon-2
- low-0 through low-2
- high-0 through high-2
Six Day Forecast
- date-0 through date-5
- icon-0 through icon-5
- high-0 through high-5
- low-0 through low-5
A static map is an image, which is downloaded to a local file by the grabber. The map is a string like /dir1/dir2/filename-600x800. This represents a local file /dir1/dir2/filename with an image sized 600x800. The '-600x800' suffix is not mandatory, if missing the image will be expanded to fill the window.
An animation is typically downloaded as a single file. The grabber splits it into separate files which are stored locally. These files are represented by a single animation string like /dir1/dir2/filename-%1-6-800x600.
The %1 part is replaced with a unique number for each file. So with animation like above there will be files like filename-0, filename-1 etc.
The '6' digit is the number of files. For this example, there will be 6 files named filename-0..filename-5
The last part is the image size (width x height).
Bottom line: an animation like filename-%1-4-800x600 represents an animation with four frames named filename-0..filename-3 sized 800x600.
Severe Weather Alerts
18 Hour Forecast
- time-0 through time-5
- 18icon-0 through 18icon-5
- temp-0 through temp-5
- pop-0 through pop-5
The below commands are ordered by sequence of being called by MythWeather.
The Version Command (-v)
This command is called when MythWeather enters the Screen Setup page. It is used to populate a list of available grabbers, for which the user can subsequently create screens. The command returns a comma separated list of the script name, script version, author, and author's email, and output must end with a newline character. If the script version changes from that stored in the database, MythWeather will repopulate the field list and timeouts as detailed below.
#./bbccurrentxml.pl -v BBC-Current-XML,0.2,Stuart Morgan,firstname.lastname@example.org
The Field List Command (-t)
MythWeather will next pull a supported field list for all new or updated grabbers. This list is used to determine which screen types the grabber can pull information for. When called, the command must return all supported data fields, one per line.
#./bbccurrentxml.pl -t cclocation station_id copyright observation_time weather temp relative_humidity wind_dir pressure visibility weather_icon appt wind_spdgst
The Timeout Command (-T)
MythWeather will next pull a supported field list for all new or updated grabbers. The command returns a comma separated list of information lifetime (minutes), and web response timeout(seconds). These specify how long MythWeather will cache the received data, and how long it will wait before erroring.
#./bbccurrentxml.pl -T 7200,30
The Location Search Command (-l <location>)
After information about the grabber is populated by the previous three commands, users will search for locations for a screen, and MythWeather will pass those searches on to one or more grabbers using the '-l' argument. The responses are an identifying string ("id") to be used with the data string, and a description, separated by a double colon, one per line.
#./bbccurrentxml.pl -l Cincinnati 407::Cincinnati, Ohio 3231::Cincinnati/Northern Kentucky International, Kentucky
The id is limited by the weathersourcesettings:sourceid field length, currently 64 characters.
The Data Command (-u <unit system> -d <folder> <location string>)
After a screen with location has been set up, MythWeather will poll the grabber for data. MythWeather will provide the unit system the information should be returned in, and a directory path will full read/write access, which can be used by the script for cache or temporary data. The location string provided by the '-l' command will be the last argument in the call. The unit system will be one of 'SI' or 'ENG'. Only the information should be changed; no units should be provided. The temp directory can be used or ignored, as needed by the script. Data is returned, one value per line, separated from the identifying string by a double colon.
#./bbccurentxml.pl -u ENG 407 appt::NA copyright::From bbc.co.uk station_id::407 cclocation::Cincinnati, United States of America observation_time::Thursday at 13:00 EST weather::Grey cloud weather_icon::cloudy.png temp::43 wind_dir::E wind_spdgst::9 (NA) relative_humidity::65 pressure::30.5321117 visibility::10-20
If necessary, some fields are allowed to span multiple lines. The same data type must be prepended at the beginning of each new line.
#./nws-alert.pl -u ENG 21015 alerts::SHORT TERM FORECAST alerts::NATIONAL WEATHER SERVICE WILMINGTON OH alerts::117 PM EDT SUN MAR 28 2010 alerts::INZ066-073>075-080-KYZ089>096-OHZ070>072-077-078-281902- alerts::BOONE-BUTLER-CAMPBELL-CARROLL-CLERMONT-CLINTON-DEARBORN-FRANKLIN IN- alerts::GALLATIN-GRANT-HAMILTON-KENTON-OHIO-OWEN-PENDLETON-RIPLEY- alerts::SWITZERLAND-WARREN- alerts::117 PM EDT SUN MAR 28 2010 alerts::.NOW... alerts::SCATTERED LIGHT SHOWERS WILL CONTINUE TO MOVE TO THE NORTHEAST AND alerts::ACROSS THE LISTENING AREA THROUGH 3 PM. RAINFALL AMOUNTS WILL BE UP alerts::ONE TENTH OF AN INCH. swlocation::Boone,KY updatetime::Last Updated on Mar 28, 01:27 PM EDT copyright::NOAA,National Weather Service
|cclocation||Descriptive name of location||Data Type|
|wind_spdgst||Wing speed (gust)||float|
|wind_dir||Wind direction||Cardinal, a string like "NNW" or "S"|
|visibility||Integer/Range e. g. "10", "1" or "1-4"|
|appt||Apparent temperature, heat index and windchill combo||Temperature|
|temp||Current Temperature||Integer Degrees|
|weather||Weather conditions, free text||String|
|weather_icon||Weather image to show||filename, as used in the file weather_types.|
|observation_time||Time of last data update||String|
|copyright||Copyright information needed for ToS compliance||String|
|3dlocation||Location of forecast||String|
|6dlocation||Location of forecast||String|
|date-<n>||Week day number||Integer, Sunday=0 .. Friday=6|
|icon-<n>||Weather image to show for date-<n>||filename, as used in the file weather_types.|
|low-<n>||Low temperature forecast for date-<n>||degrees|
|high-<n>||High temperature forecast for date-<n>||degrees|
|updatetime||Time of last data update||String|
|time-<n>||Current hour of forecast||String|
|18icon-<n>||Weather image to show for time-<n>||filename|
|temp-<n>||Temperature forecast for time-<n>||Integer|
|pop-<n>||Precipitation likelihood for time-<n>||float (percent)|
|swlocation||Descriptive name of location, for weather alerts||String|
|alerts||Weather alert, can span multiple lines||String|
|animatedimage||Animated Map Location||See MythWeather Grabber Script Format#Animated Map|
|map||Static Map Location||See MythWeather Grabber Script Format#Static Map|