Docs Home → Develop Applications → MongoDB Manual

Query a `2dsphere` Index

On this page

GeoJSON Objects Bounded by a Polygon

Intersections of GeoJSON Objects
Proximity to a GeoJSON Point
Points within a Circle Defined on a Sphere

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB server.

The following sections describe queries supported by the 2dsphere index.

GeoJSON Objects Bounded by a Polygon

The $geoWithin operator queries for location data found within a GeoJSON polygon. Your location data must be stored in GeoJSON format. Use the following syntax:

db.<collection>.find( { <location field> :
                         { $geoWithin :
                           { $geometry :
                             { type : "Polygon" ,
                               coordinates : [ <coordinates> ]
                      } } } } )

The following example selects all points and shapes that exist entirely within a GeoJSON polygon:

db.places.find( { loc :
                  { $geoWithin :
                    { $geometry :
                      { type : "Polygon" ,
                        coordinates : [ [
                                          [ 0 , 0 ] ,
                                          [ 3 , 6 ] ,
                                          [ 6 , 1 ] ,
                                          [ 0 , 0 ]
                                        ] ]
                } } } } )

Intersections of GeoJSON Objects

The $geoIntersects operator queries for locations that intersect a specified GeoJSON object. A location intersects the object if the intersection is non-empty. This includes documents that have a shared edge.

The $geoIntersects operator uses the following syntax:

db.<collection>.find( { <location field> :
                         { $geoIntersects :
                           { $geometry :
                             { type : "<GeoJSON object type>" ,
                               coordinates : [ <coordinates> ]
                      } } } } )

The following example uses $geoIntersects to select all indexed points and shapes that intersect with the polygon defined by the coordinates array.

db.places.find( { loc :
                  { $geoIntersects :
                    { $geometry :
                      { type : "Polygon" ,
                        coordinates: [ [
                                         [ 0 , 0 ] ,
                                         [ 3 , 6 ] ,
                                         [ 6 , 1 ] ,
                                         [ 0 , 0 ]
                                       ] ]
                } } } } )

Proximity to a GeoJSON Point

Proximity queries return the points closest to the defined point and sorts the results by distance. A proximity query on GeoJSON data requires a 2dsphere index.

To query for proximity to a GeoJSON point, use either the $near operator. Distance is in meters.

The $near uses the following syntax:

db.<collection>.find( { <location field> :
                         { $near :
                           { $geometry :
                              { type : "Point" ,
                                coordinates : [ <longitude> , <latitude> ] } ,
                             $maxDistance : <distance in meters>
                      } } } )

For examples, see $near.

See also the $nearSphere operator and the $geoNear aggregation pipeline stage.

Points within a Circle Defined on a Sphere

To select all grid coordinates in a "spherical cap" on a sphere, use $geoWithin with the $centerSphere operator. Specify an array that contains:

The grid coordinates of the circle's center point
The circle's radius measured in radians. To calculate radians, see Calculate Distance Using Spherical Geometry.

Use the following syntax:

db.<collection>.find( { <location field> :
                         { $geoWithin :
                           { $centerSphere :
                              [ [ <x>, <y> ] , <radius> ] }
                      } } )

The following example queries grid coordinates and returns all documents within a 10 mile radius of longitude 88 W and latitude 30 N. The example converts the distance, 10 miles, to radians by dividing by the approximate equatorial radius of the earth, 3963.2 miles:

db.places.find( { loc :
                  { $geoWithin :
                    { $centerSphere :
                       [ [ -88 , 30 ] , 10 / 3963.2 ]
                } } } )

← 2dsphere Indexes 2d Indexes →