Location

The content in this guide refers to the newly released version 3 of the library. You can still access the version 1.x guides here.

Version 1.x is now deprecated. We will continue to support 1.x through March 31, 2017 (End of Support - EOS). If you are currently using 1.x in your apps, you will need to upgrade your apps to 3.x before the EOS date. We have created a migration guide to help you.

Kinvey allows you to express the location of entities, including users, as longitude and latitude points on the coordinate system. Based on this, you can run proximity queries to find the closest restaurants, shops, or friends to a given location.

For an entity to have an associated location, set a property named _geoloc to a location using an array with two values: longitude and latitude:

{
  _id: 'entity-id',
  _geoloc: [ -71, 42 ]// longitude: -71, latitude: 42.
}

Queries

Location Queries are only available on fields named _geoloc. The value of this field should be an array holding two elements: longitude and latitude (in that order). We’ll index that attribute for you, so you can run location queries on it.

The following Location Operators are supported by Kinvey.Query:

  • near matches if the field is within the supplied radius (in miles) of the supplied coordinate.
  • withinBox matches if the field is within the box specified by the two supplied coordinates.
  • withinPolygon matches if the field is within the polygon specified by the supplied list of coordinates.

For example, a query to retrieve all restaurants close (10 mile radius) to a users’ current location could look as follows:

// Get users current position.
Titanium.Geolocation.getCurrentPosition(function(loc) {
  var coord = [loc.coords.longitude, loc.coords.latitude];

  // Query for buildings close by.
  var query = new Kinvey.Query();
  query.near('_geoloc', coord, 10);

  var store = Kinvey.DataStore.getInstance('restarants');
  var promise = store.find(query);
  promise.then(function(response) {
    ...
  }).catch(function(error) {
    ...
  });
});
Got a question?