Geospatial Queries

GeoJSON Objects

To calculate geometry over an Earth-like sphere, store your location data as GeoJSON objects.

To specify GeoJSON data, use an embedded document with:

• a field named type that specifies the GeoJSON object type and

• a field named coordinates that specifies the object's coordinates.

  Important

  If specifying latitude and longitude coordinates, list the longitude first, and then latitude.

  • Valid longitude values are between -180 and 180, both inclusive.

  • Valid latitude values are between -90 and 90, both inclusive.

<field>: { type: <GeoJSON type> , coordinates: <coordinates> }

For example, to specify a GeoJSON Point:

location: {
      type: "Point",
      coordinates: [-73.856077, 40.848447]
}

For a list of the GeoJSON objects supported in MongoDB as well as examples, see GeoJSON objects.

MongoDB geospatial queries on GeoJSON objects calculate on a sphere; MongoDB uses the WGS84 reference system for geospatial queries on GeoJSON objects.

Legacy Coordinate Pairs

To calculate distances on a Euclidean plane, store your location data as legacy coordinate pairs and use a 2d index. MongoDB supports spherical surface calculations on legacy coordinate pairs by using a 2dsphere index if you manually convert the data to the GeoJSON Point type.

To specify data as legacy coordinate pairs, you can use either an array (preferred) or an embedded document.

Specify via an array (Preferred):

<field>: [ <x>, <y> ]

If specifying latitude and longitude coordinates, list the longitude first and then latitude; i.e.

<field>: [<longitude>, <latitude> ]

• Valid longitude values are between -180 and 180, both inclusive.

• Valid latitude values are between -90 and 90, both inclusive.

Specify via an embedded document:

<field>: { <field1>: <x>, <field2>: <y> }

If specifying latitude and longitude coordinates, the first field, regardless of the field name, must contain the longitude value and the second field, the latitude value ; i.e.

<field>: { <field1>: <longitude>, <field2>: <latitude> }

• Valid longitude values are between -180 and 180, both inclusive.

• Valid latitude values are between -90 and 90, both inclusive.

To specify legacy coordinate pairs, arrays are preferred over an embedded document as some languages do not guarantee associative map ordering.

2dsphere

2dsphere indexes support queries that calculate geometries on an earth-like sphere.

To create a 2dsphere index, use the db.collection.createIndex() method and specify the string literal "2dsphere" as the index type:

db.collection.createIndex( { <location field> : "2dsphere" } )

where the <location field> is a field whose value is either a GeoJSON object or a legacy coordinates pair.

For more information on the 2dsphere index, see 2dsphere Indexes.

2d

2d indexes support queries that calculate geometries on a two-dimensional plane. Although the index can support $nearSphere queries that calculate on a sphere, if possible, use the 2dsphere index for spherical queries.

To create a 2d index, use the db.collection.createIndex() method, specifying the location field as the key and the string literal "2d" as the index type:

db.collection.createIndex( { <location field> : "2d" } )

where the <location field> is a field whose value is a legacy coordinates pair.

For more information on the 2d index, see 2d Indexes.

Geospatial Indexes and Sharded Collections

You cannot use a geospatial index as a shard key when sharding a collection. However, you can create a geospatial index on a sharded collection by using a different field as the shard key.

The following geospatial operations are supported on sharded collections:

• $geoNear aggregation stage

• $near and $nearSphere query operators (starting in MongoDB 4.0)

Starting in MongoDB 4.0, $near and $nearSphere queries are supported for sharded collections.

In earlier MongoDB versions, $near and $nearSphere queries are not supported for sharded collections; instead, for sharded clusters, you must use the $geoNear aggregation stage or the geoNear command (available in MongoDB 4.0 and earlier).

You can also query for geospatial data for a sharded cluster using $geoWithin and $geoIntersects.

Covered Queries

Geospatial indexes cannot cover a query.

Geospatial Query Operators

MongoDB provides the following geospatial query operators:

For more details, including examples, see the individual reference page.

Geospatial Aggregation Stage

MongoDB provides the following geospatial aggregation pipeline stage:

For more details, including examples, see $geoNear reference page.