# POLYGON FieldText Search

The FieldText operator `POLYGON` determines whether a Cartesian (that is, a flat plane) coordinate or polygon falls wholly inside a Cartesian polygon that you specify. You define the polygon by its corners.

When you use unified `GeoSpatialType` fields, you can also use `POLYGON` to determine whether a polygon falls wholly within the polygon that you specify. In this case, you can also use the `GEOINTERSECTS` operator, which determines whether a particular point or polygon falls wholly or partially inside the polygon that you specify.

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.

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

If you require a polygon that crosses the 180 degree meridian, you can 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

- Return Polygons that Contain a Specified Point

## 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 coordinate pairs:

    #DREREFERENCE 1
    #DRETITLE story tagged in Denver, Colorado
    #DREFIELD LAT="39.74"
    #DREFIELD LON="-104.98"
    #DREENDDOC

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

    action=query&FieldText=POLYGON{41.00,-109.02,37.00,-109.02,37.00,-102.04,41.00,-102.04}:LAT:LON"

NOTE: If you have multiple coordinates in a single document then you must set `XMLFullStructure` to `True` in your configuration file.

When you have a unified `GeospatialType` field, you can store coordinate information in a single field, by using a Well-known text format POINT or POLYGON definition. For example:

    #DREREFERENCE 1
    #DRETITLE story tagged in Denver, Colorado
    #DREFIELD POSITION=POINT(-104.98 39.74)
    #DREFIELD STATE_BORDER=POLYGON((-109.02 41.00,-109.02 37.00,-102.04 37.00,-102.04 41.00, -109.02 41.00))
    #DREENDDOC

NOTE: In the POINT and POLYGON definitions, you must always specify each point in the order x y (that is, longitude then latitude).

In this case, the following query finds documents that are tagged with a point in the state of Colorado:

    action=query&FieldText=POLYGON{41.00,-109.02,37.00,-109.02,37.00,-102.04,41.00,-102.04}:POSITION"

When you have documents of this form, you can also use an `GEOINTERSECTS` operator query to find regions that intersect with the regions in your document. This type of query also matches any points or polygons that fall wholly within the region that you specify. For example, the following query finds any documents that are tagged with a point or polygon region in or intersecting the state of Colorado:

    action=query&FieldText=GEOINTERSECTS{POLYGON((41.00 -109.02, 37.00 -109.02, 37.00 -102.04, 41.00 -102.04))}:POSITION"

## Return Polygons that Contain a Specified 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:

    #DREREFERENCE 2
    #DRETITLE Colorado
    #DREFIELD ALWAYSMATCH="1"
    #DREFIELD FTF="POLYGON{41.00,-109.02,37.00,-109.02,37.00,-102.04,41.00,-102.04}:LAT:LON"
    #DREENDDOC

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:

    action=query&AgentBooleanField=AGENTBOOL&FieldTextField=FTF&TextParse=True&Text=%23DREREFERENCE%20%0A%23DREFIELD%20LAT=%2239.74%22%0A%23DREFIELD%20LON=%22-104.98%22%0A%23DREENDDOC%0A

Here the text represents the document in IDX format:

    #DREREFERENCE
    #DREFIELD LAT="39.74"
    #DREFIELD LON="-104.98"
    #DREENDDOC

NOTE: 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`).

    #DREREFERENCE dummy
    #DREFIELD LAT=""
    #DREFIELD LON=""
    #DREFIELD AGENTBOOL=""
    #DREFIELD FTF=""
    #DREENDDOC

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.

_FT_HTML5_bannerTitle.htm