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.

Saving location data in an entity

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"
	}      
	

Querying location data

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
-(NSString*)geoQuery {
    
    //instantiate the App Delegate class
    AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate];
    
    //specify the entity type that you want to query
	NSString *type = @"device";
	
	//instantiate the ApigeeQuery class
    ApigeeQuery *qs = [[ApigeeQuery alloc] init];
    
    //add the location query to the query
	[qs addRequiredWithin:@"location" latitude:37.774989 longitude:-122.419413 distance:16000.00];
 
    //call getEntities to initiate the request
	ApigeeClientResponse *entities = [appDelegate.dataClient getEntities:type query:qs];

    @try {
        //success
    }
    @catch (NSException * e) {
        //error
    }
}			
			

//instantiate ApigeeClient and get an instance of ApigeeDataClient 
String ORGNAME = "your-org";
String APPNAME = "your-app";        

ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME, getBaseContext());
DataClient dataClient = apigeeClient.getDataClient();

//specify an entity type to retrieve
String type = "device"; //entity type to be retrieved        

//specify our geo query, including distance, latitude and longitude
String queryString = "location within 16000 of 37.774989, -122.419413";

//call getEntitiesAsync to initiate the asynchronous API call    
dataClient.getEntitiesAsync(type, queryString, new ApiResponseCallback() {	


@Override
public void onException(Exception e) { 
	// Error
}

@Override
public void onResponse(ApiResponse response) {
    try { 
        if (response != null) {
            // Success
        }
    } catch (Exception e) { //The API request returned an error
        	// Fail
    }
}
});	
			
var dataClient = new Apigee.Client({
	orgName:'your-org',
	appName:'your-app'
});

var options = {
	type:"item", //Required - the type of collection to be retrieved
	client:dataClient,
	qs:{ql:"location within 16000 of 37.774989, -122.419413"}
};

//Create a collection object to hold the response
var collection = new Apigee.Collection(options);

//Call request to initiate the API call
collection.fetch(function (error, response) {
	if (error) {
		//error
	} else {
		//success      
	}
});
			
#Create a client object
usergrid_api = 'https://api.usergrid.com'
organization = 'your-org'
application = 'your-app'

dataClient = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}"

begin
# Retrieve the collection by referencing the [type]
# and save the response
response = dataClient['devices'].query("location within 16000 of 37.774989, -122.419413").entity

rescue
#fail
end
			
var dataClient = new Usergrid.client({
	orgName:'your-org',
	appName:'your-app'
});

var options = {
	type:"item", //Required - the type of collection to be retrieved
	client:dataClient,
	qs:"location within 16000 of 37.774989, -122.419413"
};

//Create a collection object to hold the response
var collection = new Usergrid.collection(options);

//Call request to initiate the API call
collection.fetch(function (error, response) {
	if (error) {
		//error
	} else {
		//success      
	}
});
			

Enrich your app with location data

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:

Entity type Usage
user Save the location of a user's home as part of their profile in the users collection to suggest upcoming special events or activities located nearby, or to display advertisements that are relevant based on the user's proximity to a business.
device Periodically save the location data returned from a user's device, then query the devices collection to send offers and alerts to user's that are located near your business with a push notification .
activity Create stronger social connections by associating a user activity with the location where it occurred. The activity can then be displayed to nearby friends and family, or used to enrich the user's activity stream.
asset Save user photos with location data in the asset collection to allow users to retrieve and sort their memories based on when and where they happened.

 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)