Geoqueries

9min
Geoqueries
Introduction
We use the term Geoqueries to refer to the type of queries where their conditions involve ParseGeoPoint type fields. It is recommended to use the ParseGeoPoint struct to store geographic location data in a Back4App Database. The ParseSwift SDK provides a set of methods that allows us to query data according to conditions applied on ParseGeoPointdata type.
Prerequisites
To complete this tutorial, you will need:
An App created on Back4App.
A basic iOS App to test queries
Goal
To understand how to query data using conditions on geographic location data.
- Quick review about the Query<U> class
Any query performed on a Back4App Database is done via the generic class Query<U>. The generic parameter U (conforming to the ParseObject protocol) is the data type of the objects we are trying to retrieve from the database.
Given a data type like MyObject, we retrieve these objects from a Back4App Database in the following way
Swift
 import ParseSwift
2
 struct MyObject: ParseObject {
   ...
 }
6
 let query = MyObject.query()
8
 // Executes the query asynchronously
query.find { result in
  // Handle the result (of type Result<[MyObject], ParseError>)
}
 import ParseSwift
2
 struct MyObject: ParseObject {
   ...
 }
6
 let query = MyObject.query()
8
 // Executes the query asynchronously
query.find { result in
  // Handle the result (of type Result<[MyObject], ParseError>)
}
﻿
You can read more about the Query<U> class here at the official documentation.
- Save some data on Back4App
Before we begin to execute queries, we should store some sample data on a Back4App Database. By following the Quickstart guide, you can configure and link your sample iOS App to your Back4App database. For this guide, we will store information about cities. We use the following struct to organize a city’s information:
Swift
 import ParseSwift
2
 struct City: ParseObject {
     ...
  
     var name: String? // City's name
     var location: ParseGeoPoint? // It will store the city's coordinate on Earth
 }
 import ParseSwift
2
 struct City: ParseObject {
     ...
  
     var name: String? // City's name
     var location: ParseGeoPoint? // It will store the city's coordinate on Earth
 }
﻿
Now, we proceed to store the sample data. This step can be implemented using Swift or directly from your app’s console on the Back4App platform. 
Swift
Back4App's console
//A quick way to insert elements on your Back4App Database is via the console located in your App’s API section. Once you are there, you can start running Javascript code to save the sample data
 // Add City objects and create table
 // Note how GeoPoints are created, passing latitude and longitude as arguments
 // Montevideo
 City = new Parse.Object('City');
 City.set('name', 'Montevideo - Uruguay');
 City.set('location', new Parse.GeoPoint(-34.85553195363169, -56.207280375137955));
 await City.save();
8
 // Brasília
City = new Parse.Object('City');
City.set('name', 'Brasília - Brazil');
City.set('location', new Parse.GeoPoint(-15.79485821477289, -47.88391074690196));
await City.save();
14
// Bogotá
City = new Parse.Object('City');
City.set('name', 'Bogotá - Colombia');
City.set('location', new Parse.GeoPoint(4.69139880891712, -74.06936691331047));
await City.save();
20
// Mexico City
City = new Parse.Object('City');
City.set('name', 'Mexico City - Mexico');
City.set('location', new Parse.GeoPoint(19.400977162618933, -99.13311378164776));
await City.save();
26
// Washington, D.C.
City = new Parse.Object('City');
City.set('name', 'Washington, D.C. - USA');
City.set('location', new Parse.GeoPoint(38.930727220189944, -77.04626261880388));
await City.save();
32
// Ottawa
City = new Parse.Object('City');
City.set('name', 'Ottawa - Canada');
City.set('location', new Parse.GeoPoint(45.41102167733425, -75.695414598736));
await City.save();
//A quick way to insert elements on your Back4App Database is via the console located in your App’s API section. Once you are there, you can start running Javascript code to save the sample data
 // Add City objects and create table
 // Note how GeoPoints are created, passing latitude and longitude as arguments
 // Montevideo
 City = new Parse.Object('City');
 City.set('name', 'Montevideo - Uruguay');
 City.set('location', new Parse.GeoPoint(-34.85553195363169, -56.207280375137955));
 await City.save();
8
 // Brasília
