Example: Enrich your data based on geolocation

geo_match enrich policies match enrich data to incoming documents based on a geographic location, using a geo_shape query.

The following example creates a geo_match enrich policy that adds postal codes to incoming documents based on a set of coordinates. It then adds the geo_match enrich policy to a processor in an ingest pipeline.

Use the create index API to create a source index containing at least one geo_shape field.

  1. PUT /postal_codes
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "location": {
  6.         "type": "geo_shape"
  7.       },
  8.       "postal_code": {
  9.         "type": "keyword"
  10.       }
  11.     }
  12.   }
  13. }

Use the index API to index enrich data to this source index.

  1. PUT /postal_codes/_doc/1?refresh=wait_for
  2. {
  3.   "location": {
  4.     "type": "envelope",
  5.     "coordinates": [ [ 13.0, 53.0 ], [ 14.0, 52.0 ] ]
  6.   },
  7.   "postal_code": "96598"
  8. }

Use the put enrich policy API to create an enrich policy with the geo_match policy type. This policy must include:

  • One or more source indices
  • A match_field, the geo_shape field from the source indices used to match incoming documents
  • Enrich fields from the source indices you’d like to append to incoming documents
  1. PUT /_enrich/policy/postal_policy
  2. {
  3.   "geo_match": {
  4.     "indices": "postal_codes",
  5.     "match_field": "location",
  6.     "enrich_fields": [ "location", "postal_code" ]
  7.   }
  8. }

Use the execute enrich policy API to create an enrich index for the policy.

  1. POST /_enrich/policy/postal_policy/_execute

Use the put pipeline API to create an ingest pipeline. In the pipeline, add an enrich processor that includes:

  • Your enrich policy.
  • The field of incoming documents used to match the geo_shape of documents from the enrich index.
  • The target_field used to store appended enrich data for incoming documents. This field contains the match_field and enrich_fields specified in your enrich policy.
  • The shape_relation, which indicates how the processor matches geo_shapes in incoming documents to geo_shapes in documents from the enrich index. See Spatial Relations for valid options and more information.
  1. PUT /_ingest/pipeline/postal_lookup
  2. {
  3.   "description": "Enrich postal codes",
  4.   "processors": [
  5.     {
  6.       "enrich": {
  7.         "policy_name": "postal_policy",
  8.         "field": "geo_location",
  9.         "target_field": "geo_data",
  10.         "shape_relation": "INTERSECTS"
  11.       }
  12.     }
  13.   ]
  14. }

Use the ingest pipeline to index a document. The incoming document should include the field specified in your enrich processor.

  1. PUT /users/_doc/0?pipeline=postal_lookup
  2. {
  3.   "first_name": "Mardy",
  4.   "last_name": "Brown",
  5.   "geo_location": "POINT (13.5 52.5)"
  6. }

To verify the enrich processor matched and appended the appropriate field data, use the get API to view the indexed document.

  1. GET /users/_doc/0

The API returns the following response:

  1. {
  2.   "found": true,
  3.   "_index": "users",
  4.   "_type": "_doc",
  5.   "_id": "0",
  6.   "_version": 1,
  7.   "_seq_no": 55,
  8.   "_primary_term": 1,
  9.   "_source": {
  10.     "geo_data": {
  11.       "location": {
  12.         "type": "envelope",
  13.         "coordinates": [[13.0, 53.0], [14.0, 52.0]]
  14.       },
  15.       "postal_code": "96598"
  16.     },
  17.     "first_name": "Mardy",
  18.     "last_name": "Brown",
  19.     "geo_location": "POINT (13.5 52.5)"
  20.   }
  21. }