Docs Menu

Docs HomeDevelop ApplicationsMongoDB DriversNode.js

Search Geospatially

On this page

  • Overview
  • Coordinates on an Earth-like Sphere
  • Coordinates on a 2D Plane
  • Examples
  • Query by Proximity
  • Query Within a Range

You can query data based on geographical location using geospatial query operators. You can format geospatial queries 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.

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"})

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.

The following examples use the MongoDB Atlas sample dataset. You can learn how to set up your own free-tier Atlas cluster and how to load the sample dataset in our quick start guide.

The examples use the theaters collection in the sample_mflix database from the sample dataset. The theaters collection contains a 2dsphere index on the location.geo field.

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);

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 →