Many of today‘s apps are enhanced by the use of geolocation – wireless detection of the physical location of a remote device. These apps determine the user’s position and use this data to enhance user experience. For example, apps can capture the exact location where a picture was taken or determine what businesses stored in the database to return to the user based on their current location.
API Services provides a standard format for storing geolocation information in any entity, as well as syntax for querying that data based on distance from a latitude/longitude point.
In API Services, geolocation data is saved in the location property of an entity with latitude and longitude sub-properites in the following format:
"location": {
"latitude": <latitude_coordinate>,
"longitude": <longitude_coordinate>
}
An entity's geolocation can be specified when the entity is created or added later by updating an existing entity.
For example, the following entity describes a restaurant:
{
"uuid" : "03ae956a-249f-11e3-9f80-d16344f5a0e1",
"type" : "restaurant",
"name" : "Rockadero",
"location": {
"latitude": 37.779632,
"longitude": -122.395131
}
"created" : 1379975113142,
"modified" : 1379975113142,
"metadata" : {
"path" : "/restaurants/03ae956a-249f-11e3-9f80-d16344f5a0e1"
}
Location-aware apps require the ability to return content and results based on the user's current location. To easily enable this, API Services supports the following query parameter to retrieve entities within a specified distance of any geocoordinate based on its location property:
location within <distance_in_meters> of <latitude>, <longitude>
The returned results are sorted from nearest to furthest. Entities with the same location are returned in the order they were created.
The location parameter can be appended to any standard API Services query. For more information on how to query your API Services data, see Querying your Data.
For example, here is how you would find all the devices within 8,046 meters (~10 miles) of the center of San Francisco:
curl -X GET https://api.usergrid.com/your-org/your-app/devices?ql=location within 8046 of 37.774989,-122.419413
Location-awareness has become a feature users expect in many types of mobile applications because of its ability to create a more personalized and relevant experience for each user. With this in mind, the geolocation feature in API Services was designed to work with many of the available default data entities to allow app developers to easily integrate powerful in-app features that can increase user engagement.
Here are just a few of the ways that saving location data to a data entity can improve an app: