(DOCSP-29210): CRUD > Search Geospatially page (#13)

# Pull Request Info

JIRA - https://jira.mongodb.org/browse/DOCSP-29210
Staging -
https://docs-mongodbcom-staging.corp.mongodb.com/kotlin/docsworker-xlarge/docsp-29210-geo/fundamentals/crud/read-operations/geo/

[PR Reviewing
Guidelines](https://github.com/mongodb/docs-java/blob/master/REVIEWING.md)

## Pages Updated

CRUD > Read Operations > Search Geospatially page

## Changes Made
 
- Copy is unchanged from ([Java
version](https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/crud/read-operations/geo/))
of page, except where noted
- Replace all code examples with generated, tested Kotlin examples

## Checklist

- [ ] Are TOCs updated? If landing page, is page added to `snooty.toml`?
- [ ] Is .rst file renamed to .txt to ensure it's published?
- [ ] Are all API links flagged for TODO (to be updated when API Ref
docs are published)?

### Self-Review Checklist

- [ ] Is this free of any warnings or errors in the RST?
- [ ] Did you run a spell-check?
- [ ] Did you run a grammar-check?
- [ ] Are all the links working?

Author: cbullinger

examples/src/test/kotlin/GeoTest.kt

@@ -0,0 +1 @@
+collection.createIndex((Indexes.geo2d("coordinates")))

source/examples/generated/GeoTest.snippet.geo2d-index.kt

@@ -0,0 +1 @@
+collection.createIndex((Indexes.geo2dsphere("location.geo")))

source/examples/generated/GeoTest.snippet.geo2dsphere-index.kt

@@ -0,0 +1,13 @@
+val database = client.getDatabase("sample_mflix")
+val collection = database.getCollection<TheaterResults>("theaters")
+val centralPark = Point(Position(-73.9667, 40.78))
+val query = Filters.near(
+    "${Theater::location.name}.${Theater.Location::geo.name}", centralPark, 10000.0, 5000.0
+)
+val projection = Projections.fields(
+    Projections.include(
+        "${Theater::location.name}.${Theater.Location::address.name}.${Theater.Location.Address::city.name}"),
+    Projections.excludeId()
+)
+val resultsFlow = collection.find(query).projection(projection)
+resultsFlow.collect { println(it) }

source/examples/generated/GeoTest.snippet.proximity-query.kt

@@ -0,0 +1,19 @@
+val longIslandTriangle = Polygon(
+    listOf(
+        Position(-72.0, 40.0),
+        Position(-74.0, 41.0),
+        Position(-72.0, 39.0),
+        Position(-72.0, 40.0)
+    )
+)
+val projection = Projections.fields(
+    Projections.include(
+        "${Theater::location.name}.${Theater.Location::address.name}.${Theater.Location.Address::city.name}"),
+    Projections.excludeId()
+)
+val geoWithinComparison = Filters.geoWithin(
+    "${Theater::location.name}.${Theater.Location::geo.name}", longIslandTriangle
+)
+val resultsFlow = collection.find<TheaterResults>(geoWithinComparison)
+    .projection(projection)
+resultsFlow.collect { println(it) }

source/examples/generated/GeoTest.snippet.query-range.kt

@@ -0,0 +1,12 @@
+data class TheaterResults(
+    val location: Location
+) {
+    data class Location(
+        val address: Address
+    ) {
+        data class Address(
+            val city: String
+        )
+    }
+}
+

source/examples/generated/GeoTest.snippet.results-data-class.kt

@@ -0,0 +1,17 @@
+data class Theater(
+    val theaterId: Int,
+    val location: Location
+) {
+    data class Location(
+        val address: Address,
+        val geo: Point
+    ) {
+        data class Address(
+            val street1: String,
+            val street2: String? = null,
+            val city: String,
+            val state: String,
+            val zipcode: String
+        )
+    }
+}

source/examples/generated/GeoTest.snippet.theater-data-class.kt

@@ -14,7 +14,7 @@ Overview
 --------
 
 In this guide, you can learn how to search **geospatial data** with the
-MongoDB Java Driver, and the different geospatial data formats supported by MongoDB.
+MongoDB Kotlin Driver, and the different geospatial data formats supported by MongoDB.
 
 Geospatial data is data that represents a geographical location on
 the surface of the Earth. Examples of geospatial data include:
@@ -42,8 +42,6 @@ Here is the location of MongoDB headquarters in GeoJSON:
 For definitive information on GeoJSON, see the
 `official IETF specification <https://datatracker.ietf.org/doc/html/rfc7946>`__.
 
-.. external resource
-
 GeoJSON Positions
 ~~~~~~~~~~~~~~~~~
 
@@ -83,25 +81,19 @@ Here are some common GeoJSON types and how you can specify them with positions:
 To learn more about the shapes you can use in MongoDB, see the
 :manual:`GeoJSON manual entry </reference/geojson/>`.
 
-.. external resource
-
 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:
 
-.. code-block:: java
-
-   // <MongoCollection setup code here>
-   collection.createIndex(Indexes.geo2dsphere("location.geo"));
+.. literalinclude:: /examples/generated/GeoTest.snippet.geo2dsphere-index.kt
+   :language: kotlin
 
 For more information on the ``Indexes`` builder, see our 
 :doc:`guide on the Indexes builder </fundamentals/builders/indexes>`.
 
-.. guide resource
-
 Coordinates on a 2D Plane
 -------------------------
 
@@ -125,28 +117,22 @@ To query data stored as legacy coordinate pairs, you must add the field containi
 legacy coordinate pairs to  a ``2d`` index. The following snippet creates a
 ``2d`` index on the ``coordinates`` field using the ``Indexes`` builder:
 
-.. code-block:: java
-
-   // <MongoCollection setup code here>
-   collection.createIndex(Indexes.geo2d("coordinates"));
+.. literalinclude:: /examples/generated/GeoTest.snippet.geo2d-index.kt
+   :language: kotlin
 
 For more information on the ``Indexes`` builder, see our 
 :doc:`guide on the Indexes builder </fundamentals/builders/indexes>`. 
 
 For more information on legacy coordinate pairs, see the
 :manual:`MongoDB server manual page on legacy coordinate pairs </geospatial-queries/#legacy-coordinate-pairs>`.
 
-.. external resource
-
 .. tip:: Supported Operators
 
    Spherical (``2dsphere``) and flat (``2d``) indexes support some, but
    not all, of the same query operators. For a full list of operators
    and their index compatibility, see the
    :manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
 
-   .. external resource
-
 Geospatial Queries
 ------------------
 
@@ -163,15 +149,13 @@ To query your geospatial data, use one of the following query operators:
 - ``$nearSphere``
 - ``$geoIntersects`` *requires a 2dsphere index*
 
-You can specify these query operators in the MongoDB Java driver with the
+You can specify these query operators in the MongoDB Kotlin driver with the
 ``near()``, ``geoWithin()``, ``nearSphere()``, and ``geoIntersects()`` utility
 methods of the ``Filters`` builder class.
 
 For more information on geospatial query operators, see the
 :manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
 
-.. external resource
-
 For more information on ``Filters``, see our 
 :doc:`guide on the Filters builder </fundamentals/builders/filters>`.  
 
@@ -180,15 +164,13 @@ 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.
+Kotlin driver.
 
-For a full list of the GeoJSON shapes available in the MongoDB Java driver, see the
+For a full list of the GeoJSON shapes available in the MongoDB Kotlin driver, see the
 `GeoJSON package
 <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/geojson/package-summary.html>`__
 API Documentation.
 
-.. external resource
-
 Examples
 --------
 
@@ -197,21 +179,34 @@ to  set up your own free-tier Atlas cluster and how to load the sample dataset
 in our :doc:`quick start guide </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.
+from the sample dataset. 
 
 The examples require the following imports:
 
-.. literalinclude:: /includes/fundamentals/code-snippets/Geo.java
-   :language: java
-   :dedent:
-   :start-after: begin exampleImports
-   :end-before: end exampleImports
+.. code-block:: 
+  :source: kotlin
+
+  import com.mongodb.client.model.geojson.Point
+  import com.mongodb.client.model.geojson.Polygon
+  import com.mongodb.client.model.geojson.Position
+  import com.mongodb.client.model.Filters.near
+  import com.mongodb.client.model.Filters.geoWithin
+  import com.mongodb.client.model.Projections.fields
+  import com.mongodb.client.model.Projections.include
+  import com.mongodb.client.model.Projections.excludeId
+
+The data is modeled using the following Kotlin data class:
+
+.. literalinclude:: /examples/generated/GeoTest.snippet.theater-data-class.kt
+  :language: kotlin
 
-You can find the  
-`source code for the examples on Github here <https://github.com/mongodb/docs-java/blob/master/source/includes/fundamentals/code-snippets/Geo.java>`__.
+The results are modeled using the following Kotlin data class:
 
-.. external resource
+.. literalinclude:: /examples/generated/GeoTest.snippet.results-data-class.kt
+  :language: kotlin
+  
+The ``theaters`` collection already contains a ``2dsphere`` index on the 
+``"${Theater::location.name}.${Theater.Location::geo.name}"`` field.
 
 Query by Proximity
 ~~~~~~~~~~~~~~~~~~
@@ -221,44 +216,40 @@ 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 <https://en.wikipedia.org/wiki/Great_Lawn_and_Turtle_Pond>`__.
+meters from the Great Lawn of Central Park:
 
-.. literalinclude:: /includes/fundamentals/code-snippets/Geo.java
-   :language: java
-   :dedent:
-   :start-after: begin findExample
-   :end-before: end findExample
+.. io-code-block::
 
-The output of the code snippet should look something like this:
+   .. input:: /examples/generated/GeoTest.snippet.proximity-query.kt
+      :language:  kotlin
 
-.. code-block:: json
-   :copyable: false
+   .. output:: 
+      :language:  console
 
-   {"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"}}}
+      TheaterResults(location=Location(address=Address(city=Bronx)))
+      TheaterResults(location=Location(address=Address(city=New York)))
+      TheaterResults(location=Location(address=Address(city=New York)))
+      TheaterResults(location=Location(address=Address(city=Long Island City)))
+      TheaterResults(location=Location(address=Address(city=New York)))
+      TheaterResults(location=Location(address=Address(city=Secaucus)))
+      TheaterResults(location=Location(address=Address(city=Jersey City)))
+      TheaterResults(location=Location(address=Address(city=Elmhurst)))
+      TheaterResults(location=Location(address=Address(city=Flushing)))
+      TheaterResults(location=Location(address=Address(city=Flushing)))
+      TheaterResults(location=Location(address=Address(city=Flushing)))
+      TheaterResults(location=Location(address=Address(city=Elmhurst)))
 
 .. tip:: Fun Fact
 
    MongoDB uses the
    :manual:`same reference system </reference/glossary/#std-term-WGS84>`
    as GPS satellites to calculate geometries over the Earth.
 
