HW3 Flat File : Altplaces Documentation

Contents:

What are the Altplace Files?

When you attempt to obtain a forecast, you will often use either the place name or a zip code. Once you enter this information, HAMweather 3 must then look this information up in a database so that it can properly determine what weather data to retrieve, search and process for the location you selected. The Altplace database is the core central database used in HW3 for obtaining this information. This database contains information on the city name, the actual weather zone, ICAO station to use for current conditions, FIPS, latitude and longitude of location and much more. Also the exact usage of the data may very slightly between different countries.

Altplace File Location:

The altplace databases are used for both US and international locations.  The individual altplace files must be stored in the a directory called 'altplaces' with in the countries subdirectory in the hw3dbs directory. 

For example, the US altplace files are stored in the location:

hw3dbs/us/altplaces

and the Canadian altplace files are stored in the location:

hw3dbs/ca/altplaces

Altplace File Naming Convention:

The altplace databases for each country should be broken down into separate files based on the state/province, using the file name format:

xx-yy-altplaces.txt

where xx is the country two letter abbreviation in lowercase and yy is the state/province two letter abbreviation in lowercase.

An actual altplace file name for the US state of Virginia would look like:

us-va-altplaces.txt

And the altplace file name for Ontario, Canada would look like:

ca-on-altplaces.txt

Note: For countries that do not have states/provinces you can substitute the two letter country abbreviation in lowercase for the two letter state abrreviation. For example, for Italy you could use the file name:

it-it-altplaces.txt

 

Data in Altplace Files:

Each line in the altplace file is a separate entry which contains the data for a location. An example entry may look like (This is the entry for Blacksburg, VA  in the us-va-altplaces.txt altplace file):

Blacksburg|VAZ014:2|KBCB:2%KPSK:3|VAZ014|51121|RNK|24060|37.22944|-80.41417|2080|EST|-5|KFCX

The above lines gives the location name, weather forecast zone, ICAO to use for current conditions, county warning area, latitude/logitude, elevation and more.

You will notice that the actual data elements in the line are separated by a pipe ("|"). The data elements in each altplace entry are defined as follows:

RequestedPlace|ZoneEntry|CurrentConditionEntry|WxZone|FIPS|CWA|SingleZipcode|Latitude|Longitude|Elevation|TimeZoneName|TimeZoneHour|RadarICAO

Data Field Description
RequestedPlace The name of the location (city,place,county) that the current entry/line in the altplace file provides information for. 

NOTE: This is compared to what the actual user types in for the "place". Thus, if a user may type in a location name a couple different ways then you can duplicate the entry in the altplace file with only the RequestedPlace being changed to match the alternate spelling the user may us.
ZoneEntry Determines what data is used and how displayed for the zone forecast.

The ZoneEntry can be broken down further. It may look similar to:

ZoneItem:ZoneCode

Where ZoneItem is either a place name, weather zone or ICAO. The ZoneCode defines what the ZoneItem is for HW3 and how it should be used.

This code is used to determine how the ZoneEntry is applied.  It can be a number from 0 to 5.
Code Country
Usage		 Description
0 US/Canada ZoneItem is a place name, output the RequestedPlace name in output
1 US/Canada ZoneItem is a place name, output the ZoneItem name in output.
(Often used for a near by location)
2 US ZoneItem is a Weather zone number, output the RequestedPlace name in output
3 US ZoneItem is a Weather zone number, output the Weather Zone name in output
(Often used for a near by location)
4 International ZoneItem is an ICAO used for a TAF zone forecast, output the RequestedPlace name in output.
5 International ZoneItem is an ICAO used for a TAF zone forecast, output the ICAO Location name in output.
(Often used for a near by location)

How the ZoneItem:ZoneCode combinations are used by HW3:

ZoneCode = 0 or 1 (US and Canada Only)

When ZoneCode = 0 or 1 then this tells HW3 that the ZoneItem is a place name.  Note that this usage is only available for the US and Canada, and the ZoneItem (place name) is handled slightly different for both the US and Canada.

