POLYGON FieldText Search

The FieldText operator POLYGON determines whether a Cartesian (that is, a flat plane) coordinate or coordinates falls inside a given Cartesian polygon, where you define the polygon by its corners.

One of the most common uses for polygon matching is to determine whether a latitude/longitude location falls within a polygon on the Earth’s surface. Although in this case the polygon is on a sphere as opposed to on a Cartesian plane, the matching still works as expected provided that the polygon does not cross the 180 degrees E/W meridian.


A polygon containing either the North or South Pole automatically crosses this meridian.

If a polygon is required that crosses the 180 degree meridian then split it into two halves, one with ‘west-only’ longitudes and the other with ‘east-only’ longitudes.

The polygons must have at least three coordinates, but there is no upper limit on the number of coordinates that a polygon can contain.

There are two primary uses for the POLYGON operator:

Return Documents that Contain a Point Within a Polygon

You can use POLYGON to find documents that contain coordinates in a given area. For example, if your documents contain one or more coordinates:

#DRETITLE story tagged in Denver, Colorado
#DREFIELD LON="-104.98"

then you can use the following query to determine which of the documents are tagged with a point in the state of Colorado:


If you have multiple coordinates in a single document then you must add XMLFullStructure=True to your configuration file.

Return Polygons that Contain a Given Point

You can use POLYGON in AgentBoolean processes. In this case, you might have multiple polygons and want to determine the polygon that a given point falls in.

The following worked example determines which US State the point with latitude 39.74 degrees North and longitude 104.98 degrees West is in.

Store each of the polygons as a document, with an AgentBoolean field (for example, AGENTBOOL) configured with AgentbooleanCacheField=*/AGENTBOOL, your AgentBoolean FieldText field (for example FTF) configured with FieldTextCacheField=*/FTF, and an “always match” field configured as AlwaysMatchType=True.

You then index a document for each US State. The following example document represents the rectangular state of Colorado:

#DRETITLE Colorado
#DREFIELD FTF="POLYGON{41.00,-109.02,37.00,-109.02,37.00,-102.04,41.00,-102.04}:LAT:LON"

The presence of the AlwaysMatchType ensures that all queries perform the FieldText AgentBoolean on this document, whereas otherwise query Text would have to match an index field in that document as normal.

The following example query uses a document that contains a point in Denver, which returns the Colorado document:


Here the text represents the document in IDX format:

#DREFIELD LON="-104.98"

As with all AgentBoolean queries you must include an AgentBooleanField, even if none appears in your polygon documents. Similarly, as with all TextParse queries you must have indexed a dummy document containing the fields that you use in your queries (in this case DREREFERENCE, AGENTBOOL, FTF, LAT, and LON).


The matching process is extremely fast, but if you have thousands of polygon documents in your AgentBoolean IDOL then there are techniques that can optimize the matching further. Contact Technical Support for further information.