$nearSphere (geospatial)

APPLIES TO: MongoDB vCore

The $nearSphere operator returns documents with location fields near a specified point on a sphere, calculating distances using spherical geometry. This is more accurate for Earth-based calculations than $near.

Syntax

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

Parameters

Parameter Type Description
location field Field The field containing the GeoJSON Point
$geometry Object GeoJSON Point object specifying the center point
$maxDistance Number Optional. Maximum distance in meters on a spherical surface
$minDistance Number Optional. Minimum distance in meters on a spherical surface

Examples

Create the required '2dsphere' index:

db.stores.createIndex({ "location": "2dsphere" })

Find stores near "VanArsdel Picture Frame Store" (-141.9922, 16.8331):

db.stores.find({
  'location': {
    $nearSphere: {
      $geometry: {
        type: "Point",
        coordinates: [-141.9922, 16.8331]
      }
    }
  }
}, {
  name: 1,
  location: 1
})

Example 2: With Maximum Distance

Find stores within 20 KM of "Fabrikam Car Accessory Outlet" (-38.4071, -47.2548):

db.stores.find({
  'location': {
    $nearSphere: {
      $geometry: {
        type: "Point",
        coordinates: [-38.4071, -47.2548]
      },
      $maxDistance: 20000  // 20 KM in meters
    }
  }
}, {
  name: 1,
  location: 1
})

Example 3: Complex Distance Analysis

Find and analyze stores between 20 and 100 Kms from Fourth Coffee Turntable Boutique (65.3765, -44.8674):

db.stores.aggregate([
  {
    $geoNear: {
      near: {
        type: "Point",
        coordinates: [65.3765, -44.8674]
      },
      distanceField: "sphericalDistance",
      minDistance: 20000,     // 20 KM in meters
      maxDistance: 100000,    // 100 KM in meters
      spherical: true
    }
  },
  {
    $project: {
      name: 1,
      location: 1,
      distanceKm: { $divide: ["$sphericalDistance", 1000] },
      _id: 0
    }
  }
])

Key differences between $nearSphere and $near:

  • Uses spherical geometry for distance calculations
  • More accurate for Earth-based distances
  • Better for applications requiring precise global distance calculations

Related content