tralfamadore.com
get unstuck, in time

18 August 2008

Howto: Developing with the Locatable redirect service

For the first release of Locatable I've stuck to a very basic HTTP (REST) API. The idea is that you have a page that can take latitude/longitude coordinates in its URL. This might be an existing page, or it might be an iPhone-specific entry page that sets up some other variables or session cookies or whatever you might want to do. Template URLs The basic URL to perform a redirect to your location-enabled page is as follows: http://lbs.tralfamadore.com/r?u={myURL} For this to work, {myURL} needs to be a full absolute URL (including http://) to your page. Locatable looks for some special sequences in the URL you provide. @lat@ will get replaced with the user's latitude, as a floating point number @long@ will get replaced with the user's longitude, as a floating point number If the user hasn't installed Locatable, they choose not to send their location to your site, or the mobile device can't read an accurate location, the template parameters will be replaced by the empty string (that is, they will be stripped out of the URL before the redirect occurs). You should code your page for this condition. (Note: I'm looking at adding a parameter so you can check whether the service is enabled to make it easier to detect when you'll have a valid location, but that's not there yet; see below for a way to set a default value.) To take an example, the Geocaching web site expects a URL that looks like this: http://www.geocaching.com/seek/nearest.aspx?origin_lat=39.549167&origin_long=-94.329722&dist=100 To make this into a template URL for Locatable, we simply replace the numbers with the macros described above: http://www.geocaching.com/seek/nearest.aspx?origin_lat=@lat@&origin_long=@long@&dist=100 Encoding the URL Because we're going to use it as a querystring parameter to the redirector, make sure to properly encode your templated URL. Here's how to do it in various languages:
  • PHP: urlencode($myURL)
  • Java: java.net.URLEncoder.encode(myURL, "UTF-8")
  • Javascript: encodeURIComponent(myURL)
You get the basic idea. There's also a little encoder you can cut and paste from on this page. After doing that step on our example URL, it looks like this: http%3A%2F%2Fwww.geocaching.com%2Fseek%2Fnearest.aspx%3Forigin_lat%3D%40lat%40%26origin_long%3D%40long%40%26dist%3D100 Then we just need to add this to the redirector URL, and we're off and running: http://lbs.tralfamadore.com/r?u=http%3A%2F%2Fwww.geocaching.com%2Fseek%2Fnearest.aspx%3Forigin_lat%3D%40lat%40%26origin_long%3D%40long%40%26dist%3D100 Take that URL, put it in a HTML href, and you're ready to go! Defaulting the Location If you'd rather have some value for latitude and longitude rather than none, you can use the following syntax: @lat:defaultValue@ gets replaced by the latitude, or defaultValue if none is available @long:defaultValue@ gets replaced by the longitude, or defaultValue if none is available For example, if we were to start with the same Geocaching URL, but want to default to Charing Cross in London (latitude 51.509, longitude -0.125), we'd use the following template URL: http://www.geocaching.com/seek/nearest.aspx?origin_lat=@lat:51.509@&origin_long=@long:-0.125@&dist=100 Happy (geo)hacking!

Labels: , , , ,

Copyright (C) 2001-2008 Tralfamadore.com