For AI agents: this page is also available as Markdown at /docs/geo-search.md. Every docs page is: add .md to its URL. llms.txt lists them all.

Geo search

Geo search finds documents by where they are. A location is a geo_point field and an area or route is a geo_shape field. A geo condition is a query like any other: a filter beside a text query ("coffee within 5 km"), the whole query ("everything in this polygon"), a sort key ("nearest first"), a scoring signal ("prefer closer results") or an aggregation ("matches per map cell"). It runs in the same request, over the same consistent view of the collection, as your text queries, filters and facets.

#What you can do

#Pages in this guide

• Geo points and queries: defining geo_point fields, the point formats you can send, and the distance, box, polygon, shape and grid-cell queries.
• Distance sorting and nearest: sorting by distance, boosting nearby results, nearest-k search and distance_feature scoring.
• Geo aggregations: grids, distance rings, bounds, centroids and query buckets.
• Geo shapes: geo_shape fields for areas and lines, their queries and aggregations, and the accuracy and index size settings.

#Which API to use

Geo queries have no form in Lucene syntax or SQL. Write them as Elasticsearch Query DSL, or use Solr's spatial parameters:

The MCP search tool takes the same geo queries, facets, metrics and sort; see Guide for AI agents. Searches with geo queries have no native replay form; see Native queries and replays.

#Choosing a feature

• Show only nearby results: a distance, box or polygon query in filters. Filters do not change scores, so text relevance still orders the hits.
• Show the closest first: a filter to bound the area, plus a sort by distance.
• Rank by relevance, but prefer closer: a decay function in function_score, or a distance_feature clause beside the text query.
• "The 5 nearest", whatever the distance: geo_nearest. Until it is live, filter by a generous radius and sort by distance.
• "How many within 1, 5 and 10 km": distance rings, or query buckets today.
• A heat map or clustered map markers: a grid aggregation, then a geo_grid query to fetch the documents of the cell someone clicks.
• Areas, not points (delivery zones, regions, routes): a geo_shape field.

#Quickstart

The examples in this guide use one collection, places: cafes, shops and bakeries around New York, each with a location. Geo shapes adds a delivery area to some of them.

Create the collection with a geo_point field. index: "range" builds a points index, which makes distance and box queries fast on large collections:

curl -X PUT https://api.warpsearch.io/v1/collections/places \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "fields": {
        "name":        "text",
        "description": "text",
        "category":    "string",
        "city":        "string",
        "rating":      "double",
        "location":    {"type": "geo_point", "index": "range"}
      }
    }
  }'

Load a few places. A point is [longitude, latitude], longitude first:

curl -X POST "https://api.warpsearch.io/v1/collections/places/documents?commit=true" \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"id": "p1", "name": "Harbor Coffee", "description": "Espresso, pour-over and pastries",
     "category": "cafe", "city": "Manhattan", "rating": 4.6, "location": [-73.9851, 40.7589]},
    {"id": "p2", "name": "Bridge Roasters", "description": "Coffee roastery with a cafe under the bridge",
     "category": "cafe", "city": "Brooklyn", "rating": 4.4, "location": [-73.9897, 40.7033]},
    {"id": "p3", "name": "Midtown Market", "description": "Groceries, deli and a coffee bar",
     "category": "grocery", "city": "Manhattan", "rating": 4.1, "location": [-73.9772, 40.7527]},
    {"id": "p4", "name": "Astoria Bakery", "description": "Bread, pastries and coffee",
     "category": "bakery", "city": "Queens", "rating": 4.7, "location": [-73.9235, 40.7644]},
    {"id": "p5", "name": "Hudson Espresso", "description": "Espresso bar by the ferry",
     "category": "cafe", "city": "Hoboken", "rating": 4.5, "location": [-74.0324, 40.7440]}
  ]'

Find the cafes within 5 km of Times Square (40.7580, -73.9855), nearest first:

curl -X POST https://api.warpsearch.io/v1/collections/places/search \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "es",
    "query": {
      "query": {"bool": {"filter": [
        {"term": {"category": "cafe"}},
        {"geo_distance": {"distance": "5km", "location": "40.7580,-73.9855"}}
      ]}},
      "sort": [{"_geo_distance": {"location": "40.7580,-73.9855", "order": "asc", "unit": "km"}}]
    },
    "fields": ["name", "city"]
  }'

curl -X POST https://api.warpsearch.io/compat/es/places/_search \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {"bool": {"filter": [
      {"term": {"category": "cafe"}},
      {"geo_distance": {"distance": "5km", "location": "40.7580,-73.9855"}}
    ]}},
    "sort": [{"_geo_distance": {"location": "40.7580,-73.9855", "order": "asc", "unit": "km"}}],
    "_source": ["name", "city"]
  }'

curl "https://api.warpsearch.io/compat/solr/places/select" \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  --data-urlencode "q=*:*" \
  --data-urlencode "fq=category:cafe" \
  --data-urlencode "fq={!geofilt sfield=location pt=40.7580,-73.9855 d=5}" \
  --data-urlencode "sort=geodist(location,40.7580,-73.9855) asc" \
  --data-urlencode "fl=id,name,city"

The hits are p1 (Harbor Coffee, about 0.1 km away), then p5 (Hudson Espresso, about 4.2 km). Bridge Roasters, 6.1 km away, is outside the radius.

#Limits

These apply to geo queries and aggregations:

Going past a limit answers 422 limit_exceeded, except the distinct-cell count, which fails the search with an error. See Limits and errors.

Distances are great-circle (haversine) distances. Elasticsearch's distance_type: plane is accepted with a warning. Query centers can be "lat,lon", [lon, lat], {"lat": ..., "lon": ...} or "POINT (lon lat)"; geohash centers are rejected.

View this page as Markdown