GeoUtils (server 6.3.2 API)

java.lang.Object
- org.elasticsearch.common.geo.GeoUtils

public class GeoUtils
extends java.lang.Object

Field Summary

Fields
Modifier and Type	Field	Description
`static double`	`EARTH_AXIS_RATIO`	Earth axis ratio defined by WGS 84 (0.996647189335)
`static double`	`EARTH_EQUATOR`	Earth ellipsoid equator length in meters
`static double`	`EARTH_MEAN_RADIUS`	Earth mean radius defined by WGS 84 in meters
`static double`	`EARTH_POLAR_DISTANCE`	Earth ellipsoid polar distance in meters
`static double`	`EARTH_SEMI_MAJOR_AXIS`	Earth ellipsoid major axis defined by WGS 84 in meters
`static double`	`EARTH_SEMI_MINOR_AXIS`	Earth ellipsoid minor axis defined by WGS 84 in meters
`static java.lang.String`	`GEOHASH`
`static java.lang.String`	`LATITUDE`
`static java.lang.String`	`LONGITUDE`
`static double`	`MAX_LAT`	Maximum valid latitude in degrees.
`static double`	`MAX_LON`	Maximum valid longitude in degrees.
`static double`	`MIN_LAT`	Minimum valid latitude in degrees.
`static double`	`MIN_LON`	Minimum valid longitude in degrees.
`static double`	`TOLERANCE`	rounding error for quantized latitude and longitude values

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method	Description
`static double`	`arcDistance(double lat1, double lon1, double lat2, double lon2)`	Return the distance (in meters) between 2 lat,lon geo points using the haversine method implemented by lucene
`static int`	`checkPrecisionRange(int precision)`	Checks that the precision is within range supported by elasticsearch - between 1 and 12 Returns the precision value if it is in the range and throws an IllegalArgumentException if it is outside the range.
`static SortedNumericDoubleValues`	`distanceValues(GeoDistance distance, DistanceUnit unit, MultiGeoPointValues geoPointValues, GeoPoint... fromPoints)`	Return a `SortedNumericDoubleValues` instance that returns the distances to a list of geo-points for each document.
`static double`	`geoHashCellHeight(int level)`	Calculate the height (in meters) of geohash cells at a specific level
`static double`	`geoHashCellSize(int level)`	Calculate the size (in meters) of geohash cells at a specific level
`static double`	`geoHashCellWidth(int level)`	Calculate the width (in meters) of geohash cells at a specific level
`static int`	`geoHashLevelsForPrecision(double meters)`	Calculate the number of levels needed for a specific precision.
`static int`	`geoHashLevelsForPrecision(java.lang.String distance)`	Calculate the number of levels needed for a specific precision.
`static boolean`	`isValidLatitude(double latitude)`	Returns true if latitude is actually a valid latitude value.
`static boolean`	`isValidLongitude(double longitude)`	Returns true if longitude is actually a valid longitude value.
`static double`	`maxRadialDistanceMeters(double centerLat, double centerLon)`	Returns the maximum distance/radius (in meters) from the point 'center' before overlapping
`static double`	`normalizeLat(double lat)`	Normalize latitude to lie within the -90 to 90 (both inclusive) range.
`static double`	`normalizeLon(double lon)`	Normalize longitude to lie within the -180 (exclusive) to 180 (inclusive) range.
`static void`	`normalizePoint(double[] lonLat)`
`static void`	`normalizePoint(double[] lonLat, boolean normLon, boolean normLat)`
`static void`	`normalizePoint(GeoPoint point)`	Normalize the geo `Point` for its coordinates to lie within their respective normalized ranges.
`static void`	`normalizePoint(GeoPoint point, boolean normLat, boolean normLon)`	Normalize the geo `Point` for the given coordinates to lie within their respective normalized ranges.
`static GeoPoint`	`parseGeoPoint(java.lang.Object value, boolean ignoreZValue)`	Parses the value as a geopoint.
`static GeoPoint`	`parseGeoPoint(XContentParser parser)`	Parse a `GeoPoint` with a `XContentParser`:
`static GeoPoint`	`parseGeoPoint(XContentParser parser, GeoPoint point)`
`static GeoPoint`	`parseGeoPoint(XContentParser parser, GeoPoint point, boolean ignoreZValue)`	Parse a `GeoPoint` with a `XContentParser`.
`static int`	`parsePrecision(XContentParser parser)`	Parse a precision that can be expressed as an integer or a distance measure like "1km", "10m".
`static double`	`planeDistance(double lat1, double lon1, double lat2, double lon2)`	Return the distance (in meters) between 2 lat,lon geo points using a simple tangential plane this provides a faster alternative to `arcDistance(double, double, double, double)` but is inaccurate for distances greater than 4 decimal degrees
`static double`	`quadTreeCellHeight(int level)`	Calculate the height (in meters) of quadtree cells at a specific level
`static double`	`quadTreeCellSize(int level)`	Calculate the size (in meters) of quadtree cells at a specific level
`static double`	`quadTreeCellWidth(int level)`	Calculate the width (in meters) of quadtree cells at a specific level
`static int`	`quadTreeLevelsForPrecision(double meters)`	Calculate the number of levels needed for a specific precision.
`static int`	`quadTreeLevelsForPrecision(java.lang.String distance)`	Calculate the number of levels needed for a specific precision.
`static boolean`	`rectangleContainsPoint(org.apache.lucene.geo.Rectangle r, double lat, double lon)`	check if point is within a rectangle todo: move this to lucene Rectangle class

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - MAX_LAT
```
public static final double MAX_LAT
```
    Maximum valid latitude in degrees.
    
    See Also:
    
    Constant Field Values
  - MIN_LAT