City = new Parse.Object('City');
City.set('name', 'Brasília - Brazil');
City.set('location', new Parse.GeoPoint(-15.79485821477289, -47.88391074690196));
await City.save();
14
// Bogotá
City = new Parse.Object('City');
City.set('name', 'Bogotá - Colombia');
City.set('location', new Parse.GeoPoint(4.69139880891712, -74.06936691331047));
await City.save();
20
// Mexico City
City = new Parse.Object('City');
City.set('name', 'Mexico City - Mexico');
City.set('location', new Parse.GeoPoint(19.400977162618933, -99.13311378164776));
await City.save();
26
// Washington, D.C.
City = new Parse.Object('City');
City.set('name', 'Washington, D.C. - USA');
City.set('location', new Parse.GeoPoint(38.930727220189944, -77.04626261880388));
await City.save();
32
// Ottawa
City = new Parse.Object('City');
City.set('name', 'Ottawa - Canada');
City.set('location', new Parse.GeoPoint(45.41102167733425, -75.695414598736));
await City.save();
﻿
- Query the data
Sorting the results
With the sample data saved, we can start performing different query types.
For our first example, we will select all the cities and sort them depending on how far they are from a reference geopoint. We implement this query by passing a constraint to the Query<City> object. The method near(key:geoPoint:) available via the ParseSwift SDK allows us to construct such constraint. As arguments, we pass the field’s name (usually referred to as key) containing the reference geoPoint.
Swift
 // The reference geopoint will be Kingston city - Jamaica
 guard let kingstonGeoPoint = try? ParseGeoPoint(latitude: 18.018086950599134, longitude: -76.79894232253473) else { return }
3
 let query = City.query(near(key: "location", geoPoint: kingstonGeoPoint)) // The method near(key:geoPoint:) returns the constraint needed to sort the query
5
 let sortedCities: [City]? = try? query.find() // Executes the query synchronosuly and returns an array containing the cities properly sorted
7
 query.find { result in // Executes the query asynchronosuly and returns a Result<[City], ParseError> type object to handle the results
   switch result {
  case .success(let cities):
    // cities = [Bogotá, Washington DC, Mexico City, Ottawa, Brasília, Montevideo]
  case .failure(let error):
    // Handle the error if something happened
  }
}
 // The reference geopoint will be Kingston city - Jamaica
 guard let kingstonGeoPoint = try? ParseGeoPoint(latitude: 18.018086950599134, longitude: -76.79894232253473) else { return }
3
 let query = City.query(near(key: "location", geoPoint: kingstonGeoPoint)) // The method near(key:geoPoint:) returns the constraint needed to sort the query
5
 let sortedCities: [City]? = try? query.find() // Executes the query synchronosuly and returns an array containing the cities properly sorted
7
 query.find { result in // Executes the query asynchronosuly and returns a Result<[City], ParseError> type object to handle the results
   switch result {
  case .success(let cities):
    // cities = [Bogotá, Washington DC, Mexico City, Ottawa, Brasília, Montevideo]
  case .failure(let error):
    // Handle the error if something happened
  }
}
﻿
Selecting results within a given region
Suppose we want to select cities within a certain region. We can achieve this with a constraint created by the method withinKilometers(key:geoPoint:distance:). As arguments, we pass the field’s name containing the city’s location, the region’s center (a ParseGeoPoint data type) and the maximum distance (in km) a city can be from this region’s center. To select all cities that are at most 3000km away from Kingston - Jamaica, we can do it in the following way
Swift
 let distance: Double = 3000 // km
 guard let kingstonGeoPoint = try? ParseGeoPoint(latitude: 18.018086950599134, longitude: -76.79894232253473) else { return }
3
 let query = City.query(withinKilometers(key: "location", geoPoint: kingstonGeoPoint, distance: distance))
 // The method withinKilometers(key:geoPoint:distance:) returns the constraint we need for this case
6
 let sortedCities: [City]? = try? query.find() // Executes the query synchronosuly and returns an array containing the cities we are looking for (Bogotá, Washington DC and Mexico city in this case)
8
 query.find { result in // Executes the query asynchronosuly and returns a Result<[City], ParseError> type object to handle the results
  switch result {
  case .success(let cities):
    // cities = [Bogotá, Washington DC, Mexico City]
  case .failure(let error):
    // Handle the error if something happened
  }
}
 let distance: Double = 3000 // km
 guard let kingstonGeoPoint = try? ParseGeoPoint(latitude: 18.018086950599134, longitude: -76.79894232253473) else { return }
3
 let query = City.query(withinKilometers(key: "location", geoPoint: kingstonGeoPoint, distance: distance))
 // The method withinKilometers(key:geoPoint:distance:) returns the constraint we need for this case
6
 let sortedCities: [City]? = try? query.find() // Executes the query synchronosuly and returns an array containing the cities we are looking for (Bogotá, Washington DC and Mexico city in this case)
