Geolocation

Many of today's apps are enhanced by the use of geolocation, wireless detection of the physical location of a remote device. These apps are said to be geolocation-aware in that they query the device to determine the user's position and then use this data to further enhance the user's experience. For example, apps can capture the exact location where a picture was taken or a message was created.

App services support geolocation on any entity, both built in (e.g., users, groups) and user defined.

Back to top

Adding a location to an entity

To add a location to any entity, include the following member to the JSON in a POST or PUT call:

"location": {
    "latitude": 37.779632,
    "longitude": -122.395131  
}

For example, to store a listing of restaurants and their locations, start by creating a collection called restaurants:

POST https://api.usergrid.com/org_name/app_name/restaurants

Next, add a new entity to the collection:

POST https://api.usergrid.com/org_name/app_name/restaurants
{
  "name": "Rockadero",
  "address": "21 Slate Street, Bedrock, CA",
  "location": {
    "latitude": 37.779632,
    "longitude": -122.395131
  }
}

This creates a new restaurant entity called "Rockadero" with the longitude and latitude included as part of the object.

You can also use geolocation to keep track of the location of a user. In this case, the user already exists, so you just need to update that user entity. Use POST and include the location member:

POST https://api.usergrid.com/org_name/app_name/users/fred
{
  "location": {
    "latitude": 37.779632,
    "longitude": -122.395131
  }
}

This either adds or updates the location member of the user object for the user fred.

Back to top

Making queries against an entity's location

When a location is added to an entity, it is easy to make queries against that data. For example, to see all restaurants within a 10 mile radius of the user's location, make a GET call against that entity, and include a search query in the following format:

location within <distance in meters> of <latitude>, <longitude>

If we use the location of our user Fred, we first need to convert miles to meters. 1 mile is equivalent to 1609.344 meters, so 10 miles is about 16093 meters. Thus, the API call looks like this:

GET https://api.usergrid.com/org_name/app_name/restaurants?ql=location within 16093 of 37.776753, -122.407846

The url-encoded version looks like this:

https://api.usergrid.com/org_name/app_name/restaurants?ql=location%20within%2016093%20of%2037.776753%2C%20-122.407846&_=1337570474469

In this case, the API call returns one entry for the Rockadero, which is exactly where Fred happens to be. Bon Appetit!

Back to top