Getting started with KML

Using a KML file, you can have as many markers on a map as you like, with as much detail in the info windows. With KML you can also change marker icons and add other nice features. You can generate your KML file from an application like Google Earth, or you can create it yourself (in a text editor or with your own programming). Learn more about KML.

Adding a KML map to a page requires the use of the src attribute. Add this shortcode to a page to see a map that is described in KML.

[flexiblemap src="http://webaware.com.au/maps/example-toronto.kml" width="100%"]

NB: the KML file needs to be visible to the Internet. This means you can’t just use a file on your local development server behind your firewall. If you don’t want to load it to a website, an easy way to publish it is to add it to a DropBox Public folder and get the “share” link to the file.

One thing to beware of is that Google Maps caches the KML file, so it often won’t pick up any changes you make straight away. To force a change, append a URL query parameter with a number (known as a cache buster) and increment the number each time you change the KML file. A nice simple and commonly used parameter name is v (for version), like this:

http://example.com/my-map.kml?v=2

If your map is auto-generated or changes frequently, add the kmlcache attribute to ask Google to fetch a new copy periodically. You can specify the interval in minutes (e.g. “90 minutes”), hours (e.g. “2 hours”), or days (e.g. “1 day”). The minimum interval is 5 minutes.

[flexiblemap src="http://webaware.com.au/maps/example-toronto.kml" kmlcache="8 hours"]

The Google Maps API supports many commonly used KML elements, but has some restrictions. Read about Google Maps support for KML in the developers’ guide, and also see the list of KML elements supported in Google Maps.

If you are building the KML yourself, either in an editor or with code, you should check it for errors. A good validator is the Feed Validator, which accepts and validates KML feeds as well as RSS and ATOM feeds.

See the attribute reference for the full set of available attributes.