```
public static final double MIN_LAT
```
    Minimum valid latitude in degrees.
    
    See Also:
    
    Constant Field Values
  - MAX_LON
```
public static final double MAX_LON
```
    Maximum valid longitude in degrees.
    
    See Also:
    
    Constant Field Values
  - MIN_LON
```
public static final double MIN_LON
```
    Minimum valid longitude in degrees.
    
    See Also:
    
    Constant Field Values
  - LATITUDE
```
public static final java.lang.String LATITUDE
```
    See Also:
    
    Constant Field Values
  - LONGITUDE
```
public static final java.lang.String LONGITUDE
```
    See Also:
    
    Constant Field Values
  - GEOHASH
```
public static final java.lang.String GEOHASH
```
    See Also:
    
    Constant Field Values
  - EARTH_SEMI_MAJOR_AXIS
```
public static final double EARTH_SEMI_MAJOR_AXIS
```
    Earth ellipsoid major axis defined by WGS 84 in meters
    
    See Also:
    
    Constant Field Values
  - EARTH_SEMI_MINOR_AXIS
```
public static final double EARTH_SEMI_MINOR_AXIS
```
    Earth ellipsoid minor axis defined by WGS 84 in meters
    
    See Also:
    
    Constant Field Values
  - EARTH_MEAN_RADIUS
```
public static final double EARTH_MEAN_RADIUS
```
    Earth mean radius defined by WGS 84 in meters
    
    See Also:
    
    Constant Field Values
  - EARTH_AXIS_RATIO
```
public static final double EARTH_AXIS_RATIO
```
    Earth axis ratio defined by WGS 84 (0.996647189335)
    
    See Also:
    
    Constant Field Values
  - EARTH_EQUATOR
```
public static final double EARTH_EQUATOR
```
    Earth ellipsoid equator length in meters
    
    See Also:
    
    Constant Field Values
  - EARTH_POLAR_DISTANCE
```
public static final double EARTH_POLAR_DISTANCE
```
    Earth ellipsoid polar distance in meters
    
    See Also:
    
    Constant Field Values
  - TOLERANCE
```
public static final double TOLERANCE
```
    rounding error for quantized latitude and longitude values
    
    See Also:
    
    Constant Field Values
- Method Detail
  - isValidLatitude
```
public static boolean isValidLatitude(double latitude)
```
    Returns true if latitude is actually a valid latitude value.
  - isValidLongitude
```
public static boolean isValidLongitude(double longitude)
```
    Returns true if longitude is actually a valid longitude value.
  - geoHashCellWidth
```
public static double geoHashCellWidth(int level)
```
    Calculate the width (in meters) of geohash cells at a specific level
    
    Parameters:
    
    level - geohash level must be greater or equal to zero
    
    Returns:
    
    the width of cells at level in meters
  - quadTreeCellWidth
```
public static double quadTreeCellWidth(int level)
```
    Calculate the width (in meters) of quadtree cells at a specific level
    
    Parameters:
    
    level - quadtree level must be greater or equal to zero
    
    Returns:
    
    the width of cells at level in meters
  - geoHashCellHeight
```
public static double geoHashCellHeight(int level)
```
    Calculate the height (in meters) of geohash cells at a specific level
    
    Parameters:
    
    level - geohash level must be greater or equal to zero
    
    Returns:
    
    the height of cells at level in meters
  - quadTreeCellHeight
```
public static double quadTreeCellHeight(int level)
```
    Calculate the height (in meters) of quadtree cells at a specific level
    
    Parameters:
    
    level - quadtree level must be greater or equal to zero
    
    Returns:
    
    the height of cells at level in meters
  - geoHashCellSize
