Map annotations are specified in the RSS XML format. RSS is a widely supported format for syndication of news and weblogs, and is extendable to publish any sort of itemized data. Publishing geographic annotations in RSS has several advantages: there are a large number of tools available to write RSS, and other services, besides worldKit, can make use of the geographic metadata. Most important for the basics, RSS is a simple format and easy to edit by hand.

worldKit supports three flavors of RSS: RSS 2.0, Atom, and RSS 1.0. Geographic data is assigned to RSS <item>'s by additional tags in the georss namespace. Also, worldKit accepts geoannotations within certain standard RSS tags, for users of hosted services that prohibit adding new tags to RSS.

An example RSS 2.0 file is included with the worldKit package.

Within the <channel>, there are multiple <item>'s each specifying an annotation. The <title> and <description> are displayed in the annotation's textbox, and the <link> is loaded on mouse clicks. The point is plotted at the latitude/longitude specified by <georss:point>.

Important: The georss namespace must be specified in the root <rss> tag, so make sure to add the "xmlns:georss" attribute.

Both GeoRSS Simple and GeoRSS GML are supported. And though the georss namespace is recommended, worldKit is permissive and supports all known varieties: <geo:lat>, <geo:long> (W3C Geo), <icbm:lat>, <icbm:latitude>, <geourl:latitude>, <icbm:lon>, <icbm:longitude>, <geo:lon>, <geourl:longitude>. Also accepted is a <geo:Point> element, with <geo:lat> and <geo:long> child elements.

If there is no access to the structure of the RSS feed (for example, services like TypePad and Blogger), it is possible to geocode within existing RSS items. By default, this feature is not enabled; the configuration option <locfield> is described below.

To specify a location, simply type geo:lat= and geo:long=, followed by the value, within a tag. For example,

Tags supported are <description> in RSS 1.0 and 2.0, <summary> & <content> in Atom, <category> in RSS 2.0, and <dc:subject> in RSS 1.0 and Atom. worldKit expects to find the geotags in the field specified by the <locfield> config option. Its value is the name of the tag containing the annotations; or the value "any", which will have worldKit search through any of the four fields above.

Additional information on using this method in practice is in Typepad and Blogger.

There are some drawbacks to this method. This is not strictly "correct" usage of a namespace. The annotations show up as plain text (though this may be desired by some) or interfer with other functions (<category> sometimes has specific uses in weblog software). Still, on the whole, it is a useful compromise.

There are a few configuration options (in config.xml) associated with retrieving the RSS feed.

• <dataurl>: This url specifies the location of the RSS file containing annotations. It can point to a static file or dynamic CGI. It can be an absolute or relative path, but can not reside on different server from worldKit (due to the Flash Player security model). If set to NULL, then no RSS is requested. The default value is "rss.xml".
• <updateurl>: This url specifies the location of the RSS feed retrieved repeatedly after the first RSS feed in dataurl is retrieved. This is useful for transferring only new annotations on each update. By default, this value is the same as dataurl.
• <update>: The time, in seconds, between retrievals of the RSS feed. If set to 0, the RSS is retrieved only once. The default value is 60.
• <uniqueurls>: Set to "true" to insure that RSS requests are unique and avoid hitting any cache. The current timestamp will be appended to the url. The default value is "false".
• <showonlynew>: When set to "true", only annotations present in the last RSS update will be displayed. Default value is "false".
• <locfield>: Set value to the name of the RSS tag to look for annotations. Values accepted are "description", "summary", "category", "dc:subject", or "any" (all four fields will be examined). By default, this option is not set, and no tags are examined.
• <rssbbox>: Set to "true", the bounding box of the current view is appended to the RSS feed url. url&bbox=WEST,SOUTH,EAST,NORTH. This is useful for displaying only part of a large data set. Default value is "false".

Multiple feeds can be specified for dataurl and/or updateurl. Use a new element for each additional feed. This can be useful if your GeoRSS comes from multiple sources, or you wish to cut the size of your data into more "digestable" chunks.

These are a few suggestions for web sites to determine latitude and longitude for an annotation.

• worldKit Geocoder: Integrates several geocoders into one easy interface.
• Maporama: Search for nearly any address in the world. Lat/Long are listed at the bottom of the left column on the map page.
• Geonames

It's also possible to use worldKit for geocoding. See Annotation Input.

Images can also be displayed at an annotation, instead of text . Add a <media:content> to any <item>, with the "url" attribute set to the url of an image.

The annotation itself can be a small image, rather than a shape. This can be specified for an individual item with <media:thumbnail>.

You must specify the "media" namespace by addng xmlns:media="http://search.yahoo.com/mrss/" to the root rss node.

<photo:thumbnail> used to be the recommended format for sepcifying images. It's still supported, but the media namespace is recommended to be inline with current web practices. Make sure you have the most recent version of worldKit.

worldKit (and the Flash Player generally) can display any characters encoded in "UTF-8". This covers everything from Swedish to Chinese toCyrillic.

To display annotations in international characters sets, make sure that the RSS file is saved in the UTF-8 encoding. Many text editors support UTF-8: Notepad on Windows, BBEdit on Mac, vim on unix. Also most software development packages will have support for writing UTF-8 files.

There are also reports that the Flash XML parser may have bugs parsing UTF-8. Wrapping UTF-8 encoded strings in CDATA sections, and adding a space to the end of the character section may help.

For certain advanced features (like the Javascript API), it is useful to assign known identifiers to RSS items. You can assign a unique id to a RSS 1.0 item with <dc:identifier>, a RSS 2.0 item with <guid> and an Atom entry with <id>.

If you don't assign an item an id, worldKit generates an internal identifier. This is perfectly fine generally, so don't worry about id's unless you have to.

Here's an example of geocoding in RSS 1.0.

Here's an example of geocoding in Atom.

Here's an example of geocoding within <dc:subject> tags.