Docs Menu

Docs Home → Develop Applications → MongoDB Drivers → Node.js

Search Geospatially

Overview

You can query data based on geographical location using geospatial query operators. Geospatial queries can be formatted using one of the following coordinate systems:

This section contains examples of geospatial queries using different query operators that you can run against your Atlas sample dataset.

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 movies collection using the createIndex() method:

db.movies.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 should contain 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.

Note

Spherical (2dsphere) and flat (2d) indexes support some, but not all, of the same query operators. For a full list of operators and their index compatibility, consult the manual entry for geospatial queries.

Examples

The following examples use the theaters collection of the sample_mflix sample database available in MongoDB Atlas, with a 2dsphere index on the location.geo field.

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 ].

  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:

  const query = {
    "location.geo": {
      $geoWithin: {
        $geometry: {
          type: "Polygon",
          coordinates: [
            [
              [-72, 40],
              [-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.

←  Specify Which Fields to ReturnSearch Text →