|
The XML-formatted location information for a device can be accessed here:
http://www.rnoc.gatech.edu/whereami/locationService.php
The API supports two distinct modes of operation. The first party lookup service is a
simple web query that returns the location of the querying host. The third party lookup
service supports several different queries and is described in more detail later in this
document.
The first party service accepts 2 parameters:
numLocations
- This specifies the number of previous locations returned by the service. The default is 5. If there are fewer
location records available than requested, then only the number available will be returned.
The following example
will return up to 10 previous locations observed for the client in the past 24 hours.
http://www.rnoc.gatech.edu/whereami/locationService.php?numLocations=10
determinationMethod
- This allows you to specify which location determination method
is used for calculating the location of the client. Currently the only choices are
"AssociationEvent", which uses the clients association with a wireless access point and
"ipAddress", which uses a naive IP address registration look-up to determine the location of the IP address.
We hope to soon add more, and better, determination methods.
If you specify the determinationMethod then only that method will be used. By default
"AssociationEvent" is tried first since it is more precise.
If that doesn't work then "ipAddress" is used.
If you specify "AssociationEvent" and your device can't be found on LAWN, then an error will be
returned, the system will not try to use "ipAddress".
This is designed to be used for services that want all or nothing functionality.
The following example will return your location using association events only.
If WhereAmI cannot determine a location using association events it will
return an error.
http://www.rnoc.gatech.edu/whereami/locationService.php?determinationMethod=AssociationEvent
LocationResponse
This is the root data type that contains all the information that whereami will give back
to the user. A LocationResponse will allways contain a requestInformation and will either
contain one or more locationInformations or an error depending on the success or failure of
your location request.
requestInformation
A requestInformation is mainly a sanity check to ensure whereami is answering the
question you asked the way you asked it. The IpAddress element returns what whereami
thinks is the IP address of the client it is looking up location information for.
DeterminationMethod lets the user know which method whereami ended up using to
determine the location of the user.
locationInformation
LocationInformation contains the physical location information as well as a time stamp of
the user's location.
Coord has the latitude, longitude and altitide of the user. The latitude and longitude are in
signed decimal format. A positive latitude correlates to North, while negative correlates to
South. A positive longitude correlates to East and a negative correlates to West. Altitude
is given in meters above sea level. Currently 280 is always returned for the altitude of
locations on
campus. As we refine our system we hope to give altitude in response to the floor of the
building you are on.
AccuracyRadius gives the radius of a circle in meters that the user is believed
to be in centered at
the point given in coord.
ArriveTime gives the time that the user is believed to arrived at the given location.
If whereami does not know for sure when the user arrived at this location the valid
attribute will be se to false, otherwise it will be set to true. The offset from UTC
is given in +/-hhmm. Time is given in YYYY-MM-DD HH:mm:SS, offset by the given
UTC offset. The same format applies to leaveTime which specifies the time whereami
thinks that the user left, if they have left, the given location.
ArriveTime and leaveTime mainly apply when using location determination methods
that allow whereami to know when the user came and went. For IP address info look-up
arrive and leave times don't apply since whereami has no way of knowing when the
IP address was associated with a location. For determination methods that look-up the
location of the user instantanously the arriveTime will be the valid time stamp.
error
Error specifies an error, if one has occured. The code is a numeric ID of the error
that has occured. The longDescription gives a human readable description of the
error that occured.
These are some example XML files that illustrate what a response from whereami
will look like.
A successfull request for association event determined location information
A successfull request for IP address determined location information
A erronous request for association event determined location information
To make it easier for you to get things started we've created some Java classes that wrap the XML data
returned by whereami. As a quick disclaimer these classes were designed to provide very basic
functionality. There is lots of room for improvement. If you'd created an improved version or have
found found a bug
please tell us
Below are the following resources:
Jar file containg all classes
Java doc API
Here's a simple example of how to use the java classes. Everything is done in the LocationResponse class
Just call the static getLocation(url) method with the url of the service and any parameters you want to pass
in in the url string. This just prints out the returned location information. For more info see the API.
import edu.gatech.oit.rnoc.whereami.LocationResponse;
public class Test
{
public static void main(String[] args)
{
string url = "http://www.rnoc.gatech.edu/whereami/locationService.php";
System.out.println("My location information");
LocationResponse lr = LocationResponse.getLocation(url);
System.out.println(lr);
}
}
In addition to the J2SE whereami classes we also have a J2ME version. The API for these classes
is very similar to the one for the J2SE platform. Again, as a quick disclaimer these classes were designed
to provide very basic functionality. There is lots of room for improvement. If you'd created an improved
version or have found found a bug
please tell us
Since J2ME doesn't come with any XML functionality we are using kXML
to parse the XML from whereami. So you'll need to add both whereami_mobile_java_api.jar and kxml 2.3.0 jar to your class path. And
remember to select them in the "Order and Export" tab.
Below are the following resources:
kxml 2.3.0 jar file for handling the XML
Jar file containg all classes
Java doc API
Here's a simple example of how to use the java classes. Everything is done in the LocationResponse class
Just call the static getLocation(url) method with the url of the service and any parameters you want to pass
in in the url string. This just prints out the returned location information. For more info see the API.
import edu.gatech.oit.rnoc.whereami.mobile.LocationResponse;
public class whereamiTestMidlet extends MIDlet
{
protected void startApp() throws MIDletStateChangeException
{
string url = "http://www.rnoc.gatech.edu/whereami/locationService.php";
StringItem stringItem = new StringItem("Text:","");
displayable.append(stringItem);
LocationResponse lr = LocationResponse.getLocation(url);
stringItem.setText(lr.toString());
}
}
There are two major differences between the first party API and the third party API.
First, in order to manage privacy issues, third party lookups require authentication
with the WhereAmI server through WebAuth.
Second, the query must specify the target user to be located.
The following is an example call to the main third party lookup service.
https://webhost.gatech.edu/rnoc/whereami3p/getMostRecentUserLocation.php?requestor=george_burdell&subject=techfan&numLocations=5
First, note that this lookup uses https and will require WebAuth authentication using your GT username and password. The parameters are as follows.
watcher
- This specifies the handle of the user making the request. WhereAmI allows
users to create a unique user handle that is different from their GT username.
This user handle is what is specified here.
The term watcher is consistent with standard Presence service terminology.
subject
- This specifies the handle of the user you are trying to locate.
numLocations
- As in the first party lookups, this specifies the number of recent location matches
desired. This parameter is optional and the default value is 5.
https://webhost.gatech.edu/rnoc/whereami3p/getWatcherList.php?name=george_burdell
First, note that this lookup uses https and will require WebAuth authentication using your GT username and password. The parameters are as follows.
name
- This specifies the handle of the user for whom the list is being requested.
| 
