Skip to content

Search in Category

This API supports two types of geo searches:

  • Search in one or more geo categories.
  • Search based on metadata properties in one or more categories .

Methods


Future<List<GeoPoint>> Backendless.geo.getPoints({BackendlessGeoQuery query});

where:

Argument                Description
query a query object encapsulating the search parameters. See the Running Search Queries section below for details.

Return Value

A collection of GeoPoint objects matching the search query. Each GeoPoint instance contains:

Argument                Description
objectId an ID assigned to geo point by Backendless when it is saved in the backend geo location storage.
latitude latitude of the geo point.
longitude longitude of the geo point.
categories an array of geo categories the point belong to.
metadata metadata associated with the geo point. Accepted values for this parameter are: String, Number (integer and double), and property names of the related objects stored in the database. Date values must be represented as number in the Unix timestamp format (number of milliseconds since January 1, 1970 at UTC). Learn more about using date in search queries for category, radius, or rectangular area search.

Since the search query may produce a large number of geo points, not all of them are returned at once. Instead, all found geo points are divided into 'pages'. The size of each page is determined by the pageSize parameter in the query object. The first response returns the first page. The query object includes methods for adjusting page size and offset. Subsequent search requests with the query object will return additional pages of data.

Calculating offset

All geo points in the entire search result are indexed. The index of the first geo point is 0. The offset parameter in the query object specifies the index from which to load the next page of geo points. For example, suppose the entire search result is 200 points. If the initial pageSize is 20, then only 20 geo points are returned in the first response. To get the second page of geo points, they should be loaded from offset 20, third from 40 and so on. The formula for calculating the offset is:
 [value of offset in the current response] + [size of current page ].

Running Search Queries

The geo query object includes multiple parameters. Depending on which parameters contain values, the semantics of the search would change. Any search must be performed within at least one category. If no category names are provided, the search is performed in the Default category.

Search in categories

To search in one or more categories without any constraints on metadata or proximity to a center point, simply set the names of the categories in the query object. The request returns all geo points divided into pages of data, one page at a time.

BackendlessGeoQuery geoQuery = BackendlessGeoQuery()
  ..categories = ["Restaurants"];

Backendless.geo.getPoints(query: geoQuery).then((geoPoints) {
  print("Geo points in 'Restaurants' category: $geoPoints");
});

Search in categories with metadata

Metadata-based search finds all geo points which match all specified metadata properties in the given categories. The example below searches for the geo points in the Restaurants category with metadata containing "Cuisine = French" and "Atmosphere = Romantic".

BackendlessGeoQuery geoQuery = BackendlessGeoQuery()
  ..categories = ["Restaurants"]
  ..metadata = {
    "Cuisine": "French",
    "Athmosphere": "Romantic",
  };

Backendless.geo.getPoints(query: geoQuery).then((geoPoints) {
  print("Restaurants with French cuisine and romantic athmosphere: $geoPoints");
});


Using dates in where clause when searching in categories

The search query used to retrieve geo points may reference date values. These values must be stored as a number of milliseconds since January 1st, 1970 at UTC. The example below demonstrates the usage of a date/time timestamp in a search query:

void searchByDateInCategory() {
  // date
  DateTime updated = DateTime.parse("2015-01-17 12:00:00");

  // create geo point
  GeoPoint geoPoint = GeoPoint.fromLatLng(21.306944, -157.858333)
    ..categories = ["Coffee"]
    ..metadata = {
      "Name": "Starbucks",
      "Parking": true,
      "updated": DateTime.now(),
    };

  Backendless.geo.savePoint(geoPoint).then((savedGeoPoint) {
    // search
    BackendlessGeoQuery geoQuery = BackendlessGeoQuery()
      ..categories = ["Coffee"]
      ..whereClause = "updated > ${updated.millisecondsSinceEpoch}"
      ..includeMeta = true;

      Backendless.geo.getPoints(query: geoQuery).then((points) {
        print("searchByDateInCategory GETPOINTS: $points");
      });
  });
}

Requesting meta in response

Geo points returned in the search results do not include their metadata properties by default. The search query object includes a property which can be used to request the metadata to be included. This property can be used with any search options described above. For example, the following code runs a search in a category and requests the metadata to be included:

BackendlessGeoQuery geoQuery = BackendlessGeoQuery()
  ..categories = ["Restaurants"]
  ..includeMeta = true;

Backendless.geo.getPoints(query: geoQuery).then((geoPoints) {
  print("Geo points in 'Restaurants' category with metadata: $geoPoints");
});