8 25 2005-02-18T09:12:11-05:00 $Date$ NormanWalsh 2005Norman Walsh Keeping track of your location with SOAP RPC. My second interface to Where In The World is a set of methods that you can invoke using SOAP RPC. I'm not sure I really understand all the jargon yet, but I think the salient bits are: The target SOAP node That's “http://norman.walsh.name/2005/02/witw/soap” for the “where is someone” services and “http://norman.walsh.name/2005/02/witw/ami/soap” for the “where I am” services that require authentication. (In fact, the latter node will perform all of the services.) The namespace of the services That's “http://norman.walsh.name/witw”. I'd have made that a dated URI, but I'm using Perl’s SOAP::Lite module to do the implementation and there was some weirdness in the way that the namespace name was mapped to the Perl module name. I decided to just punt. The names of the methods They are “user”, “is”, “nearby”, “atlatlong”, and “atlandmark”, described below. As you may have noticed, I've decomposed things a little bit differently. I did that to make some of the return types more manageable.

The user method returns information about a userid: user xs:string userid UnknownUser It returns the userid, the name of the user, a hash (in the mbox_sha1sum-style of FOAF) of the user's email address, and the uri associated with the user. If the specified userid is unknown, the service faults.

The is method returns information about the location of the specified userid. is xs:string userid UnknownUser UnknownLocation It returns the userid, the date when the location was specified, the latitude and the longitude specified by the user. It faults if the userid is unknown or if the user has not specified a location.

The nearby method returns information about landmarks that are close to the location of the specified userid. nearby xs:string userid xs:string units "mi" xs:decimal distance 50.0 UnknownUser UnknownLocation InvalidUnits InvalidDistance The units and distance parameters are optional. If specified, units must be one of “mi”, “km”, “m”, or “ft”. The default distance is 50 miles (about 80km). It returns zero or more sequences of landmarks: the name of the landmark, its latitude, longitude, any URI associated with the landmark, and its distance from the user. It faults if the userid is unknown, if the user has not specified a location, if the units are invalid, or if the distance is invalid.

The atlatlong method allows a user to specify their location. You must use the authenticated SOAP node (http://norman.walsh.name/2005/02/witw/ami/soap) in order to access this method and the userid specified must match the authenticated user. atlatlong xs:string userid xs:decimal latitude xs:decimal longitude AuthorizationRequired InvalidUser UnknownUser InvalidLatitude InvalidLongitude It returns the userid if it succeeds or throws a SOAP fault.

The atlandmark method allows a user to specify that they are at a particular landmark. Like the atlatlong method, you must use the authenticated SOAP node (http://norman.walsh.name/2005/02/witw/ami/soap) in order to access this method and the userid specified must match the authenticated user. atlandmark xs:string userid xs:string landmark AuthorizationRequired InvalidUser UnknownUser UnknownLandmark It returns the userid if it succeeds or throws a SOAP fault.

On the assumption that any who's read this far won't be scared off by a few lines of code, here's a short Perl script that returns the latitude and longitude of a user. This morning, if you pass it ndw, it tells you I'm at home: $ perl witw.soap.pl ndw Norman Walsh was last seen at 42.34N, 72.45W. That was on 2005-02-17T21:35:42Z. To satisfy my own curiosity, I wrote a Perl script to get the same information using the brute force API: The two styles of API are clearly quite different, but I'll reserve judgement until I've done a few more experiments.