# Geographic Coordinates

NOTE: In general, the order of arguments when long/lat are being referred to is `<longitude, latitude>`

Hydrolix supports 3 types of geographic data:

• cartesian - longitude/latitude (two `double` values)
• geoHash (`string`)
• H3 (`uint64`)

## cartesian

`longitude` and `latitude` are stored in separate `double` columns in Hydrolix. North latitudes are positive, southern latitudes are negative. Eastern longitudes are positive, western latitudes are negative.

### greatCircleDistance

`greatCircleDistance` takes two locations, represented as long/lat, and calculates the shortest distance between them, taking the spherical shape of Earth into account.

Parameters:

• `longitude_1` - the `double` value of the longitude for the first location
• `latitude_1` - the `double` value of the latitude for the first location
• `longitude_2` - the `double` value of the longitude for the second location
• `latitude_2` - the `double` value of the latitude of the second location

Usage:

• `greatCircleDistance(longitude_1, latitude_1, longitude_2, latitude_2)`

Returns:

• a `double` representing the distance in meters

### pointInEllipses

`pointInEllipses` calculates if a location defined by cartesian coordinates is inside of any one of `n` number of ellipses.

Parameters:

• `loc_longitude` - the `double` value of the longitude for the location to operate on
• `loc_latitude` - the `double` value of the latitude for the location to operate on

Ellipses are defined by a cartesian center and coordinates ot the axes. Any number of ellipses can be included in the arguments, as long as each has the following declared:

• `ellipse_longitude`
• `ellipse_latitude`
• `ellipse_x_axis`
• `ellipse_y_axis`

Usage:

• `pointInEllipses(loc_longitude, loc_latitude, ellipse1_longitude, ellipse1_latitude, ellipse1_x_axis, ellipse1_y_axis [,ellipsen_longitude, ellipsen_latitude, ellipsen_x_axis, ellipsen_y_axis])`

Returns:

• `0` if the location is not in at least one of the ellipses
• `1` if the location is inside at least one of the ellipses

### pointInPolygon

`pointInPolygon` calculates if a location defined by cartesian coordinates enclosed in a polygon, defined by 3 or more long/lat pairs

Parameters:

• `loc_longitude` - the `double` value of the longitude for the location to operate on
• `loc_latitude` - the `double` value of the latitude for the location to operate on

A polygoin is defined by 3 or more long/lat pairs:

• `point_1_long`
• `point_1_lat`
• `point_2_long`
• `point_2_lat`
• `point_n_long`
• `point_n_lat`

Usage:

• `pointInPolygon((loc_longitude, loc_latitude), [(point_1_long, point_1_lat), (point_2_long, point_2_lat), (point_3_long, point_3_lat), ....])`

Returns:

• `0` if the location is in the polygon
• `1` if the location is inside the polygon

## geoHash

A geoHash `string` that is a unique representation of a location. A geohash is a unique identifier and can be used to look up the location on mapping platforms.
Geohash encoding converts a latitude/longitude combination to a string of letters and digits that is the "geohash" of the location.

A location encoded with geohash can be stored as `string` instead of two columns

### geohashDecode, geohashEncode

Geohash encoding converts a latitude/longitude combination to a string of letters and digits that is the "geohash" of the location. The geohash is a unique identifier and can be used to look up the location on mapping platforms.

Parameters:

• `longitude` - the `double` value of longitude
• `latitude` - the `double` value of the latitude
- `precision` - the `precision` of the result. Valid Integers are [1,12]. Anything outside of this range will be converted to `12`.

Usage:

• `geohashEncode(longitude, latitude [,precision])`
• `geohashDecode(geohashString)`

Returns:

• `String` representation of the geoHash. For example `geohashEncode(-90.0, 30.0)` returns `dj248j248j24`

### geohashesInBox

`geohashesInBox` returns an array of geohashes inside of a box defined by two longitude/latitude locations, with the stated precision.

North latitudes are positive, southern latitudes are negative. Eastern longitudes are positive, western latitudes are negative.

Parameters:

• `longitude_min` - the `double` value of the minimum longitude
• `latitude_min` - the `double` value of the minimum latitude
• `longitude_max` - the `double` value of the maximum longitude
• `latitude_max` - the `double` value of the maximum latitude
• `precision` - the `precision` of the result. Valid Integers are [1,12]. Anything outside of this range will be converted to `12`.

Usage:

• `geohashesInBox(longitude_min, latitude_min, logitude_max, latitude_max [, precision])`

Returns:

• an array of `string` that are the geohashes of the given precision in the box defined by the longitudes and latitudes.

## H3

H3 is a spatial indexing scheme based on dividing the planet into hexagons. H3 was developed by Uber to handle their unique challenges with location data, including tracking moving entities in real time.

H3 is represented as a `uint64`, and can be stored in a single column.

### geoToH3

`geoToH3` converts a long/lat combination to an H3 `uint64`, with a given precision.

Parameters:

• `longitude` - the `double` value of longitude
• `latitude` - the `double` value of the latitude
- `precision` - the `precision` of the result. Valid Integers are [0,15]. Anything outside of this range will be converted to `12`. NOTE Precision is required for H3, and it is not for geoHash

Usage:

• `geoToH3(longitude, latitude ,precision)`

Returns:

• `uint64` representation of the H3 value for the location.

### h3GetBaseCell

`h3GetBaseCell`

Parameters:

• `longitude` - the `double` value of longitude
• `latitude` - the `double` value of the latitude
- `precision` - the `precision` of the result. Valid Integers are [0,15]. Anything outside of this range will be converted to `12`. NOTE Precision is required for H3, and it is not for geoHash

Usage:

• `geoToH3(longitude, latitude ,precision)`

Returns:

• `uint64` representation of the H3 value for the location.