Search Geospatially

On this page

Overview

Coordinates on Earth
GeoJSON Positions
GeoJSON Types
Index
Coordinates on a 2D Plane
Index
Geospatial Queries
Query Operators
Query Parameters
Geospatial Query Examples
Query by Proximity
Query Within a Range

Overview

In this guide, you can learn how to query geospatial data by using the Kotlin driver. You can also learn about different geospatial data formats supported by MongoDB.

Geospatial data is data that represents a geographical location on the surface of the Earth. Examples of geospatial data include:

Locations of movie theaters
Borders of countries
Routes of bicycle rides
Dog exercise areas in New York City

Coordinates on Earth

To store and query your geospatial data in MongoDB, use GeoJSON. GeoJSON is a data format created by the Internet Engineering Task Force (IETF).

Here is the location of MongoDB headquarters in GeoJSON:

"location" : {
   "type": "point",
   "coordinates": [-73.986805, 40.7620853]
}

For definitive information on GeoJSON, see the official IETF specification.

GeoJSON Positions

A position represents a single place on Earth and is given as an array containing two or three number values:

Longitude in the first position (required)
Latitude in the second position (required)
Elevation in the third position (optional)

Important

Longitude then Latitude

GeoJSON orders coordinates as longitude first and latitude second. This may be surprising as geographic coordinate system conventions generally list latitude first and longitude second. Make sure to check what format any other tools you are working with use. Popular tools such as OpenStreetMap and Google Maps list coordinates as latitude first and longitude second.

GeoJSON Types

Your GeoJSON object's type determines its geometric shape. Geometric shapes are made up of positions.

Here are some common GeoJSON types and how you can specify them with positions:

Point: Single position. This could represent the location of a sculpture.
LineString: Array of two or more positions, thus forming a series of line segments. This could represent the route of the Great Wall of China.
Polygon: Array of positions in which the first and last position are the same, enclosing some space. This could represent the land within Vatican City.

To learn more about the shapes you can use in MongoDB, see GeoJSON in the Server manual.

Index

To query data stored in the GeoJSON format, add the field containing GeoJSON data to a 2dsphere index. The following snippet creates a 2dsphere index on the location.geo field by using the Indexes builder:

collection.createIndex((Indexes.geo2dsphere("location.geo")))

To learn more about the Indexes builder, see the Indexes Builders guide.

Coordinates on a 2D Plane

You can store geospatial data using x and y coordinates on a two-dimensional Euclidean plane. We refer to coordinates on a two-dimensional plane as legacy coordinate pairs.

Legacy coordinate pairs have the following structure:

{ "location" : [ x, y ] }

The field value contains an array of two values in which the first represents the x axis value and the second represents the y axis value.

Index

To query data stored as legacy coordinate pairs, you must add the field containing legacy coordinate pairs to a 2d index. The following snippet creates a 2d index on the coordinates field by using the Indexes builder:

collection.createIndex((Indexes.geo2d("coordinates")))

To learn more about the Indexes builder, see the Indexes Builders guide.

For more information on legacy coordinate pairs, see the Legacy Coordinate Pairs section of the Geospatial Queries guide in the Server manual.

Tip

Supported Operators

Spherical (2dsphere) and flat (2d) indexes support some, but not all, of the same query operators. To view a full list of operators and their index compatibility, see the Geospatial Query Operators section of the Geospatial Queries guide in the Server manual.

Geospatial Queries

Geospatial queries consist of a query operator and GeoJSON shapes as query parameters.

Query Operators

To query your geospatial data, use one of the following query operators:

$near
$geoWithin
$nearSphere
$geoIntersects requires a 2dsphere index

You can specify these query operators in the MongoDB Kotlin driver with the near(), geoWithin(), nearSphere(), and geoIntersects() utility methods of the Filters builder class.

To learn more about geospatial query operators, see the Geospatial Query Operators section of the Geospatial Queries guide in the Server manual.

To learn more about the Filters builder, see the Filters Builders guide.

Query Parameters

To specify a shape to use in a geospatial query, use the Position, Point, LineString, and Polygon classes from the Kotlin driver.

To learn more about the GeoJSON shape classes, see the GeoJSON package API Documentation.

Geospatial Query Examples

The following examples use the MongoDB Atlas sample dataset. You can learn how to set up your own free-tier Atlas cluster and how to load the sample dataset in the Kotlin Driver Quick Start guide.

The examples use the theaters collection in the sample_mflix database from the sample dataset.