```
public static double geoHashCellSize(int level)
```
    Calculate the size (in meters) of geohash cells at a specific level
    
    Parameters:
    
    level - geohash level must be greater or equal to zero
    
    Returns:
    
    the size of cells at level in meters
  - quadTreeCellSize
```
public static double quadTreeCellSize(int level)
```
    Calculate the size (in meters) of quadtree cells at a specific level
    
    Parameters:
    
    level - quadtree level must be greater or equal to zero
    
    Returns:
    
    the size of cells at level in meters
  - quadTreeLevelsForPrecision
```
public static int quadTreeLevelsForPrecision(double meters)
```
    Calculate the number of levels needed for a specific precision. Quadtree cells will not exceed the specified size (diagonal) of the precision.
    
    Parameters:
    
    meters - Maximum size of cells in meters (must greater than zero)
    
    Returns:
    
    levels need to achieve precision
  - quadTreeLevelsForPrecision
```
public static int quadTreeLevelsForPrecision(java.lang.String distance)
```
    Calculate the number of levels needed for a specific precision. QuadTree cells will not exceed the specified size (diagonal) of the precision.
    
    Parameters:
    
    distance - Maximum size of cells as unit string (must greater or equal to zero)
    
    Returns:
    
    levels need to achieve precision
  - geoHashLevelsForPrecision
```
public static int geoHashLevelsForPrecision(double meters)
```
    Calculate the number of levels needed for a specific precision. GeoHash cells will not exceed the specified size (diagonal) of the precision.
    
    Parameters:
    
    meters - Maximum size of cells in meters (must greater or equal to zero)
    
    Returns:
    
    levels need to achieve precision
  - geoHashLevelsForPrecision
```
public static int geoHashLevelsForPrecision(java.lang.String distance)
```
    Calculate the number of levels needed for a specific precision. GeoHash cells will not exceed the specified size (diagonal) of the precision.
    
    Parameters:
    
    distance - Maximum size of cells as unit string (must greater or equal to zero)
    
    Returns:
    
    levels need to achieve precision
  - normalizeLon
```
public static double normalizeLon(double lon)
```
    Normalize longitude to lie within the -180 (exclusive) to 180 (inclusive) range.
    
    Parameters:
    
    lon - Longitude to normalize
    
    Returns:
    
    The normalized longitude.
  - normalizeLat
```
public static double normalizeLat(double lat)
```
    Normalize latitude to lie within the -90 to 90 (both inclusive) range.
    Note: You should not normalize longitude and latitude separately, because when normalizing latitude it may be necessary to add a shift of 180° in the longitude. For this purpose, you should call the normalizePoint(GeoPoint) function.
    
    Parameters:
    
    lat - Latitude to normalize
    
    Returns:
    
    The normalized latitude.
    
    See Also:
    
    normalizePoint(GeoPoint)
  - normalizePoint
```
public static void normalizePoint(GeoPoint point)
```
    Normalize the geo Point for its coordinates to lie within their respective normalized ranges.
    Note: A shift of 180° is applied in the longitude if necessary, in order to normalize properly the latitude.
    
    Parameters:
    
    point - The point to normalize in-place.
  - normalizePoint
```
public static void normalizePoint(GeoPoint point,
                                  boolean normLat,
                                  boolean normLon)
```
    Normalize the geo Point for the given coordinates to lie within their respective normalized ranges.
    You can control which coordinate gets normalized with the two flags.
    Note: A shift of 180° is applied in the longitude if necessary, in order to normalize properly the latitude. If normalizing latitude but not longitude, it is assumed that the longitude is in the form x+k*360, with x in ]-180;180], and k is meaningful to the application. Therefore x will be adjusted while keeping k preserved.
    
    Parameters:
    
    point - The point to normalize in-place.
    
    normLat - Whether to normalize latitude or leave it as is.
    
    normLon - Whether to normalize longitude.
  - normalizePoint
```
public static void normalizePoint(double[] lonLat)
```
  - normalizePoint
```
public static void normalizePoint(double[] lonLat,
                                  boolean normLon,
                                  boolean normLat)
```
  - parseGeoPoint
```
public static GeoPoint parseGeoPoint(XContentParser parser)
                              throws java.io.IOException,
                                     ElasticsearchParseException
```
    Parse a GeoPoint with a XContentParser:
    
    Parameters:
    
    parser - XContentParser to parse the value from
    
    Returns:
    
    new GeoPoint parsed from the parse
    
    Throws:
    
    java.io.IOException
    
    ElasticsearchParseException
  - parseGeoPoint
