Search Geospatially

Coordinates on an Earth-like Sphere

For geospatial queries using longitude and latitude coordinates on an Earth-like sphere, use the GeoJSON query format. While GeoJSON has multiple types, all GeoJSON data types use some form of the following structure:

<field> : {
   type: <GeoJSON type>,
   coordinates: [
      [longitude_1, latitude_1],
      ...
      [longitude_n, latitude_n]
   ]
}

The object type determines the number of coordinates. For instance, a Point requires only one coordinate: a longitude and a latitude. A Line uses two coordinates: a longitude and a latitude for each end. A Polygon consists of a list of coordinates in which the first and last coordinate are the same, effectively closing the polygon. To learn more about the GeoJSON shapes you can use in MongoDB, consult the GeoJSON manual entry.

To enable querying GeoJSON data, you must add the field to a 2dsphere index. The following snippet creates an index on the location.geo field in the theaters collection using the createIndex() method:

db.theaters.createIndex({location.geo: "2dsphere"});

Coordinates on a 2D Plane

You can also express geospatial queries using x and y coordinates in a two-dimensional Euclidean plane. Until MongoDB, this was the only format compatible with geospatial queries, and are now referred to as "legacy coordinate pairs".

Legacy coordinate pairs use the following structure:

<field> : [ x, y ]

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

To enable querying using legacy coordinate pairs, create a 2d index on the field on the collection. The following snippet creates an index on the coordinates field in the shipwrecks collection using the createIndex() method:

db.shipwrecks({coordinates: "2d"});

See the MongoDB Server manual page on legacy coordinate pairs for more information.

Query by Proximity

The $near operator accepts a set of longitude-latitude coordinates and returns documents ordered from nearest to farthest. To limit the results to a maximum distance in meters, use the $maxDistance option. For a complete list of options, see the reference documentation for $near. The following example queries for theaters within 10,000 meters of [ -73.9667, 40.78 ].

// Find theaters within a certain proximity
async function proximity(theaters) {
  // Define the query to find theaters near a specific location
  const query = {
    "location.geo": {
      $near: {
        $geometry: { type: "Point", coordinates: [-73.9667, 40.78] },
        $maxDistance: 10000,
      },
    },
  };
  // Find documents based on our query
  const cursor = theaters.find(query);

Query Within a Range

The $geoWithin operator selects documents with geospatial data that exist within a specified shape. The following example searches for movie theaters in the New England area:

// Find theaters within a specific geographic range
async function range(theaters) {
  // Define the query to find theaters within a specified polygon
  const query = {
    "location.geo": {
      $geoWithin: {
        $geometry: {
          type: "Polygon",
          coordinates: [
            [
              [-72, 40], // Polygon coordinates defining the range
              [-74, 41],
              [-72, 39],
              [-72, 40],
            ],
          ],
        },
      },
    },
  };
  // Find documents based on our query
  const cursor = theaters.find(query);

See the MongoDB Server manual page on geospatial query operators for more information on the operators you can use in your query.