The following are the built-in functions for doing spatial measurements. They are divided into two sections:
ST_ANGLE(p1: point, p2: point) -> f64ST_ANGLE(p1: point, p2: point, p3: point) -> f64ST_ANGLE(p1: point, p2: point, p3: point, p4: point) -> f64ST_ANGLE(l1: line, l2: line) -> f64Computes the clockwise angle between two vectors.
Null handling
If any of the arguments is NULL, the function will also return NULL.
Notes
When given two points, computes the angle P1-(0, 0)-P2.
When given three points, computes the angle P1-P2-P3.
When given four points, computes the angle between vectors P1->P2 and P3->P4.
When given two lines, computes the angle between vectors S1->E1 and S2->E2,
where S1, S2, E1 and E2 are start and end-point of the given lines.
The function returns a positive angle between 0 and 2p radians.
The function will return NULL when the angle cannot be uniquely determined, for example when some points are the same (ST_Angle(POINT '(10 10)', POINT '(10 10)')).
See also
ST_AREA(g: [multi]polygon) -> float64Returns the area of a polygon/multipolygon geometry in square meters.
Null handling
If the argument is NULL, the function will also return NULL.
Notes
If the given geometry is empty, the function will return 0.
Examples
SELECT ST_AREA(polygon '((0 0, 100 0, 100 100, 0 100, 0 0))');
--> 222.17034400
See also
ST_AZIMUTH(p1: point, p2: point) -> float64Returns the azimuth in radians of the line segment defined by the given points.
Null handling
If any of the arguments is NULL, the function will also return NULL.
Notes
If the given points are the same, the function will return NULL.
The azimuth angle is referenced from the north (the positive Y axis), and is positive in the clockwise direction,
e.g. North -> 0, East -> pi / 2, South -> pi, West -> 3/2 * pi.
The function result (which is in radians) can be converted to degrees using the DEGREES function.
Examples
SELECT ST_Azimuth(point '(10 10)', point '(20 20)');
--> 0.785398 -- pi/4
See also
ST_LENGTH(g: [multi]linestring) -> float64ST_LENGTH(g: [multi]polygon) -> float64ST_LENGTH(x1: float64, y1: float64, x2: float64, y2: float64, ...) -> float64Returns the length/perimeter of the given geometry in meters. Also accepts raw point coordinates as arguments.
Arguments
The raw coordinate form of this function can take arbitrarily many arguments, but at least 4 are required (i.e. coordinates of at least two points). There must be an even number of arguments. The coordinates are assumed to be in the Mireo World-Point coordinate system.
Null handling
If any of the arguments is NULL, the function will also return NULL.
Notes
If the given geometry is empty, the function will return 0.
The ST_LENGTH variant accepting a polygonal argument is just an alias for the ST_PERIMETER function.
The function returns a very good approximation of the real length in meters, but the value is not exact as the Earth's surface is not a plane but a sphere.
In most cases this doesn't matter, but when it does (e.g. for linestrings spanning very large distances), there is the ST_LENGTHSPHERE function which returns the correct value.
Examples
SELECT ST_LENGTH(linestring '(0 0, 1000 1000, 2000 0)');
--> 421.587802
SELECT ST_LENGTH(polygon '((0 0, 1000 1000, 2000 0, 0 0))');
--> 719.695396
SELECT ST_LENGTH(0, 0, 1000, 1000, 2000, 0);
--> 421.587802
See also
ST_LENGTHSPHERE(g: [multi]linestring) -> float64Returns the length in meters of a linestring/multilinestring geometry on a sphere.
Null handling
If the argument is NULL, the function will also return NULL.
Notes
If the given geometry is empty, the function will return 0.
This function computes the length using the Haversine formula, but is substantially slower than the approximate ST_LENGTH function, and should therefore be used only when really neccessary.
Examples
SELECT ST_LENGTHSPHERE(linestring '(0 0, 1000 1000, 2000 0)');
--> 421.551028
See also
ST_PERIMETER(g: [multi]polygon) -> float64Returns the length of the boundary of a polygon/multipolygon geometry in meters.
Null handling
If the argument is NULL, the function will also return NULL.
Notes
If the given geometry is empty, the function will return 0.
The function returns a very good approximation of the real perimiter in meters, but the value is not exact as the Earth's surface is not a plane but a sphere.
In most cases this doesn't matter, but when it does (e.g. for polygons spanning very large distances), there is the ST_LENGTHSPHERE function which returns the correct value, and it can be called with the boundary of the polygon as its argument (as given by the ST_BOUNDARY function).
Examples
SELECT ST_PERIMETER(polygon '((0 0, 1000 1000, 2000 0, 0 0))');
--> 719.695396
See also
ST_DISTANCE(g1: anygeometry, g2: anygeometry) -> float64Returns the distance between two geometries in meters.
Null handling
If any of the arguments is NULL, the function will also return NULL.
Notes
If any geometry is empty, the function will return NULL.
The function returns a very good approximation of the real distance in meters, but the value is not exact as the Earth's surface is not a plane but a sphere.
In most cases this doesn't matter, but when it does (e.g. for calculations of distances between countries or continents), there is the ST_DISTANCESPHERE function which returns the correct value.
Examples
SELECT ST_DISTANCE(point '(11916983 38520414)', point '(12258696 36101539)');
--> 258938.47
SELECT ST_DISTANCE(polygon '((0 0, 10000 0, 8000 4000, 0 0))', linestring '(0 -15000, 15000 0)');
--> 526.984753
See also
ST_DISTANCESPHERE(g1: [multi]point, g2: [multi]point) -> float64Returns the minimum distance in meters between two [multi]point geometries using a spherical earth model.
Arguments
Both the function arguments must be [multi]point geometries. Spherical distance calculations with linear and areal geometries aren't yet supported.
Null handling
If any of the arguments is NULL, the function will also return NULL.
Notes
If any geometry is empty, the function will return NULL.
This function computes the distance using the Haversine formula, but is substantially slower than the approximate ST_DISTANCE function, and should therefore be used only when really neccessary.
Examples
SELECT ST_DISTANCESPHERE(point '(11916983 38520414)', point '(12258696 36101539)');
--> 258915.1211
See also
ST_MAXDISTANCE(g1: anygeometry, g2: anygeometry) -> float64Returns the largest distance between two geometries in meters.
Null handling
If any of the arguments is NULL, the function will also return NULL.
Notes
If g1 and g2 are the same geometry, the function will return the distance between two vertices furthest away from each other in that geometry.
If any geometry is empty, the function will return NULL.
The function returns a very good approximation of the real maximum distance in meters, but the value is not exact as the Earth's surface is not a plane but a sphere.
In most cases it doesn't matter, but in the rare case it does, this should be kept in mind.
Examples
SELECT ST_MAXDISTANCE(linestring '(10 40, 30 10)', point '(40 20)');
--> 5.374211
See also
ST_LONGESTLINE(g1: anygeometry, g2: anygeometry) -> linestringReturns the longest line between the two geometries.
Null handling
If any of the arguments is NULL, the function will also return NULL.
Notes
If there is more than one longest line, the function will return any of them.
The line returned will always start in g1 and end in g2. The length of the line will always be the same as the value of ST_MAXDISTANCE(g1, g2).
If any geometry is empty, the function will return NULL.
Examples
SELECT ST_LONGESTLINE(linestring '(10 40, 30 10)', point '(40 20)');
--> LINESTRING(10 40,40 20)
See also