```
public static GeoPoint parseGeoPoint(XContentParser parser,
                                     GeoPoint point)
                              throws java.io.IOException,
                                     ElasticsearchParseException
```
    Throws:
    
    java.io.IOException
    
    ElasticsearchParseException
  - parseGeoPoint
```
public static GeoPoint parseGeoPoint(java.lang.Object value,
                                     boolean ignoreZValue)
                              throws ElasticsearchParseException
```
    Parses the value as a geopoint. The following types of values are supported:
    Object: has to contain either lat and lon or geohash fields
    String: expected to be in "latitude, longitude" format or a geohash
    Array: two or more elements, the first element is longitude, the second is latitude, the rest is ignored if ignoreZValue is true
    
    Throws:
    
    ElasticsearchParseException
  - parseGeoPoint
```
public static GeoPoint parseGeoPoint(XContentParser parser,
                                     GeoPoint point,
                                     boolean ignoreZValue)
                              throws java.io.IOException,
                                     ElasticsearchParseException
```
    Parse a GeoPoint with a XContentParser. A geopoint has one of the following forms:
    - Object:
      {"lat": <latitude>, "lon": <longitude>}
    - String:
      "<latitude>,<longitude>"
    - Geohash:
      "<geohash>"
    - Array:
      [<longitude>,<latitude>]
    Parameters:
    
    parser - XContentParser to parse the value from
    
    point - A GeoPoint that will be reset by the values parsed
    
    Returns:
    
    new GeoPoint parsed from the parse
    
    Throws:
    
    java.io.IOException
    
    ElasticsearchParseException
  - parsePrecision
```
public static int parsePrecision(XContentParser parser)
                          throws java.io.IOException,
                                 ElasticsearchParseException
```
    Parse a precision that can be expressed as an integer or a distance measure like "1km", "10m". The precision is expressed as a number between 1 and 12 and indicates the length of geohash used to represent geo points.
    
    Parameters:
    
    parser - XContentParser to parse the value from
    
    Returns:
    
    int representing precision
    
    Throws:
    
    java.io.IOException
    
    ElasticsearchParseException
  - checkPrecisionRange
```
public static int checkPrecisionRange(int precision)
```
    Checks that the precision is within range supported by elasticsearch - between 1 and 12 Returns the precision value if it is in the range and throws an IllegalArgumentException if it is outside the range.
  - maxRadialDistanceMeters
```
public static double maxRadialDistanceMeters(double centerLat,
                                             double centerLon)
```
    Returns the maximum distance/radius (in meters) from the point 'center' before overlapping
  - arcDistance
```
public static double arcDistance(double lat1,
                                 double lon1,
                                 double lat2,
                                 double lon2)
```
    Return the distance (in meters) between 2 lat,lon geo points using the haversine method implemented by lucene
  - planeDistance
```
public static double planeDistance(double lat1,
                                   double lon1,
                                   double lat2,
                                   double lon2)
```
    Return the distance (in meters) between 2 lat,lon geo points using a simple tangential plane this provides a faster alternative to arcDistance(double, double, double, double) but is inaccurate for distances greater than 4 decimal degrees
  - rectangleContainsPoint
```
public static boolean rectangleContainsPoint(org.apache.lucene.geo.Rectangle r,
                                             double lat,
                                             double lon)
```
    check if point is within a rectangle todo: move this to lucene Rectangle class
  - distanceValues
```
public static SortedNumericDoubleValues distanceValues(GeoDistance distance,
                                                       DistanceUnit unit,
                                                       MultiGeoPointValues geoPointValues,
                                                       GeoPoint... fromPoints)
```
    Return a SortedNumericDoubleValues instance that returns the distances to a list of geo-points for each document.

Class GeoUtils

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MAX_LAT

MIN_LAT

MAX_LON

MIN_LON

LATITUDE

LONGITUDE

GEOHASH

EARTH_SEMI_MAJOR_AXIS

EARTH_SEMI_MINOR_AXIS

EARTH_MEAN_RADIUS

EARTH_AXIS_RATIO

EARTH_EQUATOR

EARTH_POLAR_DISTANCE

TOLERANCE

Method Detail

isValidLatitude

isValidLongitude

geoHashCellWidth

quadTreeCellWidth

geoHashCellHeight

quadTreeCellHeight

geoHashCellSize

quadTreeCellSize

quadTreeLevelsForPrecision

quadTreeLevelsForPrecision

geoHashLevelsForPrecision

geoHashLevelsForPrecision

normalizeLon

normalizeLat

normalizePoint

normalizePoint

normalizePoint

normalizePoint

parseGeoPoint

parseGeoPoint

parseGeoPoint

parseGeoPoint

parsePrecision

checkPrecisionRange

maxRadialDistanceMeters

arcDistance

planeDistance

rectangleContainsPoint

distanceValues