DOCS-641 geospatial final edits

source/applications/2d.txt

@@ -47,13 +47,13 @@ To store location data as legacy coordinate pairs, use either an array
 
 .. code-block:: javascript
 
-   loc : [ <long> , <lat> ]
+   loc : [ <longitude> , <latitude> ]
 
 Or an embedded document:
 
 .. code-block:: javascript
 
-   loc : { long : <long> , lat : <lat> }
+   loc : { lng : <longitude> , lat : <latitude> }
 
 Arrays are preferred as certain languages do not guarantee associative
 map ordering.

source/applications/2dsphere.txt

@@ -15,8 +15,6 @@ supports legacy coordinate pairs by converting the data to the GeoJSON
 The ``2dsphere`` index supports all MongoDB geospatial queries: queries
 for inclusion, intersection and proximity.
 
-MongoDB allows one ``2dsphere`` index per collection.
-
 A :ref:`compound <index-type-compound>` ``2dsphere`` index can reference
 multiple location and non-location fields within a collection’s
 documents. You can arrange the fields in any order.
@@ -106,18 +104,20 @@ The following are four example commands for creating a ``2dsphere`` index:
 .. code-block:: javascript
 
    db.collection.ensureIndex( { loc : "2dsphere" } )
-   db.collection.ensureIndex( { loc : "2dsphere", type : 1 } )
-   db.collection.ensureIndex( { type : 1, loc : "2dsphere" } )
-   db.collection.ensureIndex( { loc : "2dsphere", type : 1, rating : -1 } )
+   db.collection.ensureIndex( { loc : "2dsphere" , type : 1 } )
+   db.collection.ensureIndex( { rating : 1 , loc : "2dsphere" } )
+   db.collection.ensureIndex( { loc : "2dsphere" , rating : 1 , category : -1 } )
 
 The first example creates a simple geospatial index on the location
 field ``loc``. The second example creates a compound index where the
 second field contains non-location data. The third example creates an
 index where the location field is not the primary field: the location
 field does not have to be the first field in a ``2dsphere`` index. The
-fourth example creates a compound index with three fields: you can
+fourth example creates a compound index with three fields. You can
 include as many fields as you like in a ``2dsphere`` index.
 
+.. _geospatial-indexes-query-2dsphere:
+
 Query a ``2dsphere`` Index
 --------------------------
 
@@ -158,8 +158,12 @@ Intersections of GeoJSON Objects
 
 .. versionadded:: 2.4
 
-The :operator:`$geoIntersects` operator queries for location data that
-intersects a GeoJSON object. Use the following syntax:
+The :operator:`$geoIntersects` operator queries for locations that
+intersect a specified GeoJSON object. A location intersects the object
+if the intersection is non-empty. This includes documents that have a
+shared edge.
+
+The :operator:`$geoIntersects` operator uses the following syntax:
 
 .. code-block:: javascript
 
@@ -183,9 +187,6 @@ indexed points and shapes that intersect with the polygon defined by the
                            coordinates: [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ]
                    } } } } )
 
-The query returns true if the intersection between shapes is non-empty.
-This includes documents that have a shared edge.
-
 Proximity to a GeoJSON Point
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -205,7 +206,7 @@ The :operator:`$near` uses the following syntax:
                             { $near :
                               { $geometry :
                                  { type : "Point" ,
-                                   coordinates : [ <long>, <lat> ] } ,
+                                   coordinates : [ <longitude> , <latitude> ] } ,
                                 $maxDistance : <distance in meters>
                          } } } )
 

source/applications/geohaystack.txt

@@ -58,9 +58,9 @@ To build a haystack index, use the following syntax:
 
    .. code-block:: javascript
 
-      { _id : 100, pos: { long : 126.9, lat : 35.2 } , type : "restaurant"}
-      { _id : 200, pos: { long : 127.5, lat : 36.1 } , type : "restaurant"}
-      { _id : 300, pos: { long : 128.0, lat : 36.7 } , type : "national park"}
+      { _id : 100, pos: { lng : 126.9, lat : 35.2 } , type : "restaurant"}
+      { _id : 200, pos: { lng : 127.5, lat : 36.1 } , type : "restaurant"}
+      { _id : 300, pos: { lng : 128.0, lat : 36.7 } , type : "national park"}
 
    The following operations create a haystack index with buckets that
    store keys within 1 unit of longitude or latitude.

source/applications/geospatial-indexes.txt

@@ -25,15 +25,16 @@ MongoDB offers two surface types:
   </applications/2dsphere>` index.
 
   Store your location data as GeoJSON objects with this coordinate-axis
-  order: **longitude, latitude**. The default coordinate reference
-  system for GeoJSON uses the :term:`WGS84` datum. MongoDB does not yet
-  support non-default coordinate reference systems in GeoJSON.
+  order: **longitude, latitude**. The coordinate reference system for
+  GeoJSON is the :term:`WGS84` datum.
 
 - **Flat**
 
   To calculate distances on a Euclidean plane, store your location data
   as legacy coordinate pairs and use a :doc:`2d </applications/2d>` index.
 
+.. _geo-overview-location-data:
+
 Location Data
 -------------
 
@@ -48,6 +49,14 @@ If you choose spherical surface calculations, you store location data as
      is new in version 2.4. Prior to version 2.4, all geospatial data was
      stored as coordinate pairs.
 
+  MongoDB supports the following GeoJSON objects:
+
+  - Point
+
+  - LineString
+
+  - Polygon
+
 - :term:`Legacy coordinate pairs <legacy coordinate pairs>`
 
   MongoDB supports spherical surface calculations on legacy coordinate

source/core/geospatial-indexes.txt

@@ -80,11 +80,11 @@ example:
    { _id : ObjectId(...),
      locs : [ [ 55.5 , 42.3 ] ,
               [ -74 , 44.74 ] ,
-              { long : 55.5 , lat : 42.3 } ]
+              { lng : 55.5 , lat : 42.3 } ]
    }
 
 The values of the array may be either arrays, as in ``[ 55.5, 42.3 ]``,
-or embedded documents, as in ``{ long : 55.5 , lat : 42.3 }``.
+or embedded documents, as in ``{ lng : 55.5 , lat : 42.3 }``.
 
 You could then create a geospatial index on the ``locs`` field, as in
 the following:

source/reference/command/geoNear.txt

@@ -29,8 +29,8 @@ geoNear
 
       { geoNear : <collection> , near : [ <coordinates> ] }
 
-   `geoNear` provides the following options (specify all
-   distances in the same units as the document coordinate system):
+   The :dbcommand:`geoNear` command provides the following options. Specify all
+   distances in the same units as the document coordinate system:
 
    :field near: Can use either a GeoJSON point or legacy points,
                 as shown above.

source/reference/glossary.txt

@@ -902,8 +902,9 @@ Glossary
 
       GeoJSON is a geospatial data interchange format based on
       JavaScript Object Notation (JSON) and is used in geospatial queries.
-      For details, see the
-      `GeoJSON Format Specification <http://geojson.org/geojson-spec.html>`_
+      For supported GeoJSON objects, see :ref:`geo-overview-location-data`.
+      For the GeoJSON format specification, see
+      `http://geojson.org/geojson-spec.html <http://geojson.org/geojson-spec.html>`_
 
    legacy coordinate pairs
       The format used for geospatial data prior to MongoDB version 2.4.

source/reference/operator/geoIntersects.txt

@@ -9,16 +9,11 @@ $geoIntersects
    .. versionadded:: 2.4
 
    The :operator:`$geoIntersects` operator is a geospatial query
-   operator that selects all points that intersect with one of the
-   following :term:`GeoJSON` objects:
-
-   - Point
-
-   - LineString
-
-   - Polygon
-
-   The :operator:`$geoIntersects` operator uses spherical geometry.
+   operator that selects all locations that intersect with a
+   :term:`GeoJSON` object. A location intersects a GeoJSON object if the
+   intersection is non-empty. This includes documents that have a shared
+   edge. The :operator:`$geoIntersects` operator uses spherical
+   geometry.
 
    The ``2dsphere`` geospatial index supports
    :operator:`$geoIntersects`.
@@ -50,6 +45,3 @@ $geoIntersects
                             { type : "Polygon" ,
                               coordinates: [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] }
                       } } } } )
-
-   The query returns true if the intersection between shapes is
-   non-empty. This includes documents that have a shared edge.

source/reference/operator/geoWithin.txt

@@ -46,7 +46,7 @@ $geoWithin
                                { $geoWithin :
                                   { $geometry :
                                      { type : "Polygon" ,
-                                       coordinates : [ [ [ <long1>, <lat1> ] , [ <long2>, <lat2> ] ... ] ]
+                                       coordinates : [ [ [ <lng1>, <lat1> ] , [ <lng2>, <lat2> ] ... ] ]
                             } } } } )
 
    .. important:: Specify coordinates in this order: **"longitude, latitude."**
@@ -59,8 +59,8 @@ $geoWithin
                                { $geoWithin :
                                   { $geometry :
                                      { type : "Polygon" ,
-                                       coordinates : [ [ [ <long1>, <lat1> ] , [ <long2>, <lat2> ] ... ]
-                                                       [ [ <longa>, <lata> ] , [ <longb>, <latb> ] ... ] ]
+                                       coordinates : [ [ [ <lng1>, <lat1> ] , [ <lng2>, <lat2> ] ... ]
+                                                       [ [ <lngA>, <latA> ] , [ <lngB>, <latB> ] ... ] ]
                             } } } } )
 
    The following example selects all indexed points and shapes that

source/reference/operator/near.txt

@@ -25,15 +25,15 @@ $near
    GeoJSON points, use a ``2dsphere`` index. For legacy coordinate
    pairs, use a ``2d`` index.
 
