query-a-2dsphere-index.txt

.. _geospatial-indexes-query-2dsphere:

==========================
Query a ``2dsphere`` Index
==========================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

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

GeoJSON Objects Bounded by a Polygon
------------------------------------

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

.. code-block:: javascript

   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:

.. code-block:: javascript

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

Intersections of GeoJSON Objects
--------------------------------

.. versionadded:: 2.4

The :query:`$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 :query:`$geoIntersects` operator uses the following syntax:

.. code-block:: javascript

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

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

.. code-block:: javascript

   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
:query:`$near` operator or :dbcommand:`geoNear` command. Distance
is in meters.

The :query:`$near` uses the following syntax:

.. code-block:: javascript

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

For examples, see :query:`$near`.

The :dbcommand:`geoNear` command uses the following syntax:

.. code-block:: javascript

   db.runCommand( { geoNear : <collection> ,
                 near : { type : "Point" ,
                          coordinates: [ <longitude>, <latitude> ] } ,
                 spherical : true } )

The :dbcommand:`geoNear` command offers more options and returns more
information than does the :query:`$near` operator. To run the
command, see :dbcommand:`geoNear`.

Points within a Circle Defined on a Sphere
------------------------------------------

To select all grid coordinates in a "spherical cap" on a sphere, use
:query:`$geoWithin` with the :query:`$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
  :doc:`/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes`.

Use the following syntax:

.. code-block:: javascript

   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 radius of the earth, 3959 miles:

.. code-block:: javascript

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