8
 query.find { result in // Executes the query asynchronosuly and returns a Result<[City], ParseError> type object to handle the results
  switch result {
  case .success(let cities):
    // cities = [Bogotá, Washington DC, Mexico City]
  case .failure(let error):
    // Handle the error if something happened
  }
}
﻿
Additionally, when the distance is given in miles instead of kilomenters, we can use the withinMiles(key:geoPoint:distance:sorted:) method.
A less common method, withinRadians(key:geoPoint:distance:sorted:), is also available if the distance is given in radians. Its use is very similar to the previous methods.
Selecting results within a given polygon
In the previous example, we selected cities within a region represented by a circular region. In case we require to have a non-circular shape for the region, the ParseSwift SDK does allow us to construct such regions from their vertices.
Now, the goal for this example is to select cities within a five vertex polygon. These vertices are expressed using the ParseGeoPoint struct. Once we have created the vertices, we instantiate a ParsePolygon. This polygon is then passed to the withinPolygon(key:polygon:) method (provided by the ParseSwift SDK) to construct the constraint that will allow us to select cities within this polygon.
Swift
 // The polygon where the selected cities are
 let polygon: ParsePolygon? = {
   do {
     // We first instantiate the polygon vertices
     let geoPoint1 = try ParseGeoPoint(latitude: 15.822238344514378, longitude: -72.42845934415942)
     let geoPoint2 = try ParseGeoPoint(latitude: -0.7433770196268968, longitude: -97.44765968406668)
     let geoPoint3 = try ParseGeoPoint(latitude: -59.997149373299166, longitude: -76.52969196322749)
     let geoPoint4 = try ParseGeoPoint(latitude: -9.488786415007201, longitude: -18.346101586021952)
     let geoPoint5 = try ParseGeoPoint(latitude: 15.414859532811047, longitude: -60.00625459569375)
              
    // Next we compose the polygon
    return try ParsePolygon([geoPoint1, geoPoint2, geoPoint3, geoPoint4, geoPoint5])
  } catch let error as ParseError {
    print("Failed to instantiate vertices: \(error.message)")
    return nil
  } catch {
    print("Failed to instantiate vertices: \(error.localizedDescription)")
    return nil
  }
}()
      
guard let safePolygon = polygon else { return }
      
let query = City.query(withinPolygon(key: "location", polygon: safePolygon))
// withinPolygon(key:polygon:) returns the required constraint to apply on the query
      
let cities = try? query.find() // Executes the query synchronously
      
query.find { result in // Executes the query asynchronously and returns a result of type Result<[], ParseError>
  // Handle the result
}
 // The polygon where the selected cities are
 let polygon: ParsePolygon? = {
   do {
     // We first instantiate the polygon vertices
     let geoPoint1 = try ParseGeoPoint(latitude: 15.822238344514378, longitude: -72.42845934415942)
     let geoPoint2 = try ParseGeoPoint(latitude: -0.7433770196268968, longitude: -97.44765968406668)
     let geoPoint3 = try ParseGeoPoint(latitude: -59.997149373299166, longitude: -76.52969196322749)
     let geoPoint4 = try ParseGeoPoint(latitude: -9.488786415007201, longitude: -18.346101586021952)
     let geoPoint5 = try ParseGeoPoint(latitude: 15.414859532811047, longitude: -60.00625459569375)
              
    // Next we compose the polygon
    return try ParsePolygon([geoPoint1, geoPoint2, geoPoint3, geoPoint4, geoPoint5])
  } catch let error as ParseError {
    print("Failed to instantiate vertices: \(error.message)")
    return nil
  } catch {
    print("Failed to instantiate vertices: \(error.localizedDescription)")
    return nil
  }
}()
      
guard let safePolygon = polygon else { return }
      
let query = City.query(withinPolygon(key: "location", polygon: safePolygon))
// withinPolygon(key:polygon:) returns the required constraint to apply on the query
      
let cities = try? query.find() // Executes the query synchronously
      
query.find { result in // Executes the query asynchronously and returns a result of type Result<[], ParseError>
  // Handle the result
}
﻿
Conclusion
Nowadays doing operations on location data to offer custom services is very important. Back4App together with the ParseSwift SDK makes it easy to implement those kinds of operations.
Updated 20 Mar 2024
Did this page help you?
Relational Queries
User Registration
Geoqueries

Geoqueries

Introduction

Prerequisites

Goal

1 - Quick review about the Query<U> class

2 - Save some data on Back4App

3 - Query the data

Conclusion
