add geojson and geoPolygon documentation

Author: guimachiavelli

.code-samples.meilisearch.yaml

@@ -685,6 +685,11 @@ geosearch_guide_filter_usage_3: |-
     -X POST 'MEILISEARCH_URL/indexes/restaurants/search' \
     -H 'Content-type:application/json' \
     --data-binary '{ "filter": "_geoBoundingBox([45.494181, 9.214024], [45.449484, 9.179175])" }'
+geosearch_guide_filter_usage_4: |-
+  curl \
+    -X POST 'MEILISEARCH_URL/indexes/restaurants/search' \
+    -H 'Content-type:application/json' \
+    --data-binary '{ "filter": "_geoPolygon([45.494181, 9.214024], [45.449484, 9.179175], [45.449486, 9.179177])" }'
 geosearch_guide_sort_settings_1: |-
   curl \
     -X PUT 'MEILISEARCH_URL/indexes/restaurants/settings/sortable-attributes' \

learn/filtering_and_sorting/geosearch.mdx

@@ -21,9 +21,9 @@ Due to Meilisearch allowing malformed `_geo` fields in the following versions (v
 
 ## Preparing documents for location-based search
 
-In order to start filtering and sorting documents based on their geographic location, you must make sure they contain a valid `_geo` field.
+In order to start filtering and sorting documents based on their geographic location, you must make sure they contain a valid `_geo` or `_geojson` field.
 
-`_geo` is a reserved field. If you include it in your documents, Meilisearch expects its value to conform to a specific format.
+`_geo` and `_geojson` are reserved fields. If you include one of them in your documents, Meilisearch expects its value to conform to a specific format.
 
 When using JSON and NDJSON, `_geo` must contain an object with two keys: `lat` and `lng`. Both fields must contain either a floating point number or a string indicating, respectively, latitude and longitude:
 
@@ -37,6 +37,37 @@ When using JSON and NDJSON, `_geo` must contain an object with two keys: `lat` a
 }
 ```
 
+`_geojson` must be an object whose contents follow the [GeoJSON specification](https://geojson.org/):
+
+```json
+{
+  …
+  "_geojson": {
+    "type": "Feature",
+    "geometry": {
+      "type": "Point",
+      "coordinates": [0.0, 0.0]
+    }
+  }
+}
+```
+
+Meilisearch does not support transmeridian shapes. If your document includes a transmeridian shape, split it into two separate shapes grouped as a `MultiPolygon` or `MultiLine`. Transmeridian shapes are polygons that cross the 180th or antimeridian.
+
+Meilisearch does not support polygons with holes. If your polygon consists of an external ring and an inner empty space, Meilisearch ignores the hole and treats the polygon as a solid shape.
+
+<Note>
+### Using `_geo` and `_geojson` together
+
+If your application requires both sorting by distance to a point and filtering by shapes other than a circle or a rectangle, you will need to add both `_geo` and `_geojson` to your documents.
+
+When handling documents with both fields, Meilisearch:
+
+- Ignores `_geojson` values when sorting
+- Ignores `_geo` values when filtering with `_geoPolygon`
+- Matches both `_geo` and `_geojson` values when filtering with `_geoRadius` and `_geoBoundingBox`
+</Note>
+
 ### Examples
 
 Suppose we have a JSON array containing a few restaurants:
@@ -67,7 +98,7 @@ Suppose we have a JSON array containing a few restaurants:
 ]
 ```
 
-Our restaurant dataset looks like this once we add geopositioning data:
+Our restaurant dataset looks like this once we add `_geo` data:
 
 ```json
 [
@@ -122,13 +153,15 @@ If your dataset is formatted as CSV, the file header must have a `_geo` column.
 "3","Artico Gelateria Tradizionale","Via Dogana, 1, 20123 Milan, Italy","ice cream",10,"48.8826517,2.3352748"
 ```
 
-## Filtering results with `_geoRadius` and `_geoBoundingBox`
+CSV files do not support the `_geojson` attribute.
+
+## Filtering results with `_geoRadius`, `_geoBoundingBox`, and `_geoPolygon`
 
-You can use `_geo` data to filter queries so you only receive results located within a given geographic area.
+You can use `_geo` and `_geojson` data to filter queries so you only receive results located within a given geographic area.
 
 ### Configuration
 
-In order to filter results based on their location, you must add the `_geo` attribute to the `filterableAttributes` list:
+To filter results based on their location, you must add `_geo` or `_geojson` to the `filterableAttributes` list:
 
 <CodeSamplesGeosearchGuideFilterSettings1 />
 
@@ -138,7 +171,7 @@ Meilisearch will rebuild your index whenever you update `filterableAttributes`.
 
 ### Usage
 
-Use the [`filter` search parameter](/reference/api/search#filter) along with `_geoRadius` or `_geoBoundingBox`. These are special filter rules that ensure Meilisearch only returns results located within a specific geographic area.
+Use the [`filter` search parameter](/reference/api/search#filter) along with `_geoRadius` and `_geoBoundingBox`. These are special filter rules that ensure Meilisearch only returns results located within a specific geographic area. If you are using GeoJSON for your documents, you may also filter results with `_geoPolygon`.
 
 ### `_geoRadius`
 
@@ -149,7 +182,13 @@ _geoRadius(lat, lng, distance_in_meters)
 ### `_geoBoundingBox`
 
 ```
-_geoBoundingBox([{lat}, {lng}], [{lat}, {lng}])
+_geoBoundingBox([LAT, LNG], [LAT, LNG])
+```
+
+### `_geoPolygon`
+
+```
+_geoPolygon([LAT, LNG], [LAT, LNG], [LAT, LNG], …)
 ```
 
 ### Examples
@@ -162,6 +201,10 @@ We also make a similar query using `_geoBoundingBox`:
 
 <CodeSamplesGeosearchGuideFilterUsage3 />
 
+And with `_geoPolygon`:
+
+<CodeSamplesGeosearchGuideFilterUsage4 />
+
 ```json
 [
   {
@@ -189,7 +232,7 @@ We also make a similar query using `_geoBoundingBox`:
 ]
 ```
 
-It is also possible to combine `_geoRadius` and `_geoBoundingBox` with other filters. We can narrow down our previous search so it only includes pizzerias:
+It is also possible to combine `_geoRadius`, `_geoBoundingBox`, and `_geoPolygon` with other filters. We can narrow down our previous search so it only includes pizzerias:
 
 <CodeSamplesGeosearchGuideFilterUsage2 />
 
@@ -217,11 +260,13 @@ It is also possible to combine `_geoRadius` and `_geoBoundingBox` with other fil
 
 ### Configuration
 
-Before using geosearch for sorting, you must add the `_geo` attribute to the `sortableAttributes` list:
+Before using geosearch for sorting, you must add the `_geo` attribute to the [`sortableAttributes` list](/learn/filtering_and_sorting/sort_search_results):
 
 <CodeSamplesGeosearchGuideSortSettings1 />
 
-[Read more about `sortableAttributes` here.](/learn/filtering_and_sorting/sort_search_results)
+<Danger>
+It is not possible to sort documents based on the `_geojson` attribute.
+</Danger>
 
 ### Usage
 

reference/api/search.mdx

@@ -481,9 +481,9 @@ You can then use the filter in a search query:
 
 <CodeSamplesFacetedSearchWalkthroughFilter1 />
 
-#### Filtering results with `_geoRadius` and `_geoBoundingBox`
+#### Filtering results with `_geoRadius`, `_geoBoundingBox`, and `_geoPolygon`
 
-If your documents contain `_geo` data, you can use the `_geoRadius` and `_geoBoundingBox` built-in filter rules to filter results according to their geographic position.
+If your documents contain `_geo` or `_geojson` data, you can use the following built-in filter rules to filter results according to their geographic position:
 
 <Tabs>
 
@@ -504,17 +504,34 @@ _geoRadius(lat, lng, distance_in_meters)
 `_geoBoundingBox` establishes a rectangular area based on the coordinates for its top right and bottom left corners. This filter rule requires two arrays of geographic coordinates:
 
 ```
-_geoBoundingBox([{lat}, {lng}], [{lat}, {lng}])
+_geoBoundingBox([LAT, LNG], [LAT, LNG])
 ```
 
-`lat` and `lng` should be geographic coordinates expressed as floating point numbers. The first array indicates the top right corner and the second array indicates the bottom left corner of the bounding box.
+`LAT` and `LNG` should be geographic coordinates expressed as floating point numbers. The first array indicates the top right corner and the second array indicates the bottom left corner of the bounding box.
 
 <CodeSamplesGeosearchGuideFilterUsage3 />
 
 Meilisearch will throw an error if the top right corner is under the bottom left corner.
 
 </Tab>
 
+<Tab title="_geoPolygon">
+`_geoPolygon` establishes an area based on the coordinates of the specified points. This filter rule requires three arrays or more arrays of geographic coordinates and can only be used with GeoJSON documents:
+
+```
+_geoPolygon([LAT, LNG], [LAT, LNG], [LAT, LNG], …)
+```
+
+`LAT` and `LNG` should be geographic coordinates expressed as floating point numbers. If your polygon is not closed, Meilisearch will close it automatically. Closed polygons are polygons where the first and last points share the same coordinates.
+
+<CodeSamplesGeosearchGuideFilterUsage4 />
+
+Polygons cannot cross the 180th meridian. If a shape crosses the antimeridian, you must make two polygons and join them using the `AND` filter operator.
+
+`_geoPolygon` is not compatible with documents using only `_geo` data. You must specify a `_geojson` attribute to use `_geoPolygon`.
+
+</Tab>
+
 </Tabs>
 
 If any parameters are invalid or missing, Meilisearch returns an [`invalid_search_filter`](/reference/errors/error_codes#invalid_search_filter) error.
@@ -924,7 +941,7 @@ You can search for science fiction books ordered from cheapest to most expensive
 
 #### Sorting results with `_geoPoint`
 
-When dealing with documents containing geolocation data, you can use `_geoPoint` to sort results based on their distance from a specific geographic location.
+When dealing with documents containing `_geo` data, you can use `_geoPoint` to sort results based on their distance from a specific geographic location.
 
 `_geoPoint` is a sorting function that requires two floating point numbers indicating a location's latitude and longitude. You must also specify whether the sort should be ascending (`asc`) or descending (`desc`):
 
@@ -946,7 +963,9 @@ Queries using `_geoPoint` will always include a `geoDistance` field containing t
 ]
 ```
 
-[You can read more about location-based sorting in our dedicated guide.](/learn/filtering_and_sorting/geosearch#sorting-results-with-_geopoint)
+Geographic sorting is only compatible with documents containing `_geo` data. `_geoPoint` ignores all data in the `_geojson` object.
+
+[You can read more about location-based sorting in the dedicated guide.](/learn/filtering_and_sorting/geosearch#sorting-results-with-_geopoint)
 
 ### Matching strategy