Search Geospatially

GeoJSON Positions

A position represents a single place on Earth, and exists in code as an array containing two or three number values:

• Longitude in the first position (required)

• Latitude in the second position (required)

• Elevation in the third position (optional)

GeoJSON Types

Your GeoJSON object's type determines its geometric shape. 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. This can represent the location of a sculpture.

• LineString: an array of two or more positions, thus forming a series of line segments. This can represent the route of the Great Wall of China.

• Polygon: an array of positions in which the first and last position are the same, thus enclosing some space. This can represent the land within Vatican City.

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

Insert a Document Containing GeoJSON Data

To insert a document that stores GeoJSON data, create a document that contains a GeoJSON value and pass the document to the insertOne() method.

The following example inserts a document that includes a location.geo field, which contains GeoJSON data:

// Add your MongoCollection setup code here
Point point = new Point(new Position(-74.0065, 40.7085));
Document theater = new Document("theaterId", 1203)
		.append("location", new Document("geo", point));
InsertOneResult result = collection.insertOne(theater);

To learn more about inserting documents, see the Insert Operations guide.

Index

To query data stored in the GeoJSON format, add the field containing GeoJSON data to a 2dsphere index. The following snippet creates a 2dsphere index on the location.geo field using the Indexes builder:

// <MongoCollection setup code here>
collection.createIndex(Indexes.geo2dsphere("location.geo"));

For more information about the Indexes builder, see our guide on the Indexes builder.

Insert a Document Containing Legacy Coordinates

To insert a document that stores a legacy coordinate pair, create a document that assigns a coordinate pair value to a field. Then, pass the document to the insertOne() method.

The following example inserts a document that includes a coordinates field, which contains a legacy coordinate pair:

// Add your MongoCollection setup code here
Document theater = new Document("theaterId", 1204)
		.append("coordinates", Arrays.asList(-73.9862, 40.7311));
InsertOneResult result = collection.insertOne(theater);

To learn more about inserting documents, see the Insert Operations guide.

Index

To query data stored as legacy coordinate pairs, you must add the field containing legacy coordinate pairs to a 2d index. The following snippet creates a 2d index on the coordinates field using the Indexes builder:

// <MongoCollection setup code here>
collection.createIndex(Indexes.geo2d("coordinates"));

For more information about the Indexes builder, see our guide on the Indexes builder.

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

Query Operators

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

• $near

• $geoWithin

• $nearSphere

• $geoIntersects requires a 2dsphere index

You can specify these query operators in the MongoDB Java driver with the near(), geoWithin(), nearSphere(), and geoIntersects() utility methods of the Filters builder class.

For more information about geospatial query operators, see the manual entry for geospatial queries.

For more information about Filters, see our guide on the Filters builder.

Query Parameters

To specify a shape to use in a geospatial query, use the Position, Point, LineString, and Polygon classes of the MongoDB Java driver.

For a full list of the GeoJSON shapes available in the MongoDB Java driver, see the GeoJSON package API Documentation.

Query by Proximity

To search for and return documents from nearest to farthest from a point, use the near() static utility method of the Filters builder class. The near() method constructs a query with the $near query operator.

The following example queries for theaters between 10,000 and 5,000 meters from the Great Lawn of Central Park.

// Add your MongoClient setup code here
MongoDatabase database = mongoClient.getDatabase("sample_mflix");
MongoCollection<Document> collection = database.getCollection("theaters");
Point centralPark = new Point(new Position(-73.9667, 40.78));
// Creates a query that matches all locations between 5,000 and 10,000 meters from the specified Point
Bson query = near("location.geo", centralPark, 10000.0, 5000.0);
// Creates a projection to include only the "location.address.city" field in the results
Bson projection = fields(include("location.address.city"), excludeId());
// Prints the projected field of the results from the geospatial query as JSON
collection.find(query)
        .projection(projection)
        .forEach(doc -> System.out.println(doc.toJson()));

The output of the preceding code resembles the following:

{"location": {"address": {"city": "Bronx"}}}
{"location": {"address": {"city": "New York"}}}
{"location": {"address": {"city": "New York"}}}
{"location": {"address": {"city": "Long Island City"}}}
{"location": {"address": {"city": "New York"}}}
{"location": {"address": {"city": "Secaucus"}}}
{"location": {"address": {"city": "Jersey City"}}}
{"location": {"address": {"city": "Elmhurst"}}}
{"location": {"address": {"city": "Flushing"}}}
{"location": {"address": {"city": "Flushing"}}}
{"location": {"address": {"city": "Flushing"}}}
{"location": {"address": {"city": "Elmhurst"}}}

For more information about the $near operator, see the reference documentation for $near.

For more information about Filters, see our guide on the Filters builder.

Query Within a Range

To search for geospatial data within a specified shape use the geoWithin() static utility method of the Filters builder class. The geoWithin() method constructs a query with the $geoWithin query operator.

The following example searches for movie theaters in a section of Long Island.

// Add your MongoCollection setup code here
// Creates a set of points that defines the bounds of a geospatial shape
Polygon longIslandTriangle = new Polygon(Arrays.asList(new Position(-72, 40),
        new Position(-74, 41),
        new Position(-72, 39),
        new Position(-72, 40)));
// Creates a projection to include only the "location.address.city" field in the results
Bson projection = fields(include("location.address.city"), excludeId());
// Creates a query that matches documents containing "location.geo" values within the specified bounds
Bson geoWithinComparison = geoWithin("location.geo", longIslandTriangle);
// Prints the projected field of the results from the geolocation query as JSON
collection.find(geoWithinComparison)
        .projection(projection)
        .forEach(doc -> System.out.println(doc.toJson()));

The output of the preceding code resembles the following:

{"location": {"address": {"city": "Baldwin"}}}
{"location": {"address": {"city": "Levittown"}}}
{"location": {"address": {"city": "Westbury"}}}
{"location": {"address": {"city": "Mount Vernon"}}}
{"location": {"address": {"city": "Massapequa"}}}

The following figure shows the polygon defined by the longIslandTriangle variable and dots representing the locations of the movie theaters returned by our query.

For more information about the $geoWithin operator, see the reference documentation for $geoWithin

For more information about the operators you can use in your query, see the MongoDB Server manual page on geospatial query operators