US Usage:

When this method is used for a location in the US, the ZoneItem should be the name of a county or city(using the exact spelling), that appears in the appropriate zone forecast header. An example header from a zone forecast in Virginia may look like:

 
VAZ007-009>019-NCZ001-002-018-050930-
ALLEGHANY VA-ALLEGHANY NC-ASHE NC-BLAND VA-CARROLL VA-CRAIG VA-
FLOYD VA-GILES VA-GRAYSON VA-MONTGOMERY VA-PULASKI VA-SMYTH VA-
TAZEWELL VA-WATAUGA NC-WYTHE VA-
INCLUDING THE CITIES OF...BLACKSBURG VA...BOONE NC...
CLIFTON FORGE VA...GALAX VA...PEARISBURG VA...RADFORD VA...
SPARTA NC...TAZEWELL VA...WYTHEVILLE VA
335 PM EST SUN NOV 4 2001

Notice how the header contains a list of the counties and cities that make of the zone forecasts coverage area.  With this in mind, we can see that for "Shawsville, VA" the name Shawsville is not listed, but since Shawsville, VA is with in Montgomery County, VA. We can associate Shawsville to Montgomery County using the following ZoneEntry:

montgomery:0

The actual entry in the Virginia altplace file, us-va-altplace.txt would look similar to:

shawsville|montgomery:0| ...

NOTE: Take notice that not all zone forecasts in the US include both included city & county listings. Some include county listings only while some do not include either. 

Canadian Usage:

When this method is used for a location in Canada, the ZoneItem portion must be broken down into four components:

36HourURL--36HourPlaceName:ExtendedURL--ExtendedPlaceName

  • 36HourURL  is the name of the text file on the Environmental Canada web site which contains the needed zone 36 hour forecast
  • 36HourPlaceName is the optional place name that appears in the header of the 36 hour zone forecast to use. If this is not provided then the actual RequestedPlace name is used.
  • Extended URL is the name of the text file on the Environmental Canada web site which contains the needed extended zone forecast
  • ExtendedPlaceName is the optional place name that appears in the header of the exteneded zone forecast to use. If this is not provided then the actual RequestedPlace name is used.

A example ZoneEntry for Linsday, Ontario would look like:

fpcn11.woz.htm--Peterborough:fpcn54.woz.htm--Haliburton:0

Where:

  • fpcn11.woz.htm is the name of the file that contains the needed 36 hour zone forecast.
  • Peterborough is the name to look for in the header of the 36 hour zone forecast needed.
  • fpcn54.woz.htm is the name of the file that contains the needed extended forecast.
  • Haliburton is the name to look for in the header of the extended zone forecast needed.

The actual entry in the Ontario, Canada altplace file, ca-on-altplaces.txt, would look similar to:

lindsay|fpcn11.woz.htm--Peterborough:fpcn54.woz.htm--Haliburton:0| ...

An example of a ZoneEntry for a Canadian location that does not have the optional 36HourPlaceName or the ExtendedPlace name, such as Kenora, Ontario:

fpcn14.wqt.htm--:fpcn54.wqt.htm--:0

Since the 36HourPlaceName and ExtendedPlaceName are not provided, the RequestedPlace, Kenora in this case, would be used as the place name to find in the header of the zone forecast to use.

Note: Even when you to do not provide the 36HourPlaceName or ExtendedPlaceName you should include the "--" separator.

The actual entry in the Ontario, Canada altplace file, ca-on-altplaces.txt, would look similar to:

kenora|fpcn14.wqt.htm--:fpcn54.wqt.htm--:0| ...

Note that technically the extended portion of the ZoneItem (the ":ExtendedURL--ExtendedPlaceName") is totally optional. If not provided then only the 36 hour forecast will be displayed.

ZoneCode = 2 or 3 (US Only)

When ZoneCode = 2 or 3 then this tells HW3 that the ZoneItem is a Weather zone code.  Note that this usage is only available for the US. This method is the most accurate method for finding zone forecasts for US locations, thus both the freeware and HWdb Update Service databases use this method.

