Reading a user’s location

Reading back a user’s current location can be done with a single simple call:

http://mapme.at/api/where.json

This will give a response similar to the following examples. The first shows an arbitrary location, the second a favourite:

{
    "title": "Current location of john",
    "accuracy": 1,
    "username": "john",
    "current": true,
    "locations": [
        {
            "lat":37.78805,
            "lon": -122.4101,
            "bb":"32.5553,-124.3570;42.0007,-114.1420",
            "time_logged":"2009/02/06 00:45:00 +0000",
            "local_area":"Little Osaka",
            "state":"California",
            "country_code":"US",
            "source":"web",
            "favourite":null
        }
    ]
}

{
    "title": "Current location of john",
    "accuracy": 1,
    "username": "john",
    "current": true,
    "locations": [
        {
            "lat":37.78491,
            "lon": -122.40531,
            "bb": "32.5553,-124.3570;42.0007,-114.1420",
            "time_logged": "2009/02/04 18:39:14 +0000",
            "local_area": "Little Osaka",
            "state":"California",
            "country_code": "US",
            "source":"web",
            "favourite": {
                "label": "mosserhotel",
                "description": "The Mosser Hotel",
                "tags": "hotel",
                "global": false
            }
        }
    ]
}

Currently you will be able to get the user’s location at full accuracy. In the future we will allow the user to specify the accuracy when authorizing your OAuth request.

You can also request all the locations that were logged on a specific day (GMT) or all the locations logged in a given time span. By default if the user logs their location at a specific favourite location multiple times, we will only give the first and last of these (only the first while they are still at the location). This allows applications to continuously ping someone’s location without cluttering up the output from this call. If you want the API to return all logged locations you can request that with expanded=full. You can also use expanded=bordered to always show the first and last log at a location.

To request a time span use the since and until parameters. If the until parameter is left out then the current time on the server is used instead. These parameters uses the Ruby Chronic library which allows a large range of formats for describing the time. When using the since parameter we will always give you the last log before that time so that you know the starting location for the user. A few examples of requesting past locations follow:

http://mapme.at/api/where.json?mode=since&since=6%20hours%20ago

http://mapme.at/api/where.json?mode=day&day=20090216

http://mapme.at/api/where.json?mode=since&since=1%20day%20ago&expanded=true

http://mapme.at/api/where.json?mode=since&since=7%20days%20ago&until=6%20days%20ago

The output from these calls is always of the same format but you will potentially get more than one result in the ‘locations’ array. Remember that you may get zero results in the ‘locations’ array though this will only happen if the user has not updated their location, as usually the API will return the last location the user was seen in at least. You can also request output in Atom format by replacing the .json extension with .atom.