Navigation

geoWithin

On this page

Definition

geoWithin

The geoWithin operator supports querying geographic points within a given geometry. Only points are returned, even if indexShapes value is true in the index definition.

You can query points within a:

  • Circle
  • Bounding box
  • Polygon

When specifying the coordinates to search, longitude must be specified first and then the latitude. Longitude values can be between -180 and 180, both inclusive. Latitude values can be between -90 and 90, both inclusive. Coordinate values can be integers or doubles.

Note

Atlas Search does not support the following:

  • Non-default coordinate reference system (CRS)
  • Planar XY coordinate system (2 dimensional)
  • Coordinate pairs Point notation (that is, pointFieldName: [12, 34])

Syntax

geoWithin has the following syntax:

copy 
{
  "$search": {
     "index": <index name>, // optional, defaults to "default"
     "geoWithin": {
        "path": "<field-to-search>",
        "circle | box | geometry": <object>,
        "score": <score-options>
     }
  }
}

Options

geoWithin uses the following terms to construct a query:

Field Type Description Necessity
box object

Object that specifies the bottom left and top right GeoJSON points of a box to search within. The object takes the following fields:

  • bottomLeft - Bottom left GeoJSON point.
  • topRight - Top right GeoJSON point.

Either box, circle, or geometry is required.

 conditional
circle object

Object that specifies the center point and the radius in meters to search within. The object contains the following GeoJSON fields:

  • center - Center of the circle specified as a GeoJSON point.
  • radius - Radius, which is a number, specified in meters. Value must be greater than or equal to 0.

Either circle, box, or geometry is required.

 conditional
geometry GeoJSON object

GeoJSON object that specifies the MultiPolygon or Polygon to search within. The polygon must be specified as a closed loop where the last position is the same as the first position.

Either geometry, box, or circle is required.

 conditional
path string or array of strings Indexed geo type field or fields to search. See Path Construction. yes
score object

Score assigned to matching search results. The score in the results is always 1. You can modify the score using the following options:

  • boost: multiply the result score by the given number.
  • constant: replace the result score with the given number.

For information on using score in your query, see Scoring.

 no

Examples

The following examples use the listingsAndReviews collection in the sample_airbnb database. If you have the sample dataset on your cluster, you can create a custom Atlas Search index for geo type and run the queries on your cluster. The following is a sample index definition for indexing the address.location field in the listingsAndReviews collection:

copy 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "mappings": {
    "fields": {
      "address": {
        "fields": {
          "location": {
            "type": "geo"
          }
        },
        "type": "document"
      }
    }
  }
}

The Tutorial: Create and Query an Atlas Search Index contains instructions for loading the sample dataset, creating an index definition, and running Atlas Search queries.

Box Example

The following example uses the geoWithin operator to search for properties within a bounding box in Australia. It includes a $limit stage to limit the output to 3 results and a $project stage to exclude all fields except name and address.

copy 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
db.listingsAndReviews.aggregate([
  {
    "$search": {
      "geoWithin": {
        "path": "address.location",
        "box": {
          "bottomLeft": {
            "type": "Point",
            "coordinates": [112.467, -55.050]
          },
          "topRight": {
            "type": "Point",
            "coordinates": [168.000, -9.133]
          }
        }
      }
    }
  },
  {
    $limit: 3
  },
  {
    $project: {
      "_id": 0,
      "name": 1,
      "address": 1
    }
  }
])

The previous query returns the following results:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "name" : "Surry Hills Studio - Your Perfect Base in Sydney",
  "address" : {
    "street" : "Surry Hills, NSW, Australia",
    "suburb" : "Darlinghurst",
    "government_area" : "Sydney",
    "market" : "Sydney",
    "country" : "Australia",
    "country_code" : "AU",
    "location" : {
      "type" : "Point",
      "coordinates" : [ 151.21554, -33.88029 ],
      "is_location_exact" : true
    }
  }
}
{
  "name" : "Sydney Hyde Park City Apartment (checkin from 6am)",
  "address" : {
    "street" : "Darlinghurst, NSW, Australia",
    "suburb" : "Darlinghurst",
    "government_area" : "Sydney",
    "market" : "Sydney",
    "country" : "Australia",
    "country_code" : "AU",
    "location" : {
      "type" : "Point",
      "coordinates" : [ 151.21346, -33.87603 ],
      "is_location_exact" : false
    }
  }
}
{
  "name" : "THE Place to See Sydney's FIREWORKS",
  "address" : {
    "street" : "Rozelle, NSW, Australia",
    "suburb" : "Lilyfield/Rozelle",
    "government_area" : "Leichhardt",
    "market" : "Sydney",
    "country" : "Australia",
    "country_code" : "AU",
    "location" : {
      "type" : "Point",
      "coordinates" : [ 151.17956, -33.86296 ],
      "is_location_exact" : true
    }
  }
}

Circle Example

The following example uses the geoWithin operator to search for properties within one mile radius of specified coordinates in Canada. It includes a $limit stage to limit the output to 3 results and a $project stage to exclude all fields except name and address.

copy 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
db.listingsAndReviews.aggregate([
  {
    "$search": {
      "geoWithin": {
        "circle": {
          "center": {
            "type": "Point",
            "coordinates": [-73.54, 45.54]
          },
          "radius": 1600
        },
        "path": "address.location"
      }
    }
  },
  {
    $limit: 3
  },
  {
    $project: {
      "_id": 0,
      "name": 1,
      "address": 1
    }
  }
])

The query returns the following results:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "name" : "Ligne verte - à 15 min de métro du centre ville.",
  "address" : {
    "street" : "Montréal, Québec, Canada",
    "suburb" : "Hochelaga-Maisonneuve",
    "government_area" : "Mercier-Hochelaga-Maisonneuve",
    "market" : "Montreal",
    "country" : "Canada",
    "country_code" : "CA",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -73.54949, 45.54548 ],
      "is_location_exact" : false
    }
  }
}
{
  "name" : "Belle chambre à côté Metro Papineau",
  "address" : {
    "street" : "Montréal, QC, Canada",
    "suburb" : "Gay Village",
    "government_area" : "Ville-Marie",
    "market" : "Montreal",
    "country" : "Canada",
    "country_code" : "CA",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -73.54985, 45.52797 ],
      "is_location_exact" : false
    }
  }
}
{
  "name" : "L'IDÉAL, ( à 2 min du métro Pie-IX ).",
  "address" : {
    "street" : "Montréal, Québec, Canada",
    "suburb" : "Mercier-Hochelaga-Maisonneuve",
    "government_area" : "Mercier-Hochelaga-Maisonneuve",
    "market" : "Montreal",
    "country" : "Canada",
    "country_code" : "CA",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -73.55208, 45.55157 ],
      "is_location_exact" : true
    }
  }
}

Geometry Examples

The following examples use the geoWithin operator to search for properties in Hawaii. The queries includes a $limit stage to limit the output to 3 results and a $project stage to exclude all fields except name and address.

copy 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
 db.listingsAndReviews.aggregate([
   {
     "$search": {
       "geoWithin": {
         "geometry": {
           "type": "Polygon",
           "coordinates": [[[ -161.323242, 22.512557 ],
                          [ -152.446289, 22.065278 ],
                          [ -156.09375, 17.811456 ],
                          [ -161.323242, 22.512557 ]]]
         },
         "path": "address.location"
       }
     }
   },
   {
     $limit: 3
   },
   {
     $project: {
       "_id": 0,
       "name": 1,
       "address": 1
     }
   }
 ])

The query returns the following results:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "name" : "Ocean View Waikiki Marina w/prkg",
  "address" : {
    "street" : "Honolulu, HI, United States",
    "suburb" : "Oʻahu",
    "government_area" : "Primary Urban Center",
    "market" : "Oahu",
    "country" : "United States",
    "country_code" : "US",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -157.83919, 21.28634 ],
      "is_location_exact" : true
    }
  }
}
{
  "name" : "Kailua-Kona, Kona Coast II 2b condo",
  "address" : {
    "street" : "Kailua-Kona, HI, United States",
    "suburb" : "Kailua/Kona",
    "government_area" : "North Kona",
    "market" : "The Big Island",
    "country" : "United States",
    "country_code" : "US",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -155.96445, 19.5702 ],
      "is_location_exact" : true
    }
  }
}
{
  "name" : "LAHAINA, MAUI! RESORT/CONDO BEACHFRONT!! SLEEPS 4!",
  "address" : {
    "street" : "Lahaina, HI, United States",
    "suburb" : "Maui",
    "government_area" : "Lahaina",
    "market" : "Maui",
    "country" : "United States",
    "country_code" : "US",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -156.68012, 20.96996 ],
      "is_location_exact" : true
    }
  }
}
copy 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
db.listingsAndReviews.aggregate([
  {
    "$search": {
      "geoWithin": {
        "geometry": {
          "type": "MultiPolygon",
          "coordinates": [
                [[[-157.8412413882,21.2882235819],
                [-157.8607925468,21.2962046205],
                [-157.8646640634,21.3077019651],
                [-157.862776699,21.320776283],
                [-157.8341758705,21.3133826738],
                [-157.8349985678,21.3000822569],
                [-157.8412413882,21.2882235819]]],
                [[[-157.852898124,21.301208833],
                [-157.8580050499,21.3050871833],
                [-157.8587346108,21.3098050385],
                [-157.8508811028,21.3119240258],
                [-157.8454308541,21.30396767],
                [-157.852898124,21.301208833]]]
          ]
        },
        "path": "address.location"
      }
    }
  },
  {
    $limit: 3
  },
  {
    $project: {
      "_id": 0,
      "name": 1,
      "address": 1
    }
  }
])

The query returns the following results:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "name" : "Heart of Honolulu, 2BD gem! Free Garage Parking!",
  "address" : {
    "street" : "Honolulu, HI, United States",
    "suburb" : "Makiki/Lower Punchbowl/Tantalus",
    "government_area" : "Primary Urban Center",
    "market" : "Oahu",
    "country" : "United States",
    "country_code" : "US",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -157.84343, 21.30852 ],
      "is_location_exact" : false
    }
  }
}
{
  "name" : "Private Studio closed to town w/ compact parking",
  "address" : {
    "street" : "Honolulu, HI, United States",
    "suburb" : "Oʻahu",
    "government_area" : "Primary Urban Center",
    "market" : "Oahu",
    "country" : "United States",
    "country_code" : "US",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -157.85228, 21.31184 ],
      "is_location_exact" : true
    }
  }
}
{
  "name" : "Comfortable Room (2) at Affordable Rates",
  "address" : {
    "street" : "Honolulu, HI, United States",
    "suburb" : "Oʻahu",
    "government_area" : "Primary Urban Center",
    "market" : "Oahu",
    "country" : "United States",
    "country_code" : "US",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -157.83889, 21.29776 ],
      "is_location_exact" : false
    }
  }
}
←   geoShape near  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.