The examples in this section require the following imports:

import com.mongodb.client.model.geojson.Point
import com.mongodb.client.model.geojson.Polygon
import com.mongodb.client.model.geojson.Position
import com.mongodb.client.model.Filters.near
import com.mongodb.client.model.Filters.geoWithin
import com.mongodb.client.model.Projections.fields
import com.mongodb.client.model.Projections.include
import com.mongodb.client.model.Projections.excludeId

The sample documents are modeled by the following Kotlin data class:

data class Theater(
    val theaterId: Int,
    val location: Location
) {
    data class Location(
        val address: Address,
        val geo: Point
    ) {
        data class Address(
            val street1: String,
            val street2: String? = null,
            val city: String,
            val state: String,
            val zipcode: String
        )
    }
}

The result documents are modeled by the following Kotlin data class:

data class TheaterResults(
    val location: Location
) {
    data class Location(
        val address: Address
    ) {
        data class Address(
            val city: String
        )
    }
}

The theaters collection already contains a 2dsphere index on the "${Theater::location.name}.${Theater.Location::geo.name}" field.

Query by Proximity

To search for and return documents from nearest to farthest from a point, use the near() static utility method of the Filters builder class. The near() method constructs a query with the $near query operator.

The following example queries for movie theaters between 10000 and 5000 meters from the Great Lawn of Central Park:

val database = client.getDatabase("sample_mflix")
val collection = database.getCollection<TheaterResults>("theaters")
val centralPark = Point(Position(-73.9667, 40.78))
val query = Filters.near(
    "${Theater::location.name}.${Theater.Location::geo.name}", centralPark, 10000.0, 5000.0
)
val projection = Projections.fields(
    Projections.include(
        "${Theater::location.name}.${Theater.Location::address.name}.${Theater.Location.Address::city.name}"),
    Projections.excludeId()
)
val resultsFlow = collection.find(query).projection(projection)
resultsFlow.collect { println(it) }

TheaterResults(location=Location(address=Address(city=Bronx)))
TheaterResults(location=Location(address=Address(city=New York)))
TheaterResults(location=Location(address=Address(city=New York)))
TheaterResults(location=Location(address=Address(city=Long Island City)))
TheaterResults(location=Location(address=Address(city=New York)))
TheaterResults(location=Location(address=Address(city=Secaucus)))
TheaterResults(location=Location(address=Address(city=Jersey City)))
TheaterResults(location=Location(address=Address(city=Elmhurst)))
TheaterResults(location=Location(address=Address(city=Flushing)))
TheaterResults(location=Location(address=Address(city=Flushing)))
TheaterResults(location=Location(address=Address(city=Flushing)))
TheaterResults(location=Location(address=Address(city=Elmhurst)))

Tip

MongoDB uses the same reference system as GPS satellites to calculate geometries over the Earth.

To learn more about the $near operator, see the $near reference in the Server manual.

Query Within a Range

To search for geospatial data within a specified shape use the geoWithin() static utility method of the Filters builder class. The geoWithin() method constructs a query with the $geoWithin query operator.

The following example searches for movie theaters in a section of Long Island.

val longIslandTriangle = Polygon(
    listOf(
        Position(-72.0, 40.0),
        Position(-74.0, 41.0),
        Position(-72.0, 39.0),
        Position(-72.0, 40.0)
    )
)
val projection = Projections.fields(
    Projections.include(
        "${Theater::location.name}.${Theater.Location::address.name}.${Theater.Location.Address::city.name}"),
    Projections.excludeId()
)
val geoWithinComparison = Filters.geoWithin(
    "${Theater::location.name}.${Theater.Location::geo.name}", longIslandTriangle
)
val resultsFlow = collection.find<TheaterResults>(geoWithinComparison)
    .projection(projection)
resultsFlow.collect { println(it) }

TheaterResults(location=Location(address=Address(city=Baldwin))))
TheaterResults(location=Location(address=Address(city=Levittown)))
TheaterResults(location=Location(address=Address(city=Westbury)))
TheaterResults(location=Location(address=Address(city=Mount Vernon)))
TheaterResults(location=Location(address=Address(city=Massapequa)))

The following figure shows the polygon defined by the longIslandTriangle variable and dots representing the locations of the movie theaters returned by our query.

Area of Long Island in which to search for movie theaters

To learn more about the $geoWithin operator, see the $geoWithin reference in the Server manual.

Back

Specify Which Fields to Return

Search Text