# DISTSPHERICAL

The `DISTSPHERICAL` field specifier allows you to find documents that define a location (latitude and longitude) that is within a specified distance from a specified point.

You can specify the document location using either a pair of fields (corresponding to latitude and longitude values), or a unified `GeospatialType` field that contains a supported geometric shape in Well-Known Text format.

TIP: If your document location field contains any shape other than a point, IDOL calculates distances from the geometric center of the shape.

## Format

    FieldText=DISTSPHERICAL{lat,long,dist}:LOCATION

`lat` | The specified latitude. Specify latitude positions south of the equator as negative.
`long` | The specified longitude. Specify longitude positions west of the Greenwich Meridian as negative.
`dist` | The distance in kilometers from the specified latitude and longitude.
`LOCATION` | The document field or fields that contain the location value. You can use one of the following options to specify location fields: a single field. This field must contain a supported well-known text geometric object. See Supported Well-Known Text Geometric Objects. two fields, in the format `LATFIELD:LONGFIELD`, where `LATFIELD` is the field that contains the latitude value, and `LONGFIELD` is the field that contains the longitude value. You must specify the fields in the order `latitude:longitude`. You can specify multiple options for the location fields, in the form `LOCATION1:LOCATION2:LOCATION3`, and so on. This form can include a mix of types (unified location fields and split latitude and longitude fields). NOTE: If you use multiple position fields or field pairs, Distributed Action Handler cannot match documents where a pair of split geospatial fields occurs interleaved with other geospatial fields. For example, if you use `LAT1:LONG1:LOCATION` in your query, and these fields occur in a document in the order `LAT1`, `LOCATION`, `LONG1`, Distributed Action Handler does not match that document. In such cases, you can rewrite the query, in the form `DISTSPHERICAL{...}:LAT1:LONG1 OR DISTSPHERICAL{...}:LOCATION`

NOTE: You can optimize this field specifier by configuring your coordinate fields with the `GeospatialType` or `NumericType` property types. If you want to use a single field with well-known text definitions, you can optimize the field specifier only by using the unified `GeospatialType` property.

## Examples

    FieldText=DISTSPHERICAL{37.75,-122.4,20}:LAT:LONG

This example matches all documents whose position is within a 20 kilometer radius of San Francisco (37.75N,122.4W). The latitude and longitude position of a document in this example is contained in the fields `LAT` and `LONG`, respectively.

    FieldText=DISTSPHERICAL{52.2,0.1,20}:LOCATION:LAT:LONG

This example matches all documents whose position is within a 20 kilometer radius of Cambridge (52.2N,0.1W). The latitude and longitude position of a document in this example is contained in either the (unified) `LOCATION` field, or the `LAT` and `LONG` fields.

_FT_HTML5_bannerTitle.htm