# Geospatial
This section provides detailed information about geospatial operators supported by Amazon DocumentDB.
**Topics**
+ [\$1geometry](geometry.md)
+ [\$1geoIntersects](geoIntersects.md)
+ [\$1geoWithin](geoWithin.md)
+ [\$1maxDistance](maxDistance.md)
+ [\$1minDistance](minDistance.md)
+ [\$1near](near.md)
+ [\$1nearSphere](nearSphere.md)
# \$1geometry
The `$geometry` operator in Amazon DocumentDB is used to specify a GeoJSON geometry object as part of a geospatial query. This operator is used in conjunction with other geospatial query operators like `$geoWithin` and `$geoIntersects` to perform spatial queries on your data.
In Amazon DocumentDB, the `$geometry` operator supports the following GeoJSON geometry types:
+ Point
+ LineString
+ Polygon
+ MultiPoint
+ MultiLineString
+ MultiPolygon
+ GeometryCollection
**Parameters**
+ `type`: The type of the GeoJSON geometry object, e.g., `Point`, `Polygon`, etc.
+ `coordinates`: An array of coordinates representing the geometry. The structure of the coordinates array depends on the geometry type.
## Example (MongoDB Shell)
The following example demonstrates how to use the `$geometry` operator to perform a `$geoIntersects` query in Amazon DocumentDB.
**Create sample documents**
```
db.locations.insertMany([
{
"_id": 1,
"name": "Location 1",
"location": {
"type": "Point",
"coordinates": [-73.983253, 40.753941]
}
},
{
"_id": 2,
"name": "Location 2",
"location": {
"type": "Polygon",
"coordinates": [[
[-73.998427, 40.730309],
[-73.954348, 40.730309],
[-73.954348, 40.780816],
[-73.998427, 40.780816],
[-73.998427, 40.730309]
]]
}
}
]);
```
**Query example**
```
db.locations.find({
"location": {
"$geoIntersects": {
"$geometry": {
"type": "Polygon",
"coordinates": [[
[-73.998, 40.730],
[-73.954, 40.730],
[-73.954, 40.781],
[-73.998, 40.781],
[-73.998, 40.730]
]]
}
}
}
})
```
**Output**
```
[
{
"_id": 2,
"name": "Location 2",
"location": {
"type": "Polygon",
"coordinates": [
[
[-73.998427, 40.730309],
[-73.954348, 40.730309],
[-73.954348, 40.780816],
[-73.998427, 40.780816],
[-73.998427, 40.730309]
]
]
}
}
]
```
## Code examples
To view a code example for using the `$geometry` command, choose the tab for the language that you want to use:
------
#### [ Node.js ]
```
const { MongoClient } = require('mongodb');
async function example() {
const client = await MongoClient.connect('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
const db = client.db('test');
const collection = db.collection('locations');
const query = {
"location": {
"$geoIntersects": {
"$geometry": {
"type": "Polygon",
"coordinates": [[
[-73.998, 40.730],
[-73.954, 40.730],
[-73.954, 40.781],
[-73.998, 40.781],
[-73.998, 40.730]
]]
}
}
}
};
const result = await collection.find(query).toArray();
console.log(result);
await client.close();
}
example();
```
------
#### [ Python ]
```
from pymongo import MongoClient
def example():
client = MongoClient('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
db = client['test']
collection = db['locations']
query = {
"location": {
"$geoIntersects": {
"$geometry": {
"type": "Polygon",
"coordinates": [[
[-73.998, 40.730],
[-73.954, 40.730],
[-73.954, 40.781],
[-73.998, 40.781],
[-73.998, 40.730]
]]
}
}
}
}
result = list(collection.find(query))
print(result)
client.close()
example()
```
------
# \$1geoIntersects
The `$geoIntersects` operator in Amazon DocumentDB is used to find documents whose geospatial data intersects with a specified GeoJSON object. This operator is useful for applications that require identifying documents based on their spatial relationship with a given geographic shape, such as a polygon or multipolygon.
**Parameters**
+ `$geometry`: A GeoJSON object that represents the shape to check for intersection. The supported GeoJSON object types are `Point`, `LineString`, `Polygon`, and `MultiPolygon`.
## Example (MongoDB Shell)
The following example demonstrates how to use the `$geoIntersects` operator to find the state name for a given set of coordinates in Amazon DocumentDB.
**Create sample documents**
```
db.states.insertMany([
{
"name": "New York",
"loc": {
"type": "Polygon",
"coordinates": [[
[-74.25909423828125, 40.47556838210948],
[-73.70819091796875, 40.47556838210948],
[-73.70819091796875, 41.31342607582222],
[-74.25909423828125, 41.31342607582222],
[-74.25909423828125, 40.47556838210948]
]]
}
},
{
"name": "California",
"loc": {
"type": "Polygon",
"coordinates": [[
[-124.4091796875, 32.56456771381587],
[-114.5458984375, 32.56456771381587],
[-114.5458984375, 42.00964153424558],
[-124.4091796875, 42.00964153424558],
[-124.4091796875, 32.56456771381587]
]]
}
}
]);
```
**Query example**
```
var location = [-73.965355, 40.782865];
db.states.find({
"loc": {
"$geoIntersects": {
"$geometry": {
"type": "Point",
"coordinates": location
}
}
}
}, {
"name": 1
});
```
**Output**
```
{ "_id" : ObjectId("536b0a143004b15885c91a2c"), "name" : "New York" }
```
## Code examples
To view a code example for using the `$geoIntersects` command, choose the tab for the language that you want to use:
------
#### [ Node.js ]
```
const { MongoClient } = require('mongodb');
async function findStateByGeoIntersects(longitude, latitude) {
const client = await MongoClient.connect('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
const db = client.db('test');
const collection = db.collection('states');
const query = {
loc: {
$geoIntersects: {
$geometry: {
type: 'Point',
coordinates: [longitude, latitude]
}
}
}
};
const projection = {
_id: 0,
name: 1
};
const document = await collection.findOne(query, { projection });
await client.close();
if (document) {
return document.name;
} else {
throw new Error('The geo location you entered was not found in the United States!');
}
}
```
------
#### [ Python ]
```
from pymongo import MongoClient
def find_state_by_geointersects(longitude, latitude):
try:
client = MongoClient('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
db = client.test
collection_states = db.states
query_geointersects = {
"loc": {
"$geoIntersects": {
"$geometry": {
"type": "Point",
"coordinates": [longitude, latitude]
}
}
}
}
document = collection_states.find_one(query_geointersects,
projection={
"_id": 0,
"name": 1
})
if document is not None:
state_name = document['name']
return state_name
else:
raise Exception("The geo location you entered was not found in the United States!")
except Exception as e:
print('Exception in geoIntersects: {}'.format(e))
raise
finally:
if client is not None:
client.close()
```
------
# \$1geoWithin
The `$geoWithin` operator in Amazon DocumentDB is used to find documents whose location data (represented as GeoJSON objects) are completely contained within a specified shape, such as a polygon or multipolygon. This is useful for querying for objects that are located within a specific geographic region.
**Parameters**
+ `$geometry`: A GeoJSON object that represents the shape to query against.
## Example (MongoDB Shell)
The following example demonstrates how to use the `$geoWithin` operator to find all airports located within the state of New York.
**Create sample documents**
```
// Insert state document
db.states.insert({
"name": "New York",
"loc": {
"type": "Polygon",
"coordinates": [[
[-79.76278, 45.0],
[-73.94, 45.0],
[-73.94, 40.5],
[-79.76278, 40.5],
[-79.76278, 45.0]
]]
}
});
// Insert airport documents
db.airports.insert([
{
"name": "John F. Kennedy International Airport",
"type": "airport",
"code": "JFK",
"loc": {
"type": "Point",
"coordinates": [-73.7781, 40.6413]
}
},
{
"name": "LaGuardia Airport",
"type": "airport",
"code": "LGA",
"loc": {
"type": "Point",
"coordinates": [-73.8772, 40.7769]
}
},
{
"name": "Buffalo Niagara International Airport",
"type": "airport",
"code": "BUF",
"loc": {
"type": "Point",
"coordinates": [-78.7322, 42.9403]
}
}
]);
```
**Query example**
```
var state = db.states.findOne({"name": "New York"});
db.airports.find({
"loc": {
"$geoWithin": {
"$geometry": state.loc
}
}
}, {
"name": 1,
"type": 1,
"code": 1,
"_id": 0
});
```
**Output**
```
[
{
"name": "John F. Kennedy International Airport",
"type": "airport",
"code": "JFK"
},
{
"name": "LaGuardia Airport",
"type": "airport",
"code": "LGA"
}
]
```
## Code examples
To view a code example for using the `$geoWithin` command, choose the tab for the language that you want to use:
------
#### [ Node.js ]
```
const { MongoClient } = require('mongodb');
async function findAirportsWithinState(stateName) {
const client = await MongoClient.connect('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
const db = client.db('test');
const stateDoc = await db.collection('states').findOne({ name: stateName }, { projection: { _id: 0, loc: 1 } });
const airportDocs = await db.collection('airports').find({
loc: {
$geoWithin: {
$geometry: stateDoc.loc
}
}
}, { projection: { name: 1, type: 1, code: 1, _id: 0 } }).toArray();
console.log(airportDocs);
await client.close();
}
findAirportsWithinState('New York');
```
------
#### [ Python ]
```
from pymongo import MongoClient
def find_airports_within_state(state_name):
try:
client = MongoClient('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
db = client['test']
state_doc = db.states.find_one({'name': state_name}, {'_id': 0, 'loc': 1})
airport_docs = db.airports.find({
'loc': {
'$geoWithin': {
'$geometry': state_doc['loc']
}
}
}, {'name': 1, 'type': 1, 'code': 1, '_id': 0})
return list(airport_docs)
except Exception as e:
print(f'Error: {e}')
finally:
client.close()
airports = find_airports_within_state('New York')
print(airports)
```
------
# \$1maxDistance
The `$maxDistance` operator in Amazon DocumentDB is used to specify the maximum distance (in meters) from a GeoJSON point that documents must be within to be included in the query results. This operator is used in conjunction with the `$nearSphere` operator to perform geospatial queries.
**Parameters**
+ `$maxDistance`: The maximum distance (in meters) from the reference point that documents must be within to be included in the query results.
## Example (MongoDB Shell)
The following example demonstrates how to use the `$maxDistance` operator in Amazon DocumentDB to find all state capitals within 100 kilometers of Boston.
**Create sample documents**
```
db.capitals.insert([
{ state: "Massachusetts", city: "Boston", location: { type: "Point", coordinates: [-71.0589, 42.3601] } },
{ state: "Rhode Island", city: "Providence", location: { type: "Point", coordinates: [-71.4128, 41.8239] } },
{ state: "New Hampshire", city: "Concord", location: { type: "Point", coordinates: [-71.5383, 43.2067] } },
{ state: "Vermont", city: "Montpelier", location: { type: "Point", coordinates: [-72.5751, 44.2604] } }
]);
```
**Query example**
```
db.capitals.find(
{
location: {
$nearSphere: {
$geometry: { type: "Point", coordinates: [-71.0589, 42.3601] },
$maxDistance: 100000
}
}
},
{ state: 1, city: 1, _id: 0 }
);
```
**Output**
```
[
{ "state": "Rhode Island", "city": "Providence" },
{ "state": "New Hampshire", "city": "Concord" }
]
```
## Code examples
To view a code example for using the `$maxDistance` command, choose the tab for the language that you want to use:
------
#### [ Node.js ]
```
const { MongoClient } = require('mongodb');
async function findCapitalsNearBoston() {
const client = await MongoClient.connect('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
const db = client.db('test');
const capitals = db.collection('capitals');
const result = await capitals.find({
location: {
$nearSphere: {
$geometry: { type: "Point", coordinates: [-71.0589, 42.3601] },
$maxDistance: 100000
}
}
}, {
projection: { state: 1, city: 1, _id: 0 }
}).toArray();
console.log(result);
await client.close();
}
findCapitalsNearBoston();
```
------
#### [ Python ]
```
from pymongo import MongoClient
def find_capitals_near_boston():
client = MongoClient('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
db = client.test
capitals = db.capitals
result = list(capitals.find(
{
"location": {
"$nearSphere": {
"$geometry": { "type": "Point", "coordinates": [-71.0589, 42.3601] },
"$maxDistance": 100000
}
}
},
{"state": 1, "city": 1, "_id": 0}
))
print(result)
client.close()
find_capitals_near_boston()
```
------
# \$1minDistance
`$minDistance` is a find operator used in conjunction with `$nearSphere` or `$geoNear` to filter documents that are at least at the specified minimum distance from the center point. This operator is supported in Amazon DocumentDB and functions similarly to its counterpart in MongoDB.
**Parameters**
+ `$minDistance`: The minimum distance (in meters) from the center point to include documents in the results.
## Example (MongoDB Shell)
In this example, we'll find all restaurants within a 2-kilometer radius of a specific location in Seattle, Washington.
**Create sample documents**
```
db.usarestaurants.insertMany([
{
"state": "Washington",
"city": "Seattle",
"name": "Noodle House",
"rating": 4.8,
"location": {
"type": "Point",
"coordinates": [-122.3517, 47.6159]
}
},
{
"state": "Washington",
"city": "Seattle",
"name": "Pike Place Grill",
"rating": 4.5,
"location": {
"type": "Point",
"coordinates": [-122.3412, 47.6102]
}
},
{
"state": "Washington",
"city": "Bellevue",
"name": "The Burger Joint",
"rating": 4.2,
"location": {
"type": "Point",
"coordinates": [-122.2007, 47.6105]
}
}
]);
```
**Query example**
```
db.usarestaurants.find({
"location": {
"$nearSphere": {
"$geometry": {
"type": "Point",
"coordinates": [-122.3516, 47.6156]
},
"$minDistance": 1,
"$maxDistance": 2000
}
}
}, {
"name": 1
});
```
**Output**
```
{ "_id" : ObjectId("611f3da985009a81ad38e74b"), "name" : "Noodle House" }
{ "_id" : ObjectId("611f3da985009a81ad38e74c"), "name" : "Pike Place Grill" }
```
## Code examples
To view a code example for using the `$minDistance` command, choose the tab for the language that you want to use:
------
#### [ Node.js ]
```
const { MongoClient } = require('mongodb');
async function findRestaurantsNearby() {
const client = await MongoClient.connect('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
const db = client.db('test');
const collection = db.collection('usarestaurants');
const result = await collection.find({
"location": {
"$nearSphere": {
"$geometry": {
"type": "Point",
"coordinates": [-122.3516, 47.6156]
},
"$minDistance": 1,
"$maxDistance": 2000
}
}
}, {
"projection": { "name": 1 }
}).toArray();
console.log(result);
client.close();
}
findRestaurantsNearby();
```
------
#### [ Python ]
```
from pymongo import MongoClient
def find_restaurants_nearby():
client = MongoClient('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
db = client.test
collection = db.usarestaurants
result = list(collection.find({
"location": {
"$nearSphere": {
"$geometry": {
"type": "Point",
"coordinates": [-122.3516, 47.6156]
},
"$minDistance": 1,
"$maxDistance": 2000
}
}
}, {
"projection": {"name": 1}
}))
print(result)
client.close()
find_restaurants_nearby()
```
------
# \$1near
The `$near` operator in Amazon DocumentDB is used to find documents that are geographically near a specified point. It returns documents ordered by distance, with the closest documents first. This operator requires a 2dsphere geospatial index and is useful for proximity queries on location data.
**Parameters**
+ `$geometry`: A GeoJSON Point object that defines the center point for the near query.
+ `$maxDistance`: (optional) The maximum distance in meters from the specified point that a document can be to match the query.
+ `$minDistance`: (optional) The minimum distance in meters from the specified point that a document can be to match the query.
**Index Requirements**
+ `2dsphere index`: Required for geospatial queries on GeoJSON Point data.
## Example (MongoDB Shell)
The following example demonstrates how to use the `$near` operator to find the nearest restaurants to a specific location in Seattle, Washington.
**Create sample documents**
```
db.usarestaurants.insert([
{
"name": "Noodle House",
"city": "Seattle",
"state": "Washington",
"rating": 4.8,
"location": { "type": "Point", "coordinates": [-122.3517, 47.6159] }
},
{
"name": "Pike Place Grill",
"city": "Seattle",
"state": "Washington",
"rating": 4.2,
"location": { "type": "Point", "coordinates": [-122.3403, 47.6062] }
},
{
"name": "Lola",
"city": "Seattle",
"state": "Washington",
"rating": 4.5,
"location": { "type": "Point", "coordinates": [-122.3407, 47.6107] }
}
]);
```
**Create 2dsphere index**
```
db.usarestaurants.createIndex({ "location": "2dsphere" });
```
**Query example with GeoJSON Point**
```
db.usarestaurants.find({
location: {
$near: {
$geometry: {
type: "Point",
coordinates: [-122.3516, 47.6156]
},
$maxDistance: 100,
$minDistance: 10
}
}
});
```
**Output**
```
{
"_id" : ObjectId("69031ec9ea1c2922a1ce5f4a"),
"name" : "Noodle House",
"city" : "Seattle",
"state" : "Washington",
"rating" : 4.8,
"location" : {
"type" : "Point",
"coordinates" : [ -122.3517, 47.6159 ]
}
}
```
## Code examples
To view a code example for using the `$near` command, choose the tab for the language that you want to use:
------
#### [ Node.js ]
```
const { MongoClient } = require('mongodb');
async function findNearbyRestaurants() {
const client = await MongoClient.connect('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
const db = client.db('test');
const restaurants = db.collection('usarestaurants');
// Create 2dsphere index
await restaurants.createIndex({ "location": "2dsphere" });
const result = await restaurants.find({
location: {
$near: {
$geometry: {
type: "Point",
coordinates: [-122.3516, 47.6156]
},
$maxDistance: 100,
$minDistance: 10
}
}
}).toArray();
console.log(result);
client.close();
}
findNearbyRestaurants();
```
------
#### [ Python ]
```
from pymongo import MongoClient
def find_nearby_restaurants():
client = MongoClient('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
db = client['test']
restaurants = db['usarestaurants']
# Create 2dsphere index
restaurants.create_index([("location", "2dsphere")])
result = list(restaurants.find({
'location': {
'$near': {
'$geometry': {
'type': 'Point',
'coordinates': [-122.3516, 47.6156]
},
'$maxDistance': 100,
'$minDistance': 10
}
}
}))
print(result)
client.close()
find_nearby_restaurants()
```
------
# \$1nearSphere
The `$nearSphere` operator in Amazon DocumentDB is used to find documents that are within a specified distance of a geospatial point. This operator is particularly useful for geo-spatial queries, such as finding all restaurants within a certain radius of a given location.
**Parameters**
+ `$geometry`: A GeoJSON object that represents the reference point. Must be a `Point` object with `type` and `coordinates` fields.
+ `$minDistance`: (optional) The minimum distance (in meters) from the reference point that documents must be.
+ `$maxDistance`: (optional) The maximum distance (in meters) from the reference point that documents must be.
## Example (MongoDB Shell)
In this example, we will find all restaurants within 2 kilometers (2000 meters) of a specific location in Seattle, WA.
**Create sample documents**
```
db.usarestaurants.insert([
{
name: "Noodle House",
location: { type: "Point", coordinates: [-122.3516, 47.6156] }
},
{
name: "Pike Place Grill",
location: { type: "Point", coordinates: [-122.3403, 47.6101] }
},
{
name: "Seattle Coffee Co.",
location: { type: "Point", coordinates: [-122.3339, 47.6062] }
}
]);
```
**Query example**
```
db.usarestaurants.find({
location: {
$nearSphere: {
$geometry: {
type: "Point",
coordinates: [-122.3516, 47.6156]
},
$minDistance: 1,
$maxDistance: 2000
}
}
}, {
name: 1
});
```
**Output**
```
{ "_id" : ObjectId("611f3da985009a81ad38e74b"), "name" : "Noodle House" }
{ "_id" : ObjectId("611f3da985009a81ad38e74c"), "name" : "Pike Place Grill" }
```
## Code examples
To view a code example for using the `$nearSphere` command, choose the tab for the language that you want to use:
------
#### [ Node.js ]
```
const { MongoClient } = require('mongodb');
async function findNearbyRestaurants() {
const client = await MongoClient.connect('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
const db = client.db('test');
const restaurants = db.collection('usarestaurants');
const result = await restaurants.find({
location: {
$nearSphere: {
$geometry: {
type: "Point",
coordinates: [-122.3516, 47.6156]
},
$minDistance: 1,
$maxDistance: 2000
}
}
}, {
projection: { name: 1 }
}).toArray();
console.log(result);
client.close();
}
findNearbyRestaurants();
```
------
#### [ Python ]
```
from pymongo import MongoClient
def find_nearby_restaurants():
client = MongoClient('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
db = client.test
restaurants = db.usarestaurants
result = list(restaurants.find({
'location': {
'$nearSphere': {
'$geometry': {
'type': 'Point',
'coordinates': [-122.3516, 47.6156]
},
'$minDistance': 1,
'$maxDistance': 2000
}
}
}, {
'name': 1
}))
print(result)
client.close()
find_nearby_restaurants()
```
------