-For more information on the ``$near`` operator, see  
-:manual:`the reference documentation for $near </reference/operator/query/near/#mongodb-query-op.-near>`.
+For more information on the ``$near`` operator, see the 
+:manual:`reference documentation for $near </reference/operator/query/near/#mongodb-query-op.-near>`.
 
-For more information on ``Filters``,
-:doc:`see our guide on the Filters builder </fundamentals/builders/filters>`.
+For more information on ``Filters``, see
+:doc:`our guide on the Filters builder </fundamentals/builders/filters>`.
 
 Query Within a Range
 ~~~~~~~~~~~~~~~~~~~~
@@ -271,22 +262,19 @@ The following example searches for movie theaters in a section of Long Island.
 
 .. _example_range_query:
 
-.. literalinclude:: /includes/fundamentals/code-snippets/Geo.java
-   :language: java
-   :dedent:
-   :start-after: begin rangeExample
-   :end-before: end rangeExample
+.. io-code-block::
 
-The output of the code snippet should look something like this:
+   .. input:: /examples/generated/GeoTest.snippet.query-range.kt
+      :language:  kotlin
 
-.. code-block:: json
-   :copyable: false
+   .. output:: 
+      :language: console
 
-   {"location": {"address": {"city": "Baldwin"}}}
-   {"location": {"address": {"city": "Levittown"}}}
-   {"location": {"address": {"city": "Westbury"}}}
-   {"location": {"address": {"city": "Mount Vernon"}}}
-   {"location": {"address": {"city": "Massapequa"}}}
+      TheaterResults(location=Location(address=Address(city=Baldwin))))
+      TheaterResults(location=Location(address=Address(city=Levittown)))
+      TheaterResults(location=Location(address=Address(city=Westbury)))
+      TheaterResults(location=Location(address=Address(city=Mount Vernon)))
+      TheaterResults(location=Location(address=Address(city=Massapequa)))
 
 The following figure shows the polygon defined by the
 ``longIslandTriangle`` variable and dots representing the locations of
@@ -298,9 +286,5 @@ the movie theaters returned by our query.
 For more information on the ``$geoWithin`` operator, see the
 :manual:`reference documentation for $geoWithin </reference/operator/query/geoWithin/>`
 
-.. external resource
-
 For more information on the operators you can use in your query, see the
 :manual:`MongoDB server manual page on geospatial query operators </geospatial-queries/index.html>`
-
-.. external resource