US Usage:

When this method is used for a location in the US, the ZoneItem should be the weather zone code for the location the forecast is needed for. HW3 will look for the weather zone indicated in the header of the zone forecasts so it can find the exact one needed. An example header from a zone forecast in Virginia may look like:

 
VAZ007-009>019-NCZ001-002-018-050930-
ALLEGHANY VA-ALLEGHANY NC-ASHE NC-BLAND VA-CARROLL VA-CRAIG VA-
FLOYD VA-GILES VA-GRAYSON VA-MONTGOMERY VA-PULASKI VA-SMYTH VA-
TAZEWELL VA-WATAUGA NC-WYTHE VA-
INCLUDING THE CITIES OF...BLACKSBURG VA...BOONE NC...
CLIFTON FORGE VA...GALAX VA...PEARISBURG VA...RADFORD VA...
SPARTA NC...TAZEWELL VA...WYTHEVILLE VA
335 PM EST SUN NOV 4 2001

Take note of the header line:

VAZ007-009>019-NCZ001-002-018-050930-

This is the line which defined what weather/forecast zones the following forecast covers. In the case the line breaks down as follows:

  • VAZ : means that the following zone numbers are for weather/forecast zones in the state of Virginia.
  • 007- : the individual number, meaning the forecast covers weather zone 007 in VA.
  • 009>019- : defines the group of weather zones 009 through 019 in VA are covered by the following zone forecast.
  • NCZ : means that the following zone numbers are for weather/forecast zones in the state of North Carolina.
  • 002- : the individual number, meaning the forecast covers weather zone 002 in NC.
  • 018- : the individual number, meaning the forecast covers weather zone 018 in NC.

HW3 will take the ZoneItem you specify and see find the zone forecast that includes the zone number you specifi in the ZoneEntry.  The actual ZoneItem you set to the Zone number must follow the format:

XXZ###

Where:

  •  XX is the two letter state abbreviation
  • Z is just the letter Z meaning "Zone"
  • ### is the three digit weather zone number needed. Preceed with zeros "0" if the number is less than three digits. Thus weather zone 2 would be 002, weather zone 18 would be 018 and weather zone 103 would simply be 103.

As an example, Blacksburg, VA is location in Viriginia weather zone 14. Thus the ZoneEntry field would look like:

VAZ014:2

The actual entry in the Virginia altplace file, us-va-altplace.txt would look similar to:

blacksburg|VAZ014:2| ...

Note: You can find all the weather zones in the US, via the Weather/Forecast Zone shape file maintained by the National Weather Service at:

http://isl715.nws.noaa.gov/mapdata/newcat/wsom/c11-zone.htm 

ZoneCode = 4 or 5 (International)

When ZoneCode = 4 or 5 then this tells HW3 that the ZoneItem is an ICAO which should be used to find a TAF to decode into a TAF zone forecast.  Note that this usage is available for the International locations, including the US and Canada, that have a local TAF available.

A TAF, is a Terminal Aerodrome Forecast, which is a forecast for airports that are for a coverage time of up to 18 to 24 hours, length of time usually depends on the country creating the TAF.

As an example of using a TAF, for Roanoke, VA, the ZoneEntry would look like:

KROA:4

Where KROA is the ICAO which broadcasts a TAF for the Roanoke Airport.

The actual entry in the Virginia altplace file, us-va-altplace.txt would look similar to:

roanoke|KROA:4| ...

 

Multiple ZoneEntries:

Understandably there may be times with the normal zone information may not be available. In these circumstances HW3 can also use backup zone information. Basically in the ZoneEntry field you can combine multiple entries by separating them with a percent sign "%".  The combinations can use the same ZoneCode method or be different ZoneCode methods.

For example, Blacksburg, VA is located in VAZ014 but in case that is unavailable you could possibly use the backup forecast for VAZ015 (Note this is just an example). In this case the actual entry in the Virginia altplace file, us-va-altplace.txt would look similar to:

blacksburg|VAZ014:2%VAZ015:2| ...

In the above, if HW3 cannot fetch or find the forecast for VAZ014 it will then attempt to fetch/find the forecast for VA015. Thus you have two chances to find a valid forecast before failing with an error.

You could also use different ZoneCode methods as well. For example, for Blacksburg, VA we would want to display the forecast for VAZ014, if that was not available we could try searching for the zone forecast that included "montgomery" in the header since Blacksburg is in montgomery county.  Finally if that failed we could use the TAF forecast for Roanoke, VA since it is within 30 miles. (Note this is just an example.) In this case the actual entry in the Virginia altplace file, us-va-altplace.txt would look similar to:

blacskburg|VAZ015:2%montgomery:0%KROA:4| ...
CurrentConditionEntry Determines what data is used and how displayed for the current conditions.

The CurrentConditionEntrycan be broken down further. It may look similar to:

CurrentConditionItem:CurrentConditionCode

Where CurrentConditionItem is either a place name, weather zone or ICAO. The CurrentConditionCode defines what the CurrentConditionItem is for HW3 and how it should be used.

This code is used to determine how the CurrentConditionEntry is applied.  It can be a number from 0 to 5.
Code Country
Usage		 Description
0 US Only CurrentConditionItem is a place name in the hourly IWIN file, output the RequestedPlace name in output
1 US Only CurrentConditionItem is a place name in the hourly IWIN file, output the ZoneItem name in output.
(Often used for a near by location)
2 International CurrentConditionItem is an ICAO code for a METAR observation, output the RequestedPlace name in output
3 International CurrentConditionItem is  an ICAO code for a METAR observation, output the Weather Zone name in output
(Often used for a near by location)

How the CurrentConditionItem:CurrentConditionCode combinations are used by HW3:

CurrentConditionCode = 0 or 1: (US Only)

When CurrentConditionCode = 0 or 1 then this tells HW3 that the CurrentConditionItem is a place name that resides in the IWIN hourly file.  Note that this usage is only available for the US.

There are 50 IWIN hourly files, one for each state which includes an hourly round up of conditions for various locations across the state. You can see an example of the Virginia IWIN hourly file at:

http://iwin.nws.noaa.gov/iwin/va/hourly.html

Note: To see the hourly file for your state, simply change the "va" in the above URL to your states two letter abbreviation in lower case.

When you use this method, you have to take note of two things:

  1. The place name you set CurrentConditionItem too must be the exact spelling that is used in the hourly file for your state.
  2. Note that the IWIN hourly files are not always reliable, at times they can go a couple hours with out updating and/or a location that is normally updated may be missing in another hour. 

An example of what the CurrentConditionEntry may look like for Roanoke, VA may me similar to:

roanoke:0

The actual entry in the Virginia altplace file, us-va-altplace.txt would look similar to: (Note the RequestedPlace and CurrentConditionsEntry precede the CurrentConditionEntry)

roanoke|VAZ022:2|roanoke:0| ...

An example of what the CurrentConditionEntry for Charlottesville, VA may look like since it is spelled differently in the IWIN hourly file would be:

charlottesvill:0

The actual entry in the Virginia altplace file, us-va-altplace.txt would look similar to: (Note the RequestedPlace and CurrentConditionsEntry precede the CurrentConditionEntry)

charlottesville|VAZ037:2|charlottesvill:0| ..

CurrentConditionCode = 2 or 3: (International, including US)

When CurrentConditionCode = 2 or 3 then this tells HW3 that the CurrentConditionItem is an ICAO station ID for use to fetch the METAR observation.

METAR observations are normally produced by ICAO stations located at airports, military bases and various other locations.  The METAR observations are available for locations worldwide that have active ICAO stations and report their METAR observations to the world community.  Thus they allow HW3 to provide current information for major cities around the world as well as many locations with in the US.

An example of the CurrentConditionEntry for Blacksburg, VA using the KBCB ICAO station which is at the Virginia Tech Airport would look like:

KBCB:2

he actual entry in the Virginia altplace file, us-va-altplace.txt would look similar to: (Note the RequestedPlace and CurrentConditionsEntry precede the CurrentConditionEntry)

blacksburg|VA014:2|KBCB:2| ...

Multiple CurrentConditionEntries:

Understandably there may be times with the normal current condition information may not be available. In these circumstances HW3 can also use backup current conditioninformation. Basically in the CurrentConditionsEntry field you can combine multiple entries by separating them with a percent sign "%".  The combinations can use the same CurrentConditionCode method or be different CurrentConditionCode methods.

For example, Blacksburg, VA has the ICAO KBCB located with in its limits, but also has the Roanoke airport with in 30 miles which uses the ICAO KROA. In this case the actual entry in the Virginia altplace file, us-va-altplace.txt would look similar to: (Note the RequestedPlace and CurrentConditionsEntry precede the CurrentConditionEntry)

blacksburg|VAZ014:2|KBCB:2%KROA:3| ...

In the above, if HW3 cannot fetch or METAR observation for ICAO KBCB it will then attempt to fetch the observation for ICAO KROA. Thus you have two chances to find a valid forecast before failing with an error.

You could also use different CurrentConditionCode methods as well. For example, for Roanoke, VA we would want to display the current conditions for ICAO KROA.  If that was not available we could try searching for the current conditions from the IWIN hourly for the city of Roanoke. In this case the actual entry in the Virginia altplace file, us-va-altplace.txt would look similar to:(Note the RequestedPlace and CurrentConditionsEntry precede the CurrentConditionEntry)

roanoke|VAZ022:2|KROA:2%roanoke:0| ...
WxZone (US Only) The actual Weather zone the location is located in.
FIPS (US Only) The five digit State/County FIPS number the location is located in.
CWA (US Only) County Warning Area
SingleZipcode A Single zipcode that is located with in the Requested Place.

NOTE: Many locations have multiple zipcodes, this is simply of the many for a location. The Zipcode databases actually have all the zipcodes for a location.
Latitude The Latitude in decimal where the Requested place is located.
Longitude The Longitude in decimal where the Requested Place is located.
Elevation The Elevation in feet of the Requested Place.
TimeZoneName The Time Zone Name/Abbreviation for the location. (should be the non Daylight savings time name. Thus EST for the eastern part of US)
TimeZoneHour The time zone hour difference from GMT.
RadarICAO (US & Canada only) The ICAO station name to use for the closest Nexrad Radar.

Custom Altplace Files: (As of HW3 Beta 2)

Often you may want to add new locations that may be searched to your altplace files. But for many who subscribe to the HWdb Update Service you would rather not make updates to the HWdb databases only to have to redo your changes upon the next HWdb Update release of the database. To get around this, HW3 allows you to create custom altplace files for your moodifications that go into a subdirectory of the altplaces directory called "custom". These custom altplace files must follow the same naming conventions as normal altplace files. Also the data entries must be the same as well.

Thus if you wanted to add a custom entry for say "Cambria, VA" which is a name for an area with in Christiansburg, VA then  you would create a file named "us-va-altplaces.txt" and place it in the directory hw3dbs/us/altplaces/custom. Thus the complete file path would be:

hw3dbs/us/altplaces/custom/us-va-altplaces.txt

Again the data entries with in this custom db follow the same rules as the normal altplaces files. As in our example with Cambria Virginia, it was stated that Cambria is the name given to an area within Christiansburg, Va, thus we know its going to have the same forecast information as Christionasburg so we can simply copy the Christiansburg altplace entry:

Christiansburg|VAZ014:2|KBCB:3%KPSK:3|VAZ014|51121|RNK|24073|37.12972|-80.40917|2100|EST|-5|KFCX

and put this in our custom altplace file, but change the Christiansburg to Cambria, thus giving:

Cambria|VAZ014:2|KBCB:3%KPSK:3|VAZ014|51121|RNK|24073|37.12972|-80.40917|2100|EST|-5|KFCX

Now users can type in "Cambria, VA" and the appropriate forecast will display. And you are free to update your core Altplace files as needed with out bothering your custom databases.