The content in this guide refers to the newly released version 3 of the library. You can still access the version 1.x guides here.

Version 1.x is now deprecated. We will continue to support 1.x through March 31, 2017 (End of Support - EOS). If you are currently using 1.x in your apps, you will need to upgrade your apps to 3.x before the EOS date. We have created a migration guide to help you.

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.

Kinvey supports location information through special location queries.

Storing Locations

For an entity to have an associated location, it needs a GeoPoint object parameter mapped.

For example, the code below adds a geolocation property to a class named Event.

class Event: Entity {

    dynamic var title: String?
    dynamic var geolocation: GeoPoint?
    dynamic var address: String?

    override class func collectionName() -> String {
        return "Event"

    override func propertyMapping(_ map: Map) {

        title <- ("title", map["title"])
        geolocation <- ("geolocation", map["geolocation"])
        address <- ("address", map["address"])


The GeoPoint class contains 2 properties: latitude and longitude. A GeoPoint can be instantiated from a CLLocationCoordinate2D -

let coordinate: CLLocationCoordinate2D = <#your CLLocationCoordinate2D#>
let geolocation = GeoPoint(coordinate: coordinate)

GeoPoint objects are translated to a json array when they are sent to the server. This array contains 2 values: longitude and latitude (in this order).

For example:

let event = Event()
event.title = "Meetup"
event.geolocation = GeoPoint(latitude: 42.3133521, longitude: -71.1271963)

will be written to your Event collection as:

Meetup[-71.1271963, 42.3133521]

To capture the location of the device, use Core Location.

if CLLocationManager.locationServicesEnabled() {
    let manager = CLLocationManager()
    //... set up CLLocationManager and start updates

    let currentLocation = manager.location
    if let coordinate = manager.location?.coordinate {
        Kinvey.sharedClient.activeUser?.geolocation = GeoPoint(coordinate: coordinate)


Query objects supports special geolocation queries using some MapKit objects

  • MKCircle: used for queries where you have a central point (center) and a distance limit (radius). Example: look for events near to me in a maximum distance of 20 kilometers.
let query = Query(format: "geolocation = %@", MKCircle(center: coordinate, radius: 7000)) //search for objects in a max distance of 7 kilometers
  • MKPolygon: used for queries where you have a shape of any form (polygon), triangle, square and so on. Example: look for events in downtown area.
let coordinates = [
    CLLocationCoordinate2D(latitude: 42.31363114297847, longitude: -71.12454163288896), //bottom left corner
    CLLocationCoordinate2D(latitude: 42.31359338001615, longitude: -71.11596352589291), //bottom right corner
    CLLocationCoordinate2D(latitude: 42.32375212671243, longitude: -71.11492645316849), //top right corner
    CLLocationCoordinate2D(latitude: 42.32182013184487, longitude: -71.13022491168071) //top left corner
let polygon = MKPolygon(coordinates: coordinates, count: coordinates.count)
let query = Query(format: "geolocation = %@", polygon) //search for objects inside the square defined by the points in the `coordinates` variable

The default unit used by Core Location is meter (metric system). Remember to convert your values if they are in miles.

Got a question?