76_Querying_geo_shapes.asciidoc

Querying geo-shapes

The unusual thing about the geo_shape query and geo_shape filter is that they allow us to query using shapes, rather than just points.

For instance, if our user steps out of the central train station in Amsterdam, we could find all landmarks within a 1km radius with a query like this:

GET /attractions/landmark/_search
{
  "query": {
    "geo_shape": {
      "location": { (1)
        "shape": { (2)
          "type":   "circle", (3)
          "radius": "1km"
          "coordinates": [ (4)
            4.89994,
            52.37815
          ]
        }
      }
    }
  }
}

1. The query looks at geo-shapes in the location field.

2. The shape key indicates that the shape is specified inline in the query.

3. The shape is a circle, with a radius of 1km.

4. This point is situated at the entrance of the central train station in Amsterdam.

By default, the query (or filter—​do the same job) looks for indexed shapes that intersect with the query shape. The relation parameter can be set to disjoint to find indexed shapes that don’t intersect with the query shape, or within to find indexed shapes that are completely contained by the query shape.

For instance, we could find all landmarks in the center of Amsterdam with this query:

GET /attractions/landmark/_search
{
  "query": {
    "geo_shape": {
      "location": {
        "relation": "within", (1)
        "shape": {
          "type": "polygon",
          "coordinates": [[ (2)
              [4.88330,52.38617],
              [4.87463,52.37254],
              [4.87875,52.36369],
              [4.88939,52.35850],
              [4.89840,52.35755],
              [4.91909,52.36217],
              [4.92656,52.36594],
              [4.93368,52.36615],
              [4.93342,52.37275],
              [4.92690,52.37632],
              [4.88330,52.38617]
            ]]
        }
      }
    }
  }
}

1. Match only indexed shapes that are completely within the query shape.

2. This polygon represents the center of Amsterdam.