Soft-deprecation of point/geo_point formats (#86835)

* Soft-deprecation of point/geo_point formats

Since GeoJSON and WKT are now common formats for all three types:
  geo_shape, geo_point and point
We decided to soft-deprecate the other point formats by ordering:
* GeoJSON (object with keys `type` and `coordinates`)
* WKT `POINT(x y)`
* Object with keys `lat` and `lon` (or `x` and `y` for point)
* Array [lon,lat]
* String `"lat,lon"` (or `"x,y"` in point)
* String with geohash (only in `geo_point`)

The geohash is last because it is only in one field type.
The string version is second last because it is the most controversial
being the only version to reverse the coordinate order from all other
formats (for geo_point only, since the coordinates are not reversed
in point).

In addition we replaced many examples in both documentation and tests
to prioritize WKT over the plain string format.

Many remaining examples of array format or object with keys still exist
and could be replaced by, for example, GeoJSON, if we feel the need.

* Incorrect quote position

docs/reference/aggregations/bucket/composite-aggregation.asciidoc

@@ -502,8 +502,8 @@ GET /_search
                 "field": "location",
                 "precision": 22,
                 "bounds": {
-                  "top_left": "52.4, 4.9",
-                  "bottom_right": "52.3, 5.0"
+                  "top_left": "POINT (4.9 52.4)",
+                  "bottom_right": "POINT (5.0 52.3)"
                 }
               }
             }

docs/reference/aggregations/bucket/geodistance-aggregation.asciidoc

@@ -21,17 +21,17 @@ PUT /museums
 
 POST /museums/_bulk?refresh
 {"index":{"_id":1}}
-{"location": "52.374081,4.912350", "name": "NEMO Science Museum"}
+{"location": "POINT (4.912350 52.374081)", "name": "NEMO Science Museum"}
 {"index":{"_id":2}}
-{"location": "52.369219,4.901618", "name": "Museum Het Rembrandthuis"}
+{"location": "POINT (4.901618 52.369219)", "name": "Museum Het Rembrandthuis"}
 {"index":{"_id":3}}
-{"location": "52.371667,4.914722", "name": "Nederlands Scheepvaartmuseum"}
+{"location": "POINT (4.914722 52.371667)", "name": "Nederlands Scheepvaartmuseum"}
 {"index":{"_id":4}}
-{"location": "51.222900,4.405200", "name": "Letterenhuis"}
+{"location": "POINT (4.405200 51.222900)", "name": "Letterenhuis"}
 {"index":{"_id":5}}
-{"location": "48.861111,2.336389", "name": "Musée du Louvre"}
+{"location": "POINT (2.336389 48.861111)", "name": "Musée du Louvre"}
 {"index":{"_id":6}}
-{"location": "48.860000,2.327000", "name": "Musée d'Orsay"}
+{"location": "POINT (2.327000 48.860000)", "name": "Musée d'Orsay"}
 
 POST /museums/_search?size=0
 {
@@ -39,7 +39,7 @@ POST /museums/_search?size=0
     "rings_around_amsterdam": {
       "geo_distance": {
         "field": "location",
-        "origin": "52.3760, 4.894",
+        "origin": "POINT (4.894 52.3760)",
         "ranges": [
           { "to": 100000 },
           { "from": 100000, "to": 300000 },
@@ -100,7 +100,7 @@ POST /museums/_search?size=0
     "rings": {
       "geo_distance": {
         "field": "location",
-        "origin": "52.3760, 4.894",
+        "origin": "POINT (4.894 52.3760)",
         "unit": "km", <1>
         "ranges": [
           { "to": 100 },
@@ -126,7 +126,7 @@ POST /museums/_search?size=0
     "rings": {
       "geo_distance": {
         "field": "location",
-        "origin": "52.3760, 4.894",
+        "origin": "POINT (4.894 52.3760)",
         "unit": "km",
         "distance_type": "plane",
         "ranges": [
@@ -153,7 +153,7 @@ POST /museums/_search?size=0
     "rings_around_amsterdam": {
       "geo_distance": {
         "field": "location",
-        "origin": "52.3760, 4.894",
+        "origin": "POINT (4.894 52.3760)",
         "ranges": [
           { "to": 100000 },
           { "from": 100000, "to": 300000 },
@@ -207,7 +207,7 @@ POST /museums/_search?size=0
     "rings_around_amsterdam": {
       "geo_distance": {
         "field": "location",
-        "origin": "52.3760, 4.894",
+        "origin": "POINT (4.894 52.3760)",
         "ranges": [
           { "to": 100000, "key": "first_ring" },
           { "from": 100000, "to": 300000, "key": "second_ring" },

docs/reference/aggregations/bucket/geohashgrid-aggregation.asciidoc

@@ -38,17 +38,17 @@ PUT /museums
 
 POST /museums/_bulk?refresh
 {"index":{"_id":1}}
-{"location": "52.374081,4.912350", "name": "NEMO Science Museum"}
+{"location": "POINT (4.912350 52.374081)", "name": "NEMO Science Museum"}
 {"index":{"_id":2}}
-{"location": "52.369219,4.901618", "name": "Museum Het Rembrandthuis"}
+{"location": "POINT (4.901618 52.369219)", "name": "Museum Het Rembrandthuis"}
 {"index":{"_id":3}}
-{"location": "52.371667,4.914722", "name": "Nederlands Scheepvaartmuseum"}
+{"location": "POINT (4.914722 52.371667)", "name": "Nederlands Scheepvaartmuseum"}
 {"index":{"_id":4}}
-{"location": "51.222900,4.405200", "name": "Letterenhuis"}
+{"location": "POINT (4.405200 51.222900)", "name": "Letterenhuis"}
 {"index":{"_id":5}}
-{"location": "48.861111,2.336389", "name": "Musée du Louvre"}
+{"location": "POINT (2.336389 48.861111)", "name": "Musée du Louvre"}
 {"index":{"_id":6}}
-{"location": "48.860000,2.327000", "name": "Musée d'Orsay"}
+{"location": "POINT (2.327000 48.860000)", "name": "Musée d'Orsay"}
 
 POST /museums/_search?size=0
 {
@@ -104,8 +104,8 @@ POST /museums/_search?size=0
       "filter": {
         "geo_bounding_box": {
           "location": {
-            "top_left": "52.4, 4.9",
-            "bottom_right": "52.3, 5.0"
+            "top_left": "POINT (4.9 52.4)",
+            "bottom_right": "POINT (5.0 52.3)"
           }
         }
       },
@@ -218,8 +218,8 @@ POST /museums/_search?size=0
         "field": "location",
         "precision": 8,
         "bounds": {
-          "top_left": "53.4375, 4.21875",
-          "bottom_right": "52.03125, 5.625"
+          "top_left": "POINT (4.21875 53.4375)",
+          "bottom_right": "POINT (5.625 52.03125)"
         }
       }
     }

docs/reference/aggregations/bucket/geohexgrid-aggregation.asciidoc

@@ -40,17 +40,17 @@ PUT /museums
 
 POST /museums/_bulk?refresh
 {"index":{"_id":1}}
-{"location": "52.374081,4.912350", "name": "NEMO Science Museum"}
+{"location": "POINT (4.912350 52.374081)", "name": "NEMO Science Museum"}
 {"index":{"_id":2}}
-{"location": "52.369219,4.901618", "name": "Museum Het Rembrandthuis"}
+{"location": "POINT (4.901618 52.369219)", "name": "Museum Het Rembrandthuis"}
 {"index":{"_id":3}}
-{"location": "52.371667,4.914722", "name": "Nederlands Scheepvaartmuseum"}
+{"location": "POINT (4.914722 52.371667)", "name": "Nederlands Scheepvaartmuseum"}
 {"index":{"_id":4}}
-{"location": "51.222900,4.405200", "name": "Letterenhuis"}
+{"location": "POINT (4.405200 51.222900)", "name": "Letterenhuis"}
 {"index":{"_id":5}}
-{"location": "48.861111,2.336389", "name": "Musée du Louvre"}
+{"location": "POINT (2.336389 48.861111)", "name": "Musée du Louvre"}
 {"index":{"_id":6}}
-{"location": "48.860000,2.327000", "name": "Musée d'Orsay"}
+{"location": "POINT (2.327000 48.860000)", "name": "Musée d'Orsay"}
 
 POST /museums/_search?size=0
 {
@@ -110,8 +110,8 @@ POST /museums/_search?size=0
       "filter": {
         "geo_bounding_box": {
           "location": {
-            "top_left": "52.4, 4.9",
-            "bottom_right": "52.3, 5.0"
+            "top_left": "POINT (4.9 52.4)",
+            "bottom_right": "POINT (5.0 52.3)"
           }
         }
       },
@@ -182,8 +182,8 @@ POST /museums/_search?size=0
         "field": "location",
         "precision": 12,
         "bounds": {
-          "top_left": "52.4, 4.9",
-          "bottom_right": "52.3, 5.0"
+          "top_left": "POINT (4.9 52.4)",
+          "bottom_right": "POINT (5.0 52.3)"
         }
       }
     }

docs/reference/aggregations/bucket/geotilegrid-aggregation.asciidoc

@@ -49,17 +49,17 @@ PUT /museums
 
 POST /museums/_bulk?refresh
 {"index":{"_id":1}}
-{"location": "52.374081,4.912350", "name": "NEMO Science Museum"}
+{"location": "POINT (4.912350 52.374081)", "name": "NEMO Science Museum"}
 {"index":{"_id":2}}
-{"location": "52.369219,4.901618", "name": "Museum Het Rembrandthuis"}
+{"location": "POINT (4.901618 52.369219)", "name": "Museum Het Rembrandthuis"}
 {"index":{"_id":3}}
-{"location": "52.371667,4.914722", "name": "Nederlands Scheepvaartmuseum"}
+{"location": "POINT (4.914722 52.371667)", "name": "Nederlands Scheepvaartmuseum"}
 {"index":{"_id":4}}
-{"location": "51.222900,4.405200", "name": "Letterenhuis"}
+{"location": "POINT (4.405200 51.222900)", "name": "Letterenhuis"}
 {"index":{"_id":5}}
-{"location": "48.861111,2.336389", "name": "Musée du Louvre"}
+{"location": "POINT (2.336389 48.861111)", "name": "Musée du Louvre"}
 {"index":{"_id":6}}
-{"location": "48.860000,2.327000", "name": "Musée d'Orsay"}
+{"location": "POINT (2.327000 48.860000)", "name": "Musée d'Orsay"}
 
 POST /museums/_search?size=0
 {
@@ -118,8 +118,8 @@ POST /museums/_search?size=0
       "filter": {
         "geo_bounding_box": {
           "location": {
-            "top_left": "52.4, 4.9",
-            "bottom_right": "52.3, 5.0"
+            "top_left": "POINT (4.9 52.4)",
+            "bottom_right": "POINT (5.0 52.3)"
           }
         }
       },
@@ -187,8 +187,8 @@ POST /museums/_search?size=0
         "field": "location",
         "precision": 22,
         "bounds": {
-          "top_left": "52.4, 4.9",
-          "bottom_right": "52.3, 5.0"
+          "top_left": "POINT (4.9 52.4)",
+          "bottom_right": "POINT (5.0 52.3)"
         }
       }
     }

docs/reference/aggregations/metrics/geobounds-aggregation.asciidoc

@@ -23,17 +23,17 @@ PUT /museums
 
 POST /museums/_bulk?refresh
 {"index":{"_id":1}}
-{"location": "52.374081,4.912350", "name": "NEMO Science Museum"}
+{"location": "POINT (4.912350 52.374081)", "name": "NEMO Science Museum"}
 {"index":{"_id":2}}
-{"location": "52.369219,4.901618", "name": "Museum Het Rembrandthuis"}
+{"location": "POINT (4.901618 52.369219)", "name": "Museum Het Rembrandthuis"}
 {"index":{"_id":3}}
-{"location": "52.371667,4.914722", "name": "Nederlands Scheepvaartmuseum"}
+{"location": "POINT (4.914722 52.371667)", "name": "Nederlands Scheepvaartmuseum"}
 {"index":{"_id":4}}
-{"location": "51.222900,4.405200", "name": "Letterenhuis"}
+{"location": "POINT (4.405200 51.222900)", "name": "Letterenhuis"}
 {"index":{"_id":5}}
-{"location": "48.861111,2.336389", "name": "Musée du Louvre"}
+{"location": "POINT (2.336389 48.861111)", "name": "Musée du Louvre"}
 {"index":{"_id":6}}
-{"location": "48.860000,2.327000", "name": "Musée d'Orsay"}
+{"location": "POINT (2.327000 48.860000)", "name": "Musée d'Orsay"}
 
 POST /museums/_search?size=0
 {

docs/reference/aggregations/metrics/geocentroid-aggregation.asciidoc

@@ -23,17 +23,17 @@ PUT /museums
 
 POST /museums/_bulk?refresh
 {"index":{"_id":1}}
-{"location": "52.374081,4.912350", "city": "Amsterdam", "name": "NEMO Science Museum"}
+{"location": "POINT (4.912350 52.374081)", "city": "Amsterdam", "name": "NEMO Science Museum"}
 {"index":{"_id":2}}
-{"location": "52.369219,4.901618", "city": "Amsterdam", "name": "Museum Het Rembrandthuis"}
+{"location": "POINT (4.901618 52.369219)", "city": "Amsterdam", "name": "Museum Het Rembrandthuis"}
 {"index":{"_id":3}}
-{"location": "52.371667,4.914722", "city": "Amsterdam", "name": "Nederlands Scheepvaartmuseum"}
+{"location": "POINT (4.914722 52.371667)", "city": "Amsterdam", "name": "Nederlands Scheepvaartmuseum"}
 {"index":{"_id":4}}
-{"location": "51.222900,4.405200", "city": "Antwerp", "name": "Letterenhuis"}
+{"location": "POINT (4.405200 51.222900)", "city": "Antwerp", "name": "Letterenhuis"}
 {"index":{"_id":5}}
-{"location": "48.861111,2.336389", "city": "Paris", "name": "Musée du Louvre"}
+{"location": "POINT (2.336389 48.861111)", "city": "Paris", "name": "Musée du Louvre"}
 {"index":{"_id":6}}
-{"location": "48.860000,2.327000", "city": "Paris", "name": "Musée d'Orsay"}
+{"location": "POINT (2.327000 48.860000)", "city": "Paris", "name": "Musée d'Orsay"}
 
 POST /museums/_search?size=0
 {

docs/reference/aggregations/metrics/top-metrics-aggregation.asciidoc

@@ -62,7 +62,7 @@ request. So,
 
 `"sort": {"s": "desc"}`:: gets metrics from the document with the highest `s`
 `"sort": {"s": "asc"}`:: gets the metrics from the document with the lowest `s`
-`"sort": {"_geo_distance": {"location": "35.7796, -78.6382"}}`::
+`"sort": {"_geo_distance": {"location": "POINT (-78.6382 35.7796)"}}`::
   gets metrics from the documents with `location` *closest* to `35.7796, -78.6382`
 `"sort": "_score"`:: gets metrics from the document with the highest score
 

docs/reference/mapping/types/geo-point.asciidoc

@@ -14,7 +14,10 @@ Fields of type `geo_point` accept latitude-longitude pairs, which can be used:
 * to integrate distance into a document's <<query-dsl-function-score-query,relevance score>>.
 * to <<geo-sorting,sort>> documents by distance.
 
-There are six ways that a geopoint may be specified, as demonstrated below:
+As with <<geo-shape, geo_shape>> and <<point, point>>, `geo_point` can be specified in http://geojson.org[GeoJSON]
+and https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text] formats.
+However, there are a number of additional formats that are supported for convenience and historical reasons.
+In total there are six ways that a geopoint may be specified, as demonstrated below:
 
 [source,console]
 --------------------------------------------------
@@ -31,44 +34,44 @@ PUT my-index-000001
 
 PUT my-index-000001/_doc/1
 {
-  "text": "Geopoint as an object with 'lat' and 'lon' keys",
+  "text": "Geopoint as an object using GeoJSON format",
   "location": { <1>
-    "lat": 41.12,
-    "lon": -71.34
+    "type": "Point",
+    "coordinates": [-71.34, 41.12]
   }
 }
 
 PUT my-index-000001/_doc/2
 {
-  "text": "Geopoint as an object using GeoJSON format",
-  "location": { <2>
-    "type": "Point",
-    "coordinates": [-71.34, 41.12]
-  }
+  "text": "Geopoint as a WKT POINT primitive",
+  "location" : "POINT (-71.34 41.12)" <2>
 }
 
 PUT my-index-000001/_doc/3
 {
-  "text": "Geopoint as a string",
-  "location": "41.12,-71.34" <3>
+  "text": "Geopoint as an object with 'lat' and 'lon' keys",
+  "location": { <3>
+    "lat": 41.12,
+    "lon": -71.34
+  }
 }
 
 PUT my-index-000001/_doc/4
 {
-  "text": "Geopoint as a geohash",
-  "location": "drm3btev3e86" <4>
+  "text": "Geopoint as an array",
+  "location": [ -71.34, 41.12 ] <4>
 }
 
 PUT my-index-000001/_doc/5
 {
-  "text": "Geopoint as an array",
-  "location": [ -71.34, 41.12 ] <5>
+  "text": "Geopoint as a string",
+  "location": "41.12,-71.34" <5>
 }
 
 PUT my-index-000001/_doc/6
 {
-  "text": "Geopoint as a WKT POINT primitive",
-  "location" : "POINT (-71.34 41.12)" <6>
+  "text": "Geopoint as a geohash",
+  "location": "drm3btev3e86" <6>
 }
 
 GET my-index-000001/_search
@@ -90,13 +93,13 @@ GET my-index-000001/_search
 }
 --------------------------------------------------
 
-<1> Geopoint expressed as an object, with `lat` and `lon` keys.
-<2> Geopoint expressed as an object, in https://geojson.org/[GeoJSON] format, with `type` and `coordinates` keys.
-<3> Geopoint expressed as a string with the format: `"lat,lon"`.
-<4> Geopoint expressed as a geohash.
-<5> Geopoint expressed as an array with the format: [ `lon`, `lat`]
-<6> Geopoint expressed as a https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
+<1> Geopoint expressed as an object, in https://geojson.org/[GeoJSON] format, with `type` and `coordinates` keys.
+<2> Geopoint expressed as a https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
 POINT with the format: `"POINT(lon lat)"`
+<3> Geopoint expressed as an object, with `lat` and `lon` keys.
+<4> Geopoint expressed as an array with the format: [ `lon`, `lat`]
+<5> Geopoint expressed as a string with the format: `"lat,lon"`.
+<6> Geopoint expressed as a geohash.
 <7> A geo-bounding box query which finds all geopoints that fall inside the box.
 
 [IMPORTANT]

docs/reference/mapping/types/point.asciidoc

@@ -12,7 +12,10 @@ coordinate system.
 You can query documents using this type using
 <<query-dsl-shape-query,shape Query>>.
 
-There are five ways that a point may be specified, as demonstrated below:
+As with <<geo-shape, geo_shape>> and <<geo-point, geo_point>>, `point` can be specified in http://geojson.org[GeoJSON]
+and https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text] formats.
+However, there are a number of additional formats that are supported for convenience and historical reasons.
+In total there are five ways that a cartesian point may be specified, as demonstrated below:
 
 [source,console]
 --------------------------------------------------
@@ -29,26 +32,26 @@ PUT my-index-000001
 
 PUT my-index-000001/_doc/1
 {
-  "text": "Point as an object with 'x' and 'y' keys",
+  "text": "Point as an object using GeoJSON format",
   "location": { <1>
-    "x": -71.34,
-    "y": 41.12
+    "type": "Point",
+    "coordinates": [-71.34, 41.12]
   }
 }
 
 PUT my-index-000001/_doc/2
 {
-  "text": "Point as an object using GeoJSON format",
-  "location": { <2>
-    "type": "Point",
-    "coordinates": [-71.34, 41.12]
-  }
+  "text": "Point as a WKT POINT primitive",
+  "location" : "POINT (-71.34 41.12)" <2>
 }
 
 PUT my-index-000001/_doc/3
 {
-  "text": "Point as a string",
-  "location": "-71.34,41.12" <3>
+  "text": "Point as an object with 'x' and 'y' keys",
+  "location": { <3>
+    "x": -71.34,
+    "y": 41.12
+  }
 }
 
 PUT my-index-000001/_doc/4
@@ -59,18 +62,18 @@ PUT my-index-000001/_doc/4
 
 PUT my-index-000001/_doc/5
 {
-  "text": "Point as a WKT POINT primitive",
-  "location" : "POINT (-71.34 41.12)" <5>
+  "text": "Point as a string",
+  "location": "-71.34,41.12" <5>
 }
 
 --------------------------------------------------
 
-<1> Point expressed as an object, with `x` and `y` keys.
-<2> Point expressed as an object, in https://geojson.org/[GeoJSON] format, with `type` and `coordinates` keys.
-<3> Point expressed as a string with the format: `"x,y"`.
-<4> Point expressed as an array with the format: [ `x`, `y`]
-<5> Point expressed as a https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
+<1> Point expressed as an object, in https://geojson.org/[GeoJSON] format, with `type` and `coordinates` keys.
+<2> Point expressed as a https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
 POINT with the format: `"POINT(x y)"`
+<3> Point expressed as an object, with `x` and `y` keys.
+<4> Point expressed as an array with the format: [ `x`, `y`]
+<5> Point expressed as a string with the format: `"x,y"`.
 
 [NOTE]
 Unlike the case with the {ref}/geo-point.html[geo-point] field type,

docs/reference/query-dsl/geo-bounding-box-query.asciidoc

@@ -254,8 +254,8 @@ GET my_locations/_search
       "filter": {
         "geo_bounding_box": {
           "pin.location": {
-            "top_left": "40.73, -74.1",
-            "bottom_right": "40.01, -71.12"
+            "top_left": "POINT (-74.1 40.73)",
+            "bottom_right": "POINT (-71.12 40.01)"
           }
         }
       }

docs/reference/query-dsl/geo-distance-query.asciidoc

@@ -205,9 +205,9 @@ GET /my_locations/_search
 
 
 [discrete]
-===== Lat Lon As String
+===== Lat Lon As WKT String
 
-Format in `lat,lon`.
+Format in https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text].
 
 [source,console]
 --------------------------------------------------
@@ -221,7 +221,7 @@ GET /my_locations/_search
       "filter": {
         "geo_distance": {
           "distance": "12km",
-          "pin.location": "40,-70"
+          "pin.location": "POINT (-70 40)"
         }
       }
     }

docs/reference/search/search-vector-tile-api.asciidoc

@@ -24,7 +24,7 @@ PUT my-index
 
 PUT my-index/_doc/0?refresh
 {
-  "my-geo-field": "37.3864953,-122.0863176"
+  "my-geo-field": "POINT (-122.0863176 37.3864953)"
 }
 ----
 ////
@@ -689,13 +689,13 @@ PUT museums
 
 POST museums/_bulk?refresh
 { "index": { "_id": "1" } }
-{ "location": "52.374081,4.912350", "name": "NEMO Science Museum",  "price": 1750, "included": true }
+{ "location": "POINT (4.912350 52.374081)", "name": "NEMO Science Museum",  "price": 1750, "included": true }
 { "index": { "_id": "2" } }
-{ "location": "52.369219,4.901618", "name": "Museum Het Rembrandthuis", "price": 1500, "included": false }
+{ "location": "POINT (4.901618 52.369219)", "name": "Museum Het Rembrandthuis", "price": 1500, "included": false }
 { "index": { "_id": "3" } }
-{ "location": "52.371667,4.914722", "name": "Nederlands Scheepvaartmuseum", "price":1650, "included": true }
+{ "location": "POINT (4.914722 52.371667)", "name": "Nederlands Scheepvaartmuseum", "price":1650, "included": true }
 { "index": { "_id": "4" } }
-{ "location": "52.371667,4.914722", "name": "Amsterdam Centre for Architecture", "price":0, "included": true }
+{ "location": "POINT (4.914722 52.371667)", "name": "Amsterdam Centre for Architecture", "price":0, "included": true }
 ----
 
 The following request searches the index for `location` values that intersect

docs/reference/search/search-your-data/sort-search-results.asciidoc

@@ -491,9 +491,9 @@ GET /_search
 --------------------------------------------------
 
 [discrete]
-==== Lat Lon as String
+==== Lat Lon as WKT String
 
-Format in `lat,lon`.
+Format in https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text].
 
 [source,console]
 --------------------------------------------------
@@ -502,7 +502,7 @@ GET /_search
   "sort": [
     {
       "_geo_distance": {
-        "pin.location": "40,-70",
+        "pin.location": "POINT (-70 40)",
         "order": "asc",
         "unit": "km"
       }

rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search.aggregation/340_geo_distance.yml

@@ -29,7 +29,7 @@ setup:
             distance:
               geo_distance:
                 field: location
-                origin: "35.7796, -78.6382"
+                origin: "POINT (-78.6382 35.7796)"
                 ranges:
                   - to: 1000000
                   - from: 1000000
@@ -57,7 +57,7 @@ setup:
             distance:
               geo_distance:
                 field: location
-                origin: "35.7796, -78.6382"
+                origin: "POINT (-78.6382 35.7796)"
                 ranges:
                   - to: 1000000
                   - from: 1000000

server/src/test/java/org/elasticsearch/index/query/GeoBoundingBoxQueryBuilderTests.java

@@ -31,9 +31,10 @@ import static org.hamcrest.CoreMatchers.containsString;
 import static org.hamcrest.CoreMatchers.instanceOf;
 import static org.hamcrest.CoreMatchers.notNullValue;
 
+@SuppressWarnings("checkstyle:MissingJavadocMethod")
 public class GeoBoundingBoxQueryBuilderTests extends AbstractQueryTestCase<GeoBoundingBoxQueryBuilder> {
     /** Randomly generate either NaN or one of the two infinity values. */
-    private static Double[] brokenDoubles = { Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY };
+    private static final Double[] brokenDoubles = { Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY };
 
     @Override
     protected GeoBoundingBoxQueryBuilder doCreateTestQueryBuilder() {
@@ -117,11 +118,9 @@ public class GeoBoundingBoxQueryBuilderTests extends AbstractQueryTestCase<GeoBo
         PointTester[] testers = { new TopTester(), new LeftTester(), new BottomTester(), new RightTester() };
 
         for (PointTester tester : testers) {
-            QueryValidationException except = null;
-
             GeoBoundingBoxQueryBuilder builder = createTestQueryBuilder();
             tester.invalidateCoordinate(builder.setValidationMethod(GeoValidationMethod.COERCE), false);
-            except = builder.checkLatLon();
+            QueryValidationException except = builder.checkLatLon();
             assertNull(
                 "validation w/ coerce should ignore invalid "
                     + tester.getClass().getName()
@@ -237,15 +236,15 @@ public class GeoBoundingBoxQueryBuilderTests extends AbstractQueryTestCase<GeoBo
         }
     }
 
-    public abstract class PointTester {
-        private double brokenCoordinate = randomFrom(brokenDoubles);
-        private double invalidCoordinate;
+    private abstract static class PointTester {
+        private final double brokenCoordinate = randomFrom(brokenDoubles);
+        private final double invalidCoordinate;
 
-        public PointTester(double invalidCoodinate) {
+        private PointTester(double invalidCoodinate) {
             this.invalidCoordinate = invalidCoodinate;
         }
 
-        public void invalidateCoordinate(GeoBoundingBoxQueryBuilder qb, boolean useBrokenDouble) {
+        private void invalidateCoordinate(GeoBoundingBoxQueryBuilder qb, boolean useBrokenDouble) {
             if (useBrokenDouble) {
                 fillIn(brokenCoordinate, qb);
             } else {
@@ -256,8 +255,8 @@ public class GeoBoundingBoxQueryBuilderTests extends AbstractQueryTestCase<GeoBo
         protected abstract void fillIn(double fillIn, GeoBoundingBoxQueryBuilder qb);
     }
 
-    public class TopTester extends PointTester {
-        public TopTester() {
+    private static class TopTester extends PointTester {
+        private TopTester() {
             super(randomDoubleBetween(GeoUtils.MAX_LAT, Double.MAX_VALUE, false));
         }
 
@@ -267,8 +266,8 @@ public class GeoBoundingBoxQueryBuilderTests extends AbstractQueryTestCase<GeoBo
         }
     }
 
-    public class LeftTester extends PointTester {
-        public LeftTester() {
+    private static class LeftTester extends PointTester {
+        private LeftTester() {
             super(randomDoubleBetween(-Double.MAX_VALUE, GeoUtils.MIN_LON, true));
         }
 
@@ -278,8 +277,8 @@ public class GeoBoundingBoxQueryBuilderTests extends AbstractQueryTestCase<GeoBo
         }
     }
 
-    public class BottomTester extends PointTester {
-        public BottomTester() {
+    private static class BottomTester extends PointTester {
+        private BottomTester() {
             super(randomDoubleBetween(-Double.MAX_VALUE, GeoUtils.MIN_LAT, false));
         }
 
@@ -289,8 +288,8 @@ public class GeoBoundingBoxQueryBuilderTests extends AbstractQueryTestCase<GeoBo
         }
     }
 
-    public class RightTester extends PointTester {
-        public RightTester() {
+    private static class RightTester extends PointTester {
+        private RightTester() {
             super(randomDoubleBetween(GeoUtils.MAX_LON, Double.MAX_VALUE, true));
         }
 
@@ -300,6 +299,40 @@ public class GeoBoundingBoxQueryBuilderTests extends AbstractQueryTestCase<GeoBo
         }
     }
 
+    public void testParsingAndToQueryGeoJSON() throws IOException {
+        String query = """
+            {
+                "geo_bounding_box":{
+                    "%s":{
+                        "top_left":{
+                          "type":"Point",
+                          "coordinates":[-70, 40]
+                        },
+                        "bottom_right":{
+                          "type":"Point",
+                          "coordinates":[-80, 30]
+                        }
+                    }
+                }
+            }
+            """.formatted(GEO_POINT_FIELD_NAME);
+        assertGeoBoundingBoxQuery(query);
+    }
+
+    public void testParsingAndToQueryWKT() throws IOException {
+        String query = """
+            {
+                "geo_bounding_box":{
+                    "%s":{
+                        "top_left":"POINT(-70 40)",
+                        "bottom_right":"POINT(-80 30)"
+                    }
+                }
+            }
+            """.formatted(GEO_POINT_FIELD_NAME);
+        assertGeoBoundingBoxQuery(query);
+    }
+
     public void testParsingAndToQuery1() throws IOException {
         String query = """
             {

server/src/test/java/org/elasticsearch/index/query/GeoDistanceQueryBuilderTests.java

@@ -30,6 +30,7 @@ import static org.hamcrest.CoreMatchers.containsString;
 import static org.hamcrest.CoreMatchers.instanceOf;
 import static org.hamcrest.CoreMatchers.notNullValue;
 
+@SuppressWarnings("checkstyle:MissingJavadocMethod")
 public class GeoDistanceQueryBuilderTests extends AbstractQueryTestCase<GeoDistanceQueryBuilder> {
 
     @Override
@@ -131,6 +132,35 @@ public class GeoDistanceQueryBuilderTests extends AbstractQueryTestCase<GeoDista
         }
     }
 
+    @AwaitsFix(bugUrl = "https://github.com/elastic/elasticsearch/issues/86834")
+    public void testParsingAndToQueryGeoJSON() throws IOException {
+        // TODO: GeoJSON support missing for geo_distance query, although all other point formats work
+        String query = """
+            {
+                "geo_distance":{
+                    "distance":"12mi",
+                    "%s":{
+                        "type": "Point",
+                        "coordinates": [-70,40]
+                    }
+                }
+            }
+            """.formatted(GEO_POINT_FIELD_NAME);
+        assertGeoDistanceRangeQuery(query, 40, -70, 12, DistanceUnit.MILES);
+    }
+
+    public void testParsingAndToQueryWKT() throws IOException {
+        String query = """
+            {
+                "geo_distance":{
+                    "distance":"12mi",
+                    "%s":"POINT(-70 40)"
+                }
+            }
+            """.formatted(GEO_POINT_FIELD_NAME);
+        assertGeoDistanceRangeQuery(query, 40, -70, 12, DistanceUnit.MILES);
+    }
+
     public void testParsingAndToQuery1() throws IOException {
         String query = """
             {

server/src/test/java/org/elasticsearch/search/sort/SortBuilderTests.java

@@ -106,7 +106,7 @@ public class SortBuilderTests extends ESTestCase {
         assertEquals(new GeoDistanceSortBuilder("pin.location", 40, -70), sortBuilder);
 
         json = """
-            { "sort" : [{"_geo_distance" : {"pin.location" : "40,-70" } }] }""";
+            { "sort" : [{"_geo_distance" : {"pin.location" : "POINT (-70 40)" } }] }""";
         result = parseSort(json);
         assertEquals(1, result.size());
         sortBuilder = result.get(0);
@@ -210,7 +210,7 @@ public class SortBuilderTests extends ESTestCase {
                 },
                 {
                   "_geo_distance": {
-                    "pin.location": "40,-70"
+                    "pin.location": "POINT (-70 40)"
                   }
                 },
                 "_score"

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/analytics/top_metrics.yml

@@ -326,7 +326,7 @@
                   field: population
                 sort:
                   _geo_distance:
-                    location: "35.7796, -78.6382"
+                    location: "POINT (-78.6382 35.7796)"
   - match: { aggregations.pop.top.0.metrics.population: 8623000 }
   - match: { aggregations.pop.top.0.sort: [681335.0456554737] }
 
@@ -343,7 +343,7 @@
                   field: population
                 sort:
                   _geo_distance:
-                    location: "35.7796, -78.6382"
+                    location: "POINT (-78.6382 35.7796)"
   - match: { aggregations.pop.top.0.metrics.population: 8623000 }
   - match: { aggregations.pop.top.0.sort: [681335.0456554737] }
   - match: { aggregations.pop.top.1.metrics.population: 2716000 }

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/spatial/80_geohex_grid.yml

@@ -135,8 +135,8 @@ setup:
               geohex_grid:
                 field: location
                 bounds:
-                  top_left: "52.4, 4.9"
-                  bottom_right: "52.3, 5.0"
+                  top_left: "POINT (4.9 52.4)"
+                  bottom_right: "POINT (5.0 52.3)"
   - match: {hits.total.value:      6    }
   - length: { aggregations.grid.buckets: 1 }
   - match: { aggregations.grid.buckets.0.key: "85196953fffffff" }