-   If querying on GeoJSON data, use the following syntax:
+   For queries on GeoJSON data, use the following syntax:
 
    .. code-block:: javascript
 
       db.<collection>.find( { <location field> :
                                { $near :
                                   { $geometry :
                                       { type : "Point" ,
-                                        coordinates : [ <longitude>, <latitude> ] } ,
+                                        coordinates : [ <longitude> , <latitude> ] } ,
                                     $maxDistance : <distance in meters>
                             } } } )
 
@@ -48,11 +48,11 @@ $near
       db.places.find( { loc : { $near :
                                  { $geometry :
                                      { type : "Point" ,
-                                       coordinates: [ 40 , 5 ] } } ,
+                                       coordinates: [ 40 , 5 ] } ,
                                    $maxDistance : 100
                       } } } )
 
-   If querying on legacy coordinate pairs, use the following syntax:
+   For queries on legacy coordinate pairs, use the following syntax:
 
    .. code-block:: javascript
 

source/reference/operator/nearSphere.txt

@@ -9,35 +9,53 @@ $nearSphere
    .. versionadded:: 1.8
 
    The :operator:`$nearSphere` operator specifies a point for which a
-   :term:`geospatial` query returns the 100 closest documents. The
-   :operator:`$nearSphere` operator queries for points defined by legacy
-   coordinate pairs or :term:`GeoJSON` objects and calculates distances
-   using spherical geometry. The query sorts the documents from nearest
-   to farthest.
+   :term:`geospatial` query returns the 100 closest documents, sorted
+   from nearest to farthest. MongoDB calculates distances for
+   :operator:`$nearSphere` using spherical geometry.
+
+   The :operator:`$nearSphere` operator queries for points defined by
+   either :term:`GeoJSON` objects or legacy coordinate pairs.
 
    The optional :operator:`$maxDistance` operator limits a
-   :operator:`$nearSphere` query to return only those documents that fall
-   within a maximum distance of a point. Specify the maximum distance in
-   the units specified by the coordinate system.
+   :operator:`$nearSphere` query to return only those documents that
+   fall within a maximum distance of a point. If you use
+   :operator:`$maxDistance` on GeoJSON points, the distance is measured
+   in meters. If you use :operator:`$maxDistance` on legacy coordinate
+   pairs, the distance is measured in radians.
 
    The :operator:`$nearSphere` operator requires a geospatial index. The
-   ``2dsphere`` and ``2d`` indexes both support the
-   :operator:`$nearSphere` operator. In a ``2dsphere`` index, a grid
-   coordinate is interpreted as a GeoJSON point.
+   ``2dsphere`` and ``2d`` indexes both support :operator:`$nearSphere`.
+   In a ``2dsphere`` index, a grid coordinate is interpreted as a
+   GeoJSON point.
+
+   For queries on GeoJSON data, use the following syntax:
+
+   .. code-block:: javascript
+
+      db.<collection>.find( { <location field> :
+                               { $nearSphere :
+                                 { $geometry :
+                                    { type : "Point" ,
+                                      coordinates : [ <longitude> , <latitude> ] } ,
+                                   $maxDistance : <distance in meters>
+                         } } } )
+
+   .. important:: If you use longitude and latitude, specify **longitude first**.
 
-   The :operator:`$nearSphere` operator uses the following syntax:
+   For queries on legacy coordinate pairs, use the following syntax:
 
    .. code-block:: javascript
 
       db.<collection>.find( { <location field> :
                                { $nearSphere: [ <x> , <y> ] ,
-                                 $maxDistance: <distance>
+                                 $maxDistance: <distance in radians>
                             } } )
 
    .. important:: If you use longitude and latitude, specify **longitude first**.
 
-   The following example selects the 100 documents with coordinates
-   nearest to ``[ 40 , 5 ]`` as calculated by spherical geometry:
+   The following example selects the 100 documents with legacy
+   coordinates pairs nearest to ``[ 40 , 5 ]``, as calculated by
+   spherical geometry:
 
    .. code-block:: javascript
 

source/reference/operator/polygon.txt

@@ -9,9 +9,9 @@ $polygon
    .. versionadded:: 1.9
 
    The :operator:`$polygon` operator specifies a polygon for a
-   :term:`geospatial` :operator:`$geoWithin` query. The query returns
-   legacy coordinate pairs that are within the bounds of the polygon.
-   The operator does *not* query for GeoJSON objects.
+   :term:`geospatial` :operator:`$geoWithin` query on legacy coordinate
+   pairs. The query returns pairs that are within the bounds of the
+   polygon. The operator does *not* query for GeoJSON objects.
 
    The :operator:`$polygon` operator calculates distances using flat (planar)
    geometry.
@@ -35,7 +35,7 @@ $polygon
    like.
 
    The following query returns all documents that have coordinates that
-   exist within the polygon defined by ``[ 0 , 0 ]``, ``[ 3 , 3 ]``, and
+   exist within the polygon defined by ``[ 0 , 0 ]``, ``[ 3 , 6 ]``, and
    ``[ 6 , 0 ]``:
 
    .. code-block:: javascript