Search by distance¶

With the ability to store spatial data in the database,you can search for data objects by distance. This type of search returns a paged set of data objects which satisfy the whereClause condition and located within the specified distance. Distance-based search uses a special function in whereClause of the search request. The syntax of the function is:

distance( 
   center point latitude, 
   center point longitude, 
   columnname which contains geo point.latitude,
   columnname which contains geo point.longitude )<operator> units-function(value)

where:

Argument	Description
`<operator>`	Possible values are <, >, =, >=, <=
`units-function`	Defines the units of measure for the distance. Possible values are: `ft( X )` - the distance value X is expressed in feet `km( X )` - the distance value X is expressed in kilometers `mi( X )` - the distance value X is expressed in miles `yd( X )` - the distance value X is expressed in yards

For example, the following whereClause expression searches for data objects located within 200 miles from the point at 30.26715, -97.74306. Each data object must have the coordinates property of type GeoPoint.

distance( 30.26715, -97.74306, coordinates.latitude, coordinates.longitude ) < mi(200)

The following example demonstrates a search-by-distance query. The example uses three data objects stored in the Friend table: Bob, Jane, and Fred who respectively live in Austin, Houston, San Antonio. The search query in the example finds all friends who live within the specified distance. Before running the search query, create the objects in the data storage with the corresponding geo points.

The application must be setup with demo data in order to run the example and see the distance operator in action. See the setup code in the expandable block below:

Setting up the app with demo data.

Using Untyped Objects

You do not need to declare/write any custom classes/function when using the "Untyped Objects" approach. Data records are represented as plain JS objects. Column names become object properties. === "Custom Class/Function"

The Friend class definition:

function Friend()
{
  this.name = "";
  this.phoneNumber = "";
  this.coordinates = undefined;
}

Run the following query/code to store a data object representing Bob with a link to his home in Austin, TX:

Using Untyped ObjectsCustom Class/Function

// Create an object representing a geopoint. The ___class property is special, 
// it tells Backendless that the object is a GeoPoint and must be stored in
// the Backendless geo storage.
var bobsHomeLocation = {
  ___class : "GeoPoint",
  latitude: 29.76328,
  longitude: -95.36327,
  categories: [ "Home" ],
  metadata: { description:"Bob's home" }
}

// Notice the "coordinates" property, it links the object with 
// the corresponding geopoint
var bob = { 
  name:"Bob",
  phoneNumber:"512-555-1212",
  coordinates: bobsHomeLocation
};

// Save "bob" and his location in the Backendless geostorage
Backendless.Data.of( "Friend" ).save( bob )
 .then( function( result ) {
  console.log( "object and its geopoint location have been saved" );
 })
 .catch( function( error ) {
   console.log( "error " + error.message );
});

var geopoint = new Backendless.GeoPoint();
geopoint.latitude = 29.76328;
geopoint.longitude = -95.36327;
geopoint.categories = ["Home"];
geopoint.metadata = { description:"Bob's home" };

var bob = new Friend();
bob.name = "Bob";
bob.phoneNumber = "512-555-1212";
bob.coordinates = geopoint;

Backendless.Data.of( Friend ).save( bob )
 .then( function( result ) {
   console.log( "object bob with the related geopoint has been saved" );
 })
 .catch( function( error ) {
   console.log( "error " + error.message );
 });

Run the following query/code to store a data object representing Jane with a link to her home in Houston, TX:

Using Untyped ObjectsCustom Class/Function

// Create an object representing a geopoint. The ___class property is special, 
// it tells Backendless that the object is a GeoPoint and must be stored in
// the Backendless geo storage.
var janesHomeLocation = {
  ___class : "GeoPoint",
  latitude:29.76328,
  longitude: -95.36327,
  categories: [ "Home" ],
  metadata: { description:"Jane's home" }
}

// Notice the "coordinates" property, it links the object with 
// the corresponding geopoint
var jane = { 
  name:"Jane",
  phoneNumber:"281-555-1212",
  coordinates: janesHomeLocation
};

// Save "jane" and her location in the Backendless geostorage
Backendless.Data.of( "Friend" ).save( jane )
 .then( function( result ) {
  console.log( "object and its geopoint location have been saved" );
 })
 .catch( function( error ) {
   console.log( "error " + error.message );
});

var geopoint = new Backendless.GeoPoint();
geopoint.latitude = 29.76328;
geopoint.longitude = -95.36327;
geopoint.categories = ["Home"];
geopoint.metadata = { description:"Jane's home" };

var jane = new Friend();
jane.name = "Jane";
jane.phoneNumber = "281-555-1212";
jane.coordinates = geopoint;

Backendless.Data.of( Friend ).save( jane )
 .then( function( result ) {
   console.log( "object jane with the related geopoint has been saved" );
 })
 .catch( function( error ) {
   console.log( "error " + error.message );
 });

Run the following query/code to store a data object representing Fred with a link to his home in San Antonio, TX:

Using Untyped ObjectsCustom Class/Function

// Create an object representing a geopoint. The ___class property is special, 
// it tells Backendless that the object is a GeoPoint and must be stored in
// the Backendless geo storage.
var fredsHomeLocation = {
  ___class : "GeoPoint",
  latitude:29.42412,
  longitude: -98.49363,
  categories: [ "Home" ],
  metadata: { description:"Fred's home" }
}

// Notice the "coordinates" property, it links the object with 
// the corresponding geopoint
var fred = { 
  name:"Fred",
  phoneNumber:"210-555-1212",
  coordinates: fredsHomeLocation
};

// Save "fred" and his location in the Backendless geostorage
Backendless.Data.of( "Friend" ).save( fred )
 .then( function( result ) {
  console.log( "object and its geopoint location have been saved" );
 })
 .catch( function( error ) {
   console.log( "error " + error.message );
});

var geopoint = new Backendless.GeoPoint();
geopoint.latitude = 29.42412;
geopoint.longitude = -98.49363;
geopoint.categories = ["Home"];
geopoint.metadata = { description:"Fred's home" };

var fred = new Friend();
fred.name = "Jane";
fred.phoneNumber = "210-555-1212";
fred.coordinates = geopoint;

Backendless.Data.of( Friend ).save( fred )
 .then( function( result ) {
   console.log( "object fred with the related geopoint has been saved" );
 })
 .catch( function( error ) {
   console.log( "error " + error.message );
 });

Once the data is in the database and the geo location storage, you can verify it in Backendless Console by opening the Geolocation screen and selecting the Home geocategory:

Suppose you need to get all objects located within 300 miles radius from Beaumont, TX, which has the GPS coordinates of 30.084, -94.145. The following code/query performs that distance-based search:

Using Untyped ObjectsCustom Class/Function

var whereClause = "distance( 30.26715, -97.74306, " + 
                  "coordinates.latitude, " +
                  "coordinates.longitude ) < mi(200)";
var queryBuilder = DataQueryBuilder.create();
queryBuilder.setWhereClause( whereClause ).setRelationsDepth( 1 );
var friends = Backendless.Data.of( "Friend" ).find( queryBuilder );

friends.forEach( function( friend ) {
  console.log(  friend.name + 
                " lives at " +
                friend.coordinates.latitude + " , " +
                friend.coordinates.longitude + " " +
                friend.coordinates.metadata.description); 
});

var whereClause = "distance( 30.26715, -97.74306, " + 
                  "coordinates.latitude, " + 
                  "coordinates.longitude ) < mi(200)";
var queryBuilder = DataQueryBuilder.create();
queryBuilder.setWhereClause( whereClause ).setRelationsDepth( 1 );
var friends = Backendless.Data.of( Friend ).find( queryBuilder );

friends.forEach( function( friend ) {
  console.log(  friend.name + 
                " lives at " +
                friend.coordinates.latitude + " , " +
                friend.coordinates.longitude + " " +
                friend.coordinates.metadata.description); 
});

The search returns all data objects within the specified distance. Each data object has the Coordinates property containing the coordinates of a geo point associated with this data object.