Location

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.

Location queries are only possible when the data store is in Network mode. Location queries in Cache or Sync mode return an error.

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 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.

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

// Get user's current position
navigator.geolocation.getCurrentPosition(function(loc) {
  var coord = [loc.coords.longitude, loc.coords.latitude];

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

  var dataStore = Kinvey.DataStore.collection(
        'restaurants',
        Kinvey.DataStoreType.Network
  );
  var stream = dataStore.find(query);
  stream.subscribe(function onNext(entities) {
    // ...
  }, function onError(error) {
    // ...
  }, function onComplete() {
    // ...
  });
});

Guides

Location

Queries