Skip to content

Search in Rectangular Area

This API runs a search within a rectangular area of the map. The area is defined with the coordinates of the North West and South East corners of the map rectangle.

- (void)getPointsWithGeoQuery:(BackendlessGeoQuery * _Nonnull)geoQuery responseHandler:^(NSArray<GeoPoint *> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;
func getPoints(geoQuery: BackendlessGeoQuery, responseHandler: (([GeoPoint]) -> Void)!, errorHandler: ((Fault) -> Void)!)

where:

Argument                Description
geoQuery 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.

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, however, only the coordinates defining the rectangular area are required.  A search query must be performed within at least one category. If no category names are provided, the search is performed in the Default category.

Search in a rectangle in categories

Rectangle-based search establishes a geographic area by setting the coordinates of the North West and South East corners of the area. Backendless searches for geo points in the specified area and includes them into the search result:

GeoPoint *geoPoint1 = [[GeoPoint alloc] initWithLatitude:32.78 longitude:-96.8];
GeoPoint *geoPoint2 = [[GeoPoint alloc] initWithLatitude:25.79 longitude:-80.22];

BackendlessGeoQuery *geoQuery = [BackendlessGeoQuery new];
geoQuery.categories = @[@"restaurants"];
geoQuery.rectangle = [[GeoQueryRectangle alloc] initWithNordWestPoint:geoPoint1 southEastPoint:geoPoint2];

[Backendless.shared.geo getPointsWithGeoQuery:geoQuery responseHandler:^(NSArray *geoPoints) {
    NSLog(@"Retrieved geoPoints: %@", geoPoints);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];
let geoPoint1 = GeoPoint(latitude: 32.78, longitude: -96.8)
let geoPoint2 = GeoPoint(latitude: 25.79, longitude: -80.22)

let geoQuery = BackendlessGeoQuery()
geoQuery.categories = ["restaurants"]
geoQuery.rectangle = GeoQueryRectangle(nordWestPoint: geoPoint1, southEastPoint: geoPoint2)

Backendless.shared.geo.getPoints(geoQuery: geoQuery, responseHandler: { geoPoints in
    print("Retrieved geoPoints: \(geoPoints)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

Search in categories in a rectangular area and metadata

This is the same as above, with the difference that the search result includes only geo points with the matching metadata:

GeoPoint *geoPoint1 = [[GeoPoint alloc] initWithLatitude:32.78 longitude:-96.8];
GeoPoint *geoPoint2 = [[GeoPoint alloc] initWithLatitude:25.79 longitude:-80.22];

BackendlessGeoQuery *geoQuery = [BackendlessGeoQuery new];
geoQuery.categories = @[@"restaurants"];
geoQuery.rectangle = [[GeoQueryRectangle alloc] initWithNordWestPoint:geoPoint1 southEastPoint:geoPoint2];
geoQuery.metadata = @{@"cuisine": @"french", @"atmosphere": @"romantic"};

[Backendless.shared.geo getPointsWithGeoQuery:geoQuery responseHandler:^(NSArray *geoPoints) {
    NSLog(@"Retrieved geoPoints: %@", geoPoints);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];
let geoPoint1 = GeoPoint(latitude: 32.78, longitude: -96.8)
let geoPoint2 = GeoPoint(latitude: 25.79, longitude: -80.22)

let geoQuery = BackendlessGeoQuery()
geoQuery.categories = ["restaurants"]
geoQuery.rectangle = GeoQueryRectangle(nordWestPoint: geoPoint1, southEastPoint: geoPoint2)
geoQuery.metadata = ["cuisine": "french", "atmosphere": "romantic"]

Backendless.shared.geo.getPoints(geoQuery: geoQuery, responseHandler: { geoPoints in
    print("Retrieved geoPoints: \(geoPoints)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

Using dates in where clause

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:

GeoPoint *center = [[GeoPoint alloc] initWithLatitude:21.306944 longitude:-157.858333];

BackendlessGeoQuery *geoQuery = [BackendlessGeoQuery new];
geoQuery.categories = @[@"restaurants"];
geoQuery.rectangle = [[GeoQueryRectangle alloc] initWithCenter:center length:0.5 width:0.5];
double now = [[NSDate date] timeIntervalSince1970];
geoQuery.whereClause = [NSString stringWithFormat:@"opened < %@ AND closed > %@", @(now), @(now)];

[Backendless.shared.geo getPointsWithGeoQuery:geoQuery responseHandler:^(NSArray *geoPoints) {
    NSLog(@"Retrieved geoPoints: %@", geoPoints);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];
let center = GeoPoint(latitude: 21.306944, longitude: -157.858333)

let geoQuery = BackendlessGeoQuery()
geoQuery.categories = ["restaurants"]
geoQuery.rectangle = GeoQueryRectangle(center: center, length: 0.5, width: 0.5)

let now = Date().timeIntervalSince1970
geoQuery.whereClause = "opened < \(now) AND closed > \(now)"

Backendless.shared.geo.getPoints(geoQuery: geoQuery, responseHandler: { geoPoints in
    print("Retrieved geoPoints: \(geoPoints)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

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. The syntax for requesting metadata in response is described in the Search in Category section.