org.apache.lucene.document

## Class LatLonPoint

- java.lang.Object
- - org.apache.lucene.document.Field
  - - org.apache.lucene.document.LatLonPoint

All Implemented Interfaces:
  IndexableField

    public class LatLonPoint
    extends Field

An indexed location field.

Finding all documents within a range at search time is efficient. Multiple values for the same field in one document is allowed.

This field defines static factory methods for common operations:

- `newBoxQuery()` for matching points within a bounding box.
- `newDistanceQuery()` for matching points within a specified distance.
- `newPolygonQuery()` for matching points within an arbitrary polygon.

If you also need per-document operations such as sort by distance, add a separate `LatLonDocValuesField` instance. If you also need to store the value, you should add a separate `StoredField` instance.

WARNING: Values are indexed with some loss of precision from the original `double` values (4.190951585769653E-8 for the latitude component and 8.381903171539307E-8 for longitude).

See Also:
  `PointValues`, `LatLonDocValuesField`

### Nested Class Summary

### Nested classes/interfaces inherited from class org.apache.lucene.document.Field

`Field.Store`

### Field Summary

Fields
`static int` `BYTES` LatLonPoint is encoded as integer values so number of bytes is 4
`static FieldType` `TYPE` Type for an indexed LatLonPoint

### Fields inherited from class org.apache.lucene.document.Field

`fieldsData, name, tokenStream, type`

### Constructor Summary

Constructors
Constructor and Description
`LatLonPoint(String name, double latitude, double longitude)` Creates a new LatLonPoint with the specified latitude and longitude

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`static Query` `newBoxQuery(String field, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude)` Create a query for matching a bounding box.

`static Query`

`newDistanceFeatureQuery(String field, float weight, double originLat, double originLon, double pivotDistanceMeters)`
Given a field that indexes point values into a `LatLonPoint` and doc values into `LatLonDocValuesField`, this returns a query that scores documents based on their haversine distance in meters to `(originLat, originLon)`: `score = weight * pivotDistanceMeters / (pivotDistanceMeters + distance)`, ie.

`static Query` `newDistanceQuery(String field, double latitude, double longitude, double radiusMeters)` Create a query for matching points within the specified distance of the supplied location.
`static Query` `newPolygonQuery(String field, Polygon... polygons)` Create a query for matching one or more polygons.
`void` `setLocationValue(double latitude, double longitude)` Change the values of this field
`String` `toString()` Prints a Field for human consumption.

### Methods inherited from class org.apache.lucene.document.Field

`binaryValue, fieldType, getCharSequenceValue, name, numericValue, readerValue, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, stringValue, tokenStream, tokenStreamValue`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Field Detail

#### BYTES

    public static final int BYTES

LatLonPoint is encoded as integer values so number of bytes is 4

See Also:
  Constant Field Values

#### TYPE

    public static final FieldType TYPE

Type for an indexed LatLonPoint

Each point stores two dimensions with 4 bytes per dimension.

### Constructor Detail

#### LatLonPoint

    public LatLonPoint(String name,
                       double latitude,
                       double longitude)

Creates a new LatLonPoint with the specified latitude and longitude

Parameters:
  `name` - field name
  `latitude` - latitude value: must be within standard +/-90 coordinate bounds.
  `longitude` - longitude value: must be within standard +/-180 coordinate bounds.
Throws:
  `IllegalArgumentException` - if the field name is null or latitude or longitude are out of bounds

### Method Detail

#### setLocationValue

    public void setLocationValue(double latitude,
                                 double longitude)

Change the values of this field

Parameters:
  `latitude` - latitude value: must be within standard +/-90 coordinate bounds.
  `longitude` - longitude value: must be within standard +/-180 coordinate bounds.
Throws:
  `IllegalArgumentException` - if latitude or longitude are out of bounds

#### toString

    public String toString()

Description copied from class: `Field`
Prints a Field for human consumption.

Overrides:
  `toString` in class `Field`

#### newBoxQuery

    public static Query newBoxQuery(String field,
                                    double minLatitude,
                                    double maxLatitude,
                                    double minLongitude,
                                    double maxLongitude)

Create a query for matching a bounding box.

The box may cross over the dateline.

Parameters:
  `field` - field name. must not be null.
  `minLatitude` - latitude lower bound: must be within standard +/-90 coordinate bounds.
  `maxLatitude` - latitude upper bound: must be within standard +/-90 coordinate bounds.
  `minLongitude` - longitude lower bound: must be within standard +/-180 coordinate bounds.
  `maxLongitude` - longitude upper bound: must be within standard +/-180 coordinate bounds.
Returns:
  query matching points within this box
Throws:
  `IllegalArgumentException` - if `field` is null, or the box has invalid coordinates.

#### newDistanceQuery

    public static Query newDistanceQuery(String field,
                                         double latitude,
                                         double longitude,
                                         double radiusMeters)

Create a query for matching points within the specified distance of the supplied location.

Parameters:
  `field` - field name. must not be null.
  `latitude` - latitude at the center: must be within standard +/-90 coordinate bounds.
  `longitude` - longitude at the center: must be within standard +/-180 coordinate bounds.
  `radiusMeters` - maximum distance from the center in meters: must be non-negative and finite.
Returns:
  query matching points within this distance
Throws:
  `IllegalArgumentException` - if `field` is null, location has invalid coordinates, or radius is invalid.

#### newPolygonQuery

    public static Query newPolygonQuery(String field,
                                        Polygon... polygons)

Create a query for matching one or more polygons.

Parameters:
  `field` - field name. must not be null.
  `polygons` - array of polygons. must not be null or empty
Returns:
  query matching points within this polygon
Throws:
  `IllegalArgumentException` - if `field` is null, `polygons` is null or empty
See Also:
  `Polygon`

#### newDistanceFeatureQuery

    public static Query newDistanceFeatureQuery(String field,
                                                float weight,
                                                double originLat,
                                                double originLon,
                                                double pivotDistanceMeters)

Given a field that indexes point values into a `LatLonPoint` and doc values into `LatLonDocValuesField`, this returns a query that scores documents based on their haversine distance in meters to `(originLat, originLon)`: `score = weight * pivotDistanceMeters / (pivotDistanceMeters + distance)`, ie. score is in the `[0, weight]` range, is equal to `weight` when the document's value is equal to `(originLat, originLon)` and is equal to `weight/2` when the document's value is distant of `pivotDistanceMeters` from `(originLat, originLon)`. In case of multi-valued fields, only the closest point to `(originLat, originLon)` will be considered. This query is typically useful to boost results based on distance by adding this query to a `BooleanClause.Occur.SHOULD` clause of a `BooleanQuery`.