diff options
Diffstat (limited to 'data/README')
| -rw-r--r-- | data/README | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/data/README b/data/README new file mode 100644 index 0000000..904fa8a --- /dev/null +++ b/data/README @@ -0,0 +1,95 @@ +The format of Locations.xml[.in] is something like this: + +<mateweather format="1.0"> + <region> + <_name>North America</_name> + <country> + <_name>United States</_name> + <iso-code>US</iso-code> + <state> + <_name>Alabama</_name> + <tz-hint>America/Chicago</tz-hint> + <location> + <!-- Translators: This is in Alabama in the United States. --> + <_name>Alabaster</_name> + <code>KEET</code> + <zone>ALZ019</zone> + <radar>bhm</radar> + <coordinates>33-10-42N 086-46-54W</coordinates> + </location> + <city> + <!-- Translators: This is in Alabama in the United States. --> + <_name>Mobile</_name> + <location> + <!-- Translators: This is in Mobile, Alabama in the United States. --> + <_name>Mobile Downtown Airport</_name> + <code>KBFM</code> + <zone>ALZ061</zone> + <radar>bix</radar> + <coordinates>30-36-50N 088-03-48W</coordinates> + </location> + </city> + ... + +Most of the data in the file appears inside <location> entries. +However, various larger geographic divisions exist to make things +easier for both users and maintainers. + +At the top level are <region>s. These mostly correspond to continents, +but not entirely. They are arbitrary, and could be changed in the +future if we wanted. + +Each <region> is divided into <country>s. Every internationally- +recognized country for which at least one <location> is defined should +have its own <country>. For the most part, "dependencies", +"territories", "protectorates" and the like are listed as <location>s +within their ruling country if they are in the same <region>, but +separately if they are in a different <region>. This is not followed +100% consistently. + +Every <country> must have an <iso-code> tag giving its ISO 3166-1 +alpha-2 code. Sub-country <location>s can also specify their own +<iso-code> if they have one. + +A <country> MAY specify a <tz-hint>, giving the default time zone name +for the country. Countries that only have one timezone (or where the +majority of the country is covered by a single timezone) should list +it at the <country> level. Countries with multiple timezones and no +obvious "default" should not list anything here. (See README.timezones +for more information about timezones in Locations.xml.) + +A <country> can contain <city>s and <location>s directly, or can be +split into <state>s which contain <city>s and <location>s. The name +"state" comes from the US states, but it can be used to represent any +sort of well-defined sub-country region that has a name which will be +familiar to local users. A <state> may specify a <tz-hint> which will +override the <country>'s <tz-hint> for <location>s within the state. + +<city> is an optional element used to group together multiple +<location>s within the same city. + +Finally, a <location> represents a location for which weather data can +be retrieved. Its fields are: + + <_name> - required, the name of the location + + <iso-code> - optional, the ISO 3166 code of the location, if not + the same as its parent <country> + + <tz-hint> - optional, the timezone of the location, if not the + same as its parent <state> or <country> + + <code> - required, the METAR code identifying this location + + <zone> - optional, secondary weather source information: + US: the NOAA IWIN zone + UK: the Met Office region name, prefixed with ":" + AU: the BOM forecast name, prefixed with "@" + + <radar> - optional, the Weather.com radar map name for the + location (North America only) + + <coordinates> - optional, the latitude and longitude of the + location, as "[-]ddd.dddddd [-]ddd.dddddd" + Positive values are North and East respectively, + negative values are South and West. |