Search Geospatially

On this page

Overview

Geospatial Data Formats
GeoJSON
Legacy Coordinate Pairs
Geospatial Indexes
Query Operators
Examples
Query by Proximity
Query by Polygon
Additional Resources

Overview

In this guide, you can learn how to work with geospatial data, data formats, indexes, and queries.

Geospatial data represents a geographic location on the surface of the Earth.

Examples of geospatial data include:

Locations of movie theaters
Borders of countries
Routes of bicycle rides
Dog exercise areas in New York City
Points on a graph

Geospatial Data Formats

All geospatial data in MongoDB is stored in one of the following formats:

GeoJSON, a format that represents geospatial data on an earth-like sphere.
Legacy coordinate pairs, a format that represents geospatial data on a Euclidean plane.

GeoJSON

Use GeoJSON to store data that represents geospatial information on an earth-like sphere. GeoJSON is composed of one or more positions and a type.

Positions

A position represents a single location and exists in code as an array containing the following values:

Longitude in the first position (required)
Latitude in the second position (required)
Elevation in the third position (optional)

The following is the position of the MongoDB Headquarters in New York City, NY.

GeoJson.Position(-73.986805, 40.7620853)

Alternatively, you can use the GeoJson.Geographic() method to construct a coordinate pair.

GeoJson.Geographic(-73.986805, 40.7620853)

Important

Longitude then Latitude

GeoJSON orders coordinates with longitude first and latitude second. Make sure to check what format any other tools you are working with use, since many popular tools such as OpenStreetMap and Google Maps list coordinates with latitude first and longitude second.

Types

The type of your GeoJSON object determines the geometric shape it represents. Geometric shapes are made up of positions.

Here are some common GeoJSON types and how you can specify them with positions:

Point: a single position. The following Point represents the location of the MongoDB Headquarters:
```
GeoJson.Point(GeoJson.Position(-73.986805, 40.7620853))
```
LineString: an array of two or more positions that forms a series of line segments. A LineString can represent a path, route, border, or any other linear geospatial data. The following LineString represents a segment of the Great Wall of China:
```
GeoJson.LineString
(
   GeoJson.Position(116.572, 40.430),
   GeoJson.Position(116.570, 40.434),
   GeoJson.Position(116.567, 40.436),
   GeoJson.Position(116.566, 40.441)
)
```

Polygon: an array of positions in which the first and last position are the same and enclose some space. The following Polygon roughly represents the land within the Vatican City:

GeoJson.Polygon
(
    GeoJson.Position(12.446086, 41.901977),
    GeoJson.Position(12.457952, 41.901559),
    GeoJson.Position(12.455375, 41.907351),
    GeoJson.Position(12.449863, 41.905186),
    GeoJson.Position(12.446086, 41.901977)
}

To learn more about the GeoJSON types you can use in MongoDB, see the GeoJSON manual entry.

For more information on the GeoJSON format, see the official IETF specification.

Legacy Coordinate Pairs

Use legacy coordinate pairs to store data that represents geospatial information on a two-dimensional plane.

Legacy coordinate pairs are represented by an array of two values, in which the first represents the x axis value and the second represents the y axis value.

For more information on legacy coordinate pairs, see the MongoDB server manual page on legacy coordinate pairs.

Geospatial Indexes

To enable querying on geospatial data, you must create an index that corresponds to the data format. The following index types enable geospatial queries:

2dsphere, used for GeoJSON data
2d, used for legacy coordinate pairs

To learn more about how to create geospatial indexes, see the Geospatial Indexes section of the Indexes guide.

Query Operators

To query geospatial data, use one of the following query operators:

$near
$geoWithin
$nearSphere
$geoIntersects (requires a 2dsphere index)

When using the $near operator, you can specify the following distance operators:

$minDistance
$maxDistance

When using the $geoWithin operator, you can specify the following shape operators:

$box
$polygon
$center
$centerSphere

For more information on geospatial query operators, see Geospatial Query Operators in the server manual.

Examples

The following examples uses the MongoDB Atlas sample dataset. To obtain this sample dataset, see Quick Start.

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.

Query by Proximity

The following example queries for documents with a location.geo field value within 1000 meters of the MongoDB Headquarters in New York City, NY. It returns documents from nearest to farthest.

// Point representation of the MongoDB Headquarters
var point = GeoJson.Point(GeoJson.Position(-73.986805, 40.7620853));
// Specifies a maxDistance of 1000 meters and a minDistance of 0 meters
var filter = Builders<Theater>.Filter.Near(m => m.Location.Geo, point, 1000.0, 0.0);
// Only fetches the _id and theaterId fields
var projection = Builders<Theater>.Projection.Include("theaterId");
var results = collection.Find(filter).Project(projection);

The results of the preceding example contain the following documents:

{ "_id" : ObjectId("59a47287cfa9a3a73e51e8e2"), "theaterId" : 1908 }
{ "_id" : ObjectId("59a47286cfa9a3a73e51e838"), "theaterId" : 1448 }

Query by Polygon

The following example queries for documents with a location.geo field value that exists within the boundaries of Manhattan.

// Polygon representation of Manhattan
var polygon = GeoJson.Polygon
(
   GeoJson.Position(-73.925492, 40.877410),
   GeoJson.Position(-73.910372, 40.872366),
   GeoJson.Position(-73.935127, 40.834020),
   GeoJson.Position(-73.929049, 40.798569),
   GeoJson.Position(-73.976485, 40.711432),
   GeoJson.Position(-74.015747, 40.701229),
   GeoJson.Position(-74.018859, 40.708367),
   GeoJson.Position(-74.008007, 40.754307),
   GeoJson.Position(-73.925492, 40.877410)
);
var filter = Builders<Theater>.Filter.GeoWithin(m => m.Location.Geo, polygon);
// Only fetches the _id and theaterId fields
var projection = Builders<Theater>.Projection.Include("theaterId");
var results = collection.Find(filter).Project(projection);