## 2.14. Geographic Functions

Geographical functions operate on geographic input, like points, lines or polygons. The built-in general-purpose geographic functions are listed in Table 2.24.

Table 2.24. Geography functions

FunctionReturn TypeDescriptionExample[a] Result[b]
`geo_make_point(latitude double, longitude double)` `geography(point)` Creates a point with coordinates `latitude` and `longitude`.
`geo_make_point(20, 30)`
`point(30.0000003 20.0)[c]`
`geo_make_line(a geography(point), b geography(point))` `geography(linestring)` Creates a line between `a` and `b`
```geo_make_line('point(14 42)'::geography,
'point(18 43)'::geography)```
```linestring(14.0000003 42.0000002,
18.0000003 43.0000001)```
`geo_distance(a geography(point), b geography(point), unit string)` `double` Distance in the WGS84 ellipsoid between points `a` and `b` expressed in `unit`.
```geo_distance('point(0 0)'::geography,
'point(0 1)'::geography,
'kilometers')```
`110.574372592802`
`geo_buffer(p geography(point), r double, unit string)` `geography(polygon)` 120-sided polygon around point `p`, which is fully enclosed by circle with center in same point and radius `r`, where radius unit is given in `unit`. When radius is 0, a single point is returned (the input parameter) instead of a 120-sided polygon
```geo_buffer('point(90 45)'::geography,
1989.0,
'meter')```
```polygon((90.0000002 45.0178973,
89.9986795 45.0178727,
...
90.0013209 45.0178727,
90.0000002 45.0178973))```
`geo_auto_vertex_order(arg geography)` `geography` Inverts the vertex order for all polygons if they are specified in an interior-right winding order assuming flat earth topology.[d]
```geo_auto_vertex_order(
'geometrycollection(polygon((0 0, 2 0, 0 4, 0 0)),
polygon((0 0, 0 2, 4 0, 0 0)),
point(0 2))'::geography)```
```geometrycollection(
polygon((0.0 0.0,2.0000003 0.0,0.0 4.0,0.0 0.0)),
polygon((0.0 0.0,4.0 0.0,0.0 2.0000003,0.0 0.0)),
point(0.0 2.0000003))```
`geo_invert_vertex_order(arg geography)` `geography` Inverts the vertex order of all polygons
```geo_invert_vertex_order(
'geometrycollection(polygon((0 0, 2 0, 0 4, 0 0)),
polygon((0 0, 0 2, 4 0, 0 0)),
point(0 2))'::geography)```
```geometrycollection(
polygon((0.0 0.0,0.0 4.0,2.0000003 0.0,0.0 0.0)),
polygon((0.0 0.0,4.0 0.0,0.0 2.0000003,0.0 0.0)),
point(0.0 2.0000003))```

[a] To pass a `geography` constant as an argument, it needs to be cast from a string which contains a `geography` object formatted in the Well Known Text (WKT) format defined by the Open GIS Consortium, Inc, in the OpenGIS Simple Features Specification For SQL. More examples of handling `geography` objects using the Hyper API can be found here.

[b] Return values of type `geography` are shown in WKT format

[c] Note that the latitude and longitude are flipped in the result, because it is shown in the WKT format as `point(longitude latitude)`.

[d] Explicit use of `geo_auto_vertex_order` is needed and recommended only when processing extracts generated by Hyper API version v0.0.12514 or earlier. `geo_auto_vertex_order` is implicitly used when parsing `GEOGRAPHY` values from WKT format.

All supported units of length are listed in Table 2.25.

Table 2.25. Supported distance units

Unit name in American spellingOther supported spellingsDescription
meter metre, m, meters, metres Base unit of length in International System of Units (SI)
kilometer kilometre, km, kilometers, kilometres Equal to 1000 meters
mile mi, miles Equal to 1609.344 meters
foot ft, feet Equal to 0.3048 meters