> This page location: /docs.md > /docs/development.md > /docs/manual/crud.md > /docs/manual/tutorial/query-documents.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  other tabs: filter-bar, aggregation
-->

# Geospatial Queries

MongoDB supports query operations on geospatial data. This section introduces MongoDB geospatial features.

## Geospatial Data

In MongoDB, you can store geospatial data as GeoJSON objects or as legacy coordinate pairs.

### GeoJSON Objects

To calculate geometry over an Earth-like sphere, store your location data as [GeoJSON objects.](https://www.mongodb.com/docs/manual/reference/geojson.md#std-label-geospatial-indexes-store-geojson)

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.

```javascript
<field>: { type: <GeoJSON type> , coordinates: <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.

For example, to specify a [GeoJSON Point:](https://www.mongodb.com/docs/manual/reference/geojson.md#std-label-geojson-point)

```javascript
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.](https://www.mongodb.com/docs/manual/reference/geojson.md#std-label-geospatial-indexes-store-geojson)

MongoDB geospatial queries on GeoJSON objects calculate on a sphere; MongoDB uses the [WGS84](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-WGS84) reference system for geospatial queries on GeoJSON objects.

### Legacy Coordinate Pairs

Use legacy coordinate pairs for flat (Euclidean) calculations with a [2d Indexes](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2d.md#std-label-geo-2d) index. To perform spherical calculations, convert legacy pairs to a GeoJSON `Point` and use a [2dsphere Indexes](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-geo-2dsphere) index.

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

Array:

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

When you use longitude and latitude, list longitude first, then latitude:

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

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

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

Embedded document:

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

If you use longitude and latitude, the first field must be longitude and the second must be latitude:

```javascript
<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.

Use arrays for legacy coordinate pairs because some languages do not preserve object field ordering.

## Geospatial Indexes

Geospatial indexes support queries on data stored as [GeoJSON](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-geospatial-geojson) objects or [legacy coordinate pairs](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-geospatial-legacy). You can use geospatial indexes to improve performance for queries on geospatial data or to run certain geospatial queries.

MongoDB provides two types of geospatial indexes:

- [2dsphere Indexes](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-2dsphere-index), which support queries that interpret geometry on a sphere.

- [2d Indexes](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2d.md#std-label-2d-index), which support queries that interpret geometry on a flat surface.

For more information on geospatial indexes, see [Geospatial Indexes.](https://www.mongodb.com/docs/manual/core/indexes/index-types/index-geospatial.md#std-label-geospatial-index)

## Geospatial Queries

**Note:**

Using a `2d` index for queries on spherical data can return incorrect results or an error. For example, `2d` indexes don't support spherical queries that wrap around the poles.

If an indexed document contains both legacy coordinate fields and a GeoJSON object in the same `location` subdocument, MongoDB selects the indexed representation based on the server version:

- MongoDB earlier than 8.2 indexes the first supported representation according to field order. If the first two fields are numeric, MongoDB interprets them as a legacy `[longitude, latitude]` pair and ignores any GeoJSON fields that appear later.

- MongoDB 8.2 and later always indexes the GeoJSON representation when the subdocument contains any GeoJSON object, regardless of field order.

### Geospatial Query Operators

MongoDB provides the following geospatial query operators. For more details, including examples, see the respective reference pages.

| Name | Description |
| --- | --- |
| [`$geoIntersects`](https://www.mongodb.com/docs/manual/reference/operator/query/geointersects.md#mongodb-query-op.-geoIntersects) | Selects geometries that intersect with a [GeoJSON](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-GeoJSON) geometry. The [2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-2dsphere-index) index supports [`$geoIntersects`.](https://www.mongodb.com/docs/manual/reference/operator/query/geointersects.md#mongodb-query-op.-geoIntersects) |
| [`$geoWithin`](https://www.mongodb.com/docs/manual/reference/operator/query/geowithin.md#mongodb-query-op.-geoWithin) | Selects geometries within a bounding [GeoJSON geometry](https://www.mongodb.com/docs/manual/reference/geojson.md#std-label-geospatial-indexes-store-geojson). The [2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-2dsphere-index) and [2d](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2d.md#std-label-2d-index) indexes support [`$geoWithin`.](https://www.mongodb.com/docs/manual/reference/operator/query/geowithin.md#mongodb-query-op.-geoWithin) |
| [`$near`](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near) | Returns geospatial objects in proximity to a point. Requires a geospatial index. The `2dsphere` and `2d` indexes support [`$near`.](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near) |
| [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) | Returns geospatial objects in proximity to a point on a sphere. Requires a geospatial index. The `2dsphere` and `2d` indexes support [`$nearSphere`.](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) |

**Note:**

Time series collections only support the [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear) aggregation stage for sorting [geospatial data](https://www.mongodb.com/docs/manual/geospatial-queries.md) from queries against [2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-2dsphere-index) indexes. You can't use [`$near`](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near) and [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) operators on time series collections.

### Geospatial Aggregation Stage

MongoDB provides the following geospatial [aggregation pipeline stage:](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline)

| Stage | Description |
| --- | --- |
| [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear) | Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match), [`$sort`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort), and [`$limit`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit) for geospatial data. The output documents include an additional distance field and can include a location identifier field. [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear) requires a [geospatial index.](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-index-feature-geospatial) |

For more details, including examples, see [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear) reference page.

## Geospatial Models

MongoDB geospatial queries can interpret geometry on a flat surface or a sphere.

`2dsphere` indexes support only spherical queries (that is, queries that interpret geometries on a spherical surface).

`2d` indexes support flat queries (that is, queries that interpret geometries on a flat surface) and some spherical queries. While `2d` indexes support some spherical queries, the use of `2d` indexes for these spherical queries can result in error. If possible, use `2dsphere` indexes for spherical queries.

The following table lists the geospatial query operators, supported query, used by each geospatial operations:

| Operation | Spherical/Flat Query | Notes |
| --- | --- | --- |
| [`$near`](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near) ([GeoJSON](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-geospatial-geojson) centroid point in this line and the following line, [2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-geo-2dsphere) index) | Spherical | See also the [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) operator, which provides the same functionality when used with [GeoJSON](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-geospatial-geojson) and a [2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-geo-2dsphere) index. |
| [`$near`](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near) ([legacy coordinates](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-geospatial-legacy), [2d](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2d.md#std-label-geo-2d) index) | Flat | |
| [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) ([GeoJSON](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-geospatial-geojson) point, [2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-geo-2dsphere) index) | Spherical | Provides the same functionality as [`$near`](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near) operation that uses [GeoJSON](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-geospatial-geojson) point and a [2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-geo-2dsphere) index. For spherical queries, it may be preferable to use [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) which explicitly specifies the spherical queries in the name rather than [`$near`](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near) operator. |
| [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) ([legacy coordinates](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-geospatial-legacy), [2d](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2d.md#std-label-geo-2d) index) | Spherical | Use [GeoJSON](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-GeoJSON) points instead. |
| [`$geoWithin`](https://www.mongodb.com/docs/manual/reference/operator/query/geowithin.md#mongodb-query-op.-geoWithin) : { [`$geometry`](https://www.mongodb.com/docs/manual/reference/operator/query/geometry.md#mongodb-query-op.-geometry): ... } | Spherical | |
| [`$geoWithin`](https://www.mongodb.com/docs/manual/reference/operator/query/geowithin.md#mongodb-query-op.-geoWithin) : { [`$box`](https://www.mongodb.com/docs/manual/reference/operator/query/box.md#mongodb-query-op.-box): ... } | Flat | |
| [`$geoWithin`](https://www.mongodb.com/docs/manual/reference/operator/query/geowithin.md#mongodb-query-op.-geoWithin) : { [`$polygon`](https://www.mongodb.com/docs/manual/reference/operator/query/polygon.md#mongodb-query-op.-polygon): ... } | Flat | |
| [`$geoWithin`](https://www.mongodb.com/docs/manual/reference/operator/query/geowithin.md#mongodb-query-op.-geoWithin) : { [`$center`](https://www.mongodb.com/docs/manual/reference/operator/query/center.md#mongodb-query-op.-center): ... } | Flat | |
| [`$geoWithin`](https://www.mongodb.com/docs/manual/reference/operator/query/geowithin.md#mongodb-query-op.-geoWithin) : { [`$centerSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/centersphere.md#mongodb-query-op.-centerSphere): ... } | Spherical | |
| [`$geoIntersects`](https://www.mongodb.com/docs/manual/reference/operator/query/geointersects.md#mongodb-query-op.-geoIntersects) | Spherical | |
| [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear) aggregation stage ([2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-geo-2dsphere) index) | Spherical | |
| [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear) aggregation stage ([2d](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2d.md#std-label-geo-2d) index) | Flat | |

## Perform Geospatial Queries in Atlas

### Query Filter Bar

You can use the MongoDB Atlas UI to perform geospatial queries in Atlas.

1. Create an index

   If your geospatial collection does not already have a geospatial index, you must create one.

   1. Select the database for the collection.

      The main panel and Namespaces on the left side list the collections in the database.

   2. Select the collection.

      Select the collection that contains your geospatial data on the left-hand side or in the main panel. The main panel displays the Find, Indexes, and Aggregation views.

   3. Select the Index view.

      When you open the Index view, Atlas displays any indexes that exist on the collection.

   4. Define the Index for the geo Type

      Press the Create Index button.

      Define a geo Type index. Refer to [How to Index GeoJSON Objects.](https://www.mongodb.com/docs/manual/core/indexes/index-types/index-geospatial.md#std-label-geospatial-index)

2. Query the geospatial data

   1. Select the Find view.

      From the collection that contains your geospatial data, select the Find tab to view your geospatial collection.

   2. Enter a query.

      Enter a query in the Filter text box. Use any of the [geospatial query operators](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-geospatial-operators) to perform the relevant query on your geospatial data. A geospatial query might resemble:

      ```javascript
      {
        "coordinates": {
          $geoWithin: {
            $geometry: {
              type: "Polygon",
              coordinates: [
                [
                  [-80.0, 10.00], [ -80.0, 9.00], [ -79.0, 9.0], [ -79.0, 10.00 ], [ -80.0, 10.0 ]
                ]
              ]
            }
          }
        }
      }
      ```

   3. Press the Apply button.

      Press the Apply button to apply your query. Atlas filters the geospatial data to show only documents that match your geospatial query.

## Examples

The examples on this page use data from the [sample\_mflix dataset](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-sample-mflix). For details on how to load this dataset into your self-managed MongoDB deployment, see [Load the Sample Dataset](https://www.mongodb.com/docs/manual/sample-data/load-sample-data-local.md#std-label-sample-dataset-local). If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

The `sample_mflix.theaters` collection has a `2dsphere` index. The following query uses the [`$near`](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near) operator to return documents sorted from nearest to farthest. The query returns documents at least 1000 meters and at most 100000 meters from the specified GeoJSON point:

```javascript
db.theaters.find(
   {
      "location.geo": {
         $near: {
            $geometry: {
               type: "Point",
               coordinates: [ -73.9667, 40.78 ]
            },
            $minDistance: 1000,
            $maxDistance: 100000
         }
      }
   }
).limit(3)

```

**Output:**

```javascript
[
  {
    _id: ObjectId('59a47287cfa9a3a73e51eae8'),
    theaterId: 374,
    location: {
      address: {
        street1: '2478 Central Park Ave',
        city: 'Yonkers',
        state: 'NY',
        zipcode: '10710'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.826805, 40.983246 ]
      }
    }
  },
  {
    _id: ObjectId('59a47287cfa9a3a73e51ead6'),
    theaterId: 345,
    location: {
      address: {
        street1: '148 Walt Whitman Rd',
        city: 'Huntington Station',
        state: 'NY',
        zipcode: '11746'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.410637, 40.825775 ]
      }
    }
  },
  {
    _id: ObjectId('59a47287cfa9a3a73e51e92f'),
    theaterId: 200,
    location: {
      address: {
        street1: '3124 Jericho Tpke',
        city: 'East Northport',
        state: 'NY',
        zipcode: '11731'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.319092, 40.838463 ]
      }
    }
  }
]

```

The following operation uses the [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear) aggregation operation to return documents that match the query filter `{ "location.address.state": "NY" }`, sorted in order of nearest to farthest to the specified GeoJSON point:

```javascript
db.theaters.aggregate( [
   {
      $geoNear: {
         near: { type: "Point", coordinates: [ -73.9667, 40.78 ] },
         spherical: true,
         query: { "location.address.state": "NY" },
         distanceField: "calcDistance"
      }
   },
   { $limit: 3 }
] )

```

**Output:**

```javascript
[
  {
    _id: ObjectId('59a47287cfa9a3a73e51eae8'),
    theaterId: 374,
    location: {
      address: {
        street1: '2478 Central Park Ave',
        city: 'Yonkers',
        state: 'NY',
        zipcode: '10710'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.826805, 40.983246 ]
      }
    },
    calcDistance: 27000
  },
  {
    _id: ObjectId('59a47287cfa9a3a73e51ead6'),
    theaterId: 345,
    location: {
      address: {
        street1: '148 Walt Whitman Rd',
        city: 'Huntington Station',
        state: 'NY',
        zipcode: '11746'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.410637, 40.825775 ]
      }
    },
    calcDistance: 55000
  },
  {
    _id: ObjectId('59a47287cfa9a3a73e51e92f'),
    theaterId: 200,
    location: {
      address: {
        street1: '3124 Jericho Tpke',
        city: 'East Northport',
        state: 'NY',
        zipcode: '11731'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.319092, 40.838463 ]
      }
    },
    calcDistance: 72000
  }
]

```
