Geo line tool

Introduced 0.13.0

The GeoLineTool, which an agent sees as FindTracks, answers where did it go — a vessel's voyage, a vehicle's route, a device's movement over time.

It returns one ordered path per moving thing, and for each path it says whether that path is the complete set of fixes or was shortened, and how. A track that silently drops points is worse than no track at all, because a shortened route still looks like a route.

The tool is a wrapper over the geo_line aggregation.

Parameters

Parameter	Required	Description
index	Yes	The index to trace.
field	No	The geo_point field holding the fixes. If omitted, the tool discovers one in the index.
group_by	No	The field identifying the moving thing — a vessel ID, a device ID, a vehicle registration. One path is drawn per distinct value.
sort	No	The field that orders points along the path. This is normally a timestamp.
query	No	A query string restricting which documents are traced.
size	No	The maximum number of points in a single path.
tracks	No	How many distinct things to return paths for. Default is 10.
overflow	No	What to do when a path has more points than size allows.

warning

sort decides the order of the path, not just its ranking. Without a meaningful sort field the points are still connected in some order, and a route drawn through fixes in the wrong order is a plausible looking line that never happened.

Register a flow agent that runs the GeoLineTool

POST /_plugins/_agent/agents/_register
{
  "name": "Track_Agent",
  "type": "flow",
  "description": "traces where things travelled",
  "tools": [
    {
      "type": "GeoLineTool",
      "name": "DemoGeoLineTool",
      "parameters": {
        "index": "vessel_positions",
        "group_by": "mmsi",
        "sort": "timestamp",
        "tracks": 10
      }
    }
  ]
}

Run it:

POST /_plugins/_agent/agents/<agent_id>/_execute
{
  "parameters": { "question": "trace the vessels that moved today" }
}

What the answer tells you

Completeness is stated per path and before the listing:

• When every document contributed, the answer says the path was drawn through every document — so you know the line is the whole story.
• When a path was shortened, the answer says so and says how it was shortened, rather than returning a truncated line that looks complete.
• When more things moved than tracks allows, the answer says these are the most active only. It does not present a sample as though it were the population.

If nothing could be traced, the answer says no movement could be traced on that field, rather than returning an empty path list. If the index has no geo_point field, it says that instead.

note

FindTracks is for where something went. It does not tell you where things are now, and it does not plan a route between two places — for road routing, see the routing APIs under Geospatial. For where activity concentrates, use FindConcentrations.