• Reference >
• Operators >
• Query and Projection Operators >
• Geospatial Query Operators >
• $nearSphere

$nearSphere

Definition

$nearSphere

Specifies a point for which a geospatial query returns the documents from nearest to farthest. MongoDB calculates distances for $nearSphere using spherical geometry.

$nearSphere requires a geospatial index:

• 2dsphere index for location data defined as GeoJSON points
• 2d index for location data defined as legacy coordinate pairs. To use a 2d index on GeoJSON points, create the index on the coordinates field of the GeoJSON object.

The $nearSphere operator can specify either a GeoJSON point or legacy coordinate point.

To specify a GeoJSON Point, use the following syntax:

copy

{
  $nearSphere: {
     $geometry: {
        type : "Point",
        coordinates : [ <longitude>, <latitude> ]
     },
     $minDistance: <distance in meters>,
     $maxDistance: <distance in meters>
  }
}

• The optional $minDistance is available only if the query uses the 2dsphere index. $minDistance limits the results to those documents that are at least the specified distance from the center point.

  New in version 2.6.

• The optional $maxDistance is available for either index.

To specify a point using legacy coordinates, use the following syntax:

copy

{
  $nearSphere: [ <x>, <y> ],
  $minDistance: <distance in radians>,
  $maxDistance: <distance in radians>
}

• The optional $minDistance is available only if the query uses the 2dsphere index. $minDistance limits the results to those documents that are at least the specified distance from the center point.

  New in version 2.6.

• The optional $maxDistance is available for either index.

If you use longitude and latitude for legacy coordinates, specify the longitude first, then latitude.

See also

2d Indexes and Geospatial Near Queries

Behavior

Special Indexes Restriction

You cannot combine the $nearSphere operator, which requires a special geospatial index, with a query operator or command that requires another special index. For example you cannot combine $nearSphere with the $text query.

Sharded Collections Restrictions

For sharded collections, queries using $nearSphere are not supported. You can instead use either the geoNear command or the $geoNear aggregation stage.

Sort Operation

$nearSphere sorts documents by distance. If you also include a sort() for the query, sort() re-orders the matching documents, effectively overriding the sort operation already performed by $nearSphere. When using sort() with geospatial queries, consider using $geoWithin operator, which does not sort documents, instead of $nearSphere.

Examples

Specify Center Point Using GeoJSON

Consider a collection places that contains documents with a location field and has a 2dsphere index.

Then, the following example returns whose location is at least 1000 meters from and at most 5000 meters from the specified point, ordered from nearest to farthest:

copy

db.places.find(
   {
     location: {
        $nearSphere: {
           $geometry: {
              type : "Point",
              coordinates : [ -73.9667, 40.78 ]
           },
           $minDistance: 1000,
           $maxDistance: 5000
        }
     }
   }
)

Specify Center Point Using Legacy Coordinates

2d Index

Consider a collection legacyPlaces that contains documents with legacy coordinates pairs in the location field and has a 2d index.

Then, the following example returns those documents whose location is at most 0.10 radians from the specified point, ordered from nearest to farthest:

copy

db.legacyPlaces.find(
   { location : { $nearSphere : [ -73.9667, 40.78 ], $maxDistance: 0.10 } }
)

2dsphere Index

If the collection has a 2dsphere index instead, you can also specify the optional $minDistance specification. For example, the following example returns the documents whose location is at least 0.0004 radians from the specified point, ordered from nearest to farthest:

copy

db.legacyPlaces.find(
   { location : { $nearSphere : [ -73.9667, 40.78 ], $minDistance: 0.0004 } }
)

←   $near $box  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.