Atompub and KML Demo

Update (2009-05-20): Hammock has been retired, replaced since December 2007 by Knowhere.

I have repurposed my Hammock application into a demonstration of the Atompub, KML, and Google Earth integration. Now, from an Atom perspective there is a service document and one collection at:

http://sgillies.net/hammock/index.atom

http://sgillies.net/hammock/places/

Subscribe to that second URL, it's an Atom feed. Any newsreader should be able to use it to monitor changes to the collection. Next, start Google Earth and in your temporary places container create a new network link to this URL:

http://sgillies.net/hammock/places.kml

The same (very simplistic) data model supports both the Atom feed and the KML document.

Ready to publish data to the Web, Atompub-style? All you need is a terminal, curl or another moderately sophisticated HTTP client, and a little make-believe. Imagine that Google Earth or another future geo-browser is doing all the POST and PUT dirty work for you.

In the temporary places container, create a new point placemark anywhere. Give it a name and a plain text description. Save it to your filesystem as hammock.kml. To create a new, publicly-shared place within the collection based on your new placemark you send the contents of that file in the body of a request to the collection URI. I showed that URI above, but the sure place to find it is in the atom:link element of the KML file. View the source on that file and verify that there's a link to http://sgillies.net/hammock/places/. Now send a request like:

POST /hammock/places/ HTTP/1.1
Host: sgillies.net
Content-type: application/vnd.google-earth.kml+xml

<kml>
...
</kml>

You can use curl to do it like this:

$ cat hammock.kml | curl -d @- --header
Content-type:application/vnd.google-earth.kml+xml
http://sgillies.net/hammock/places/

It's very important to specify the proper content type. If you've typed carefully, you will get response with a Location header containing the URL of the newly created resource. If you refresh the Atom feed and network link, you'll see the new resource reflected in each. You've seen this before in other apps like FeatureServer. What's new is that the KML document itself carries a link to the collection URI, the factory for new placemark resources. That's Atompub in action.

Furthermore, any placemark resource represented in http://sgillies.net/hammock/places.kml can be edited via its "edit" or "edit-media" (they are equivalent in this demo) atom:links using the HTTP PUT method. View the source to find the edit link for your newly created resource, and copy it (remember, one day Google Earth should do all this for you). Now, move the placemark in Google Earth or create a new one, and save it to the filesystem. Finally, PUT the saved placemark to the edit URI you copied using curl like:

$ cat edit.kml | curl -X PUT -d @- --header
Content-type:application/vnd.google-earth.kml+xml
http://sgillies.net/hammock/places/3

In this case, I've edited the third place. Note the use of the PUT method. If you typed carefully, the changes you made will be reflected in your newsreader and in the Google Earth network link.

It almost seems too simple to work: serve KML to users that provides the very links by which users can add to, or modify, the web resources represented in the document. I'd be surprised if there is a tidier solution. I hope this simple demo can convince a few people to take a closer look at using Atompub for geospatial services.