Spatial Measurement

﻿
﻿ spatial measurement functions can perform basic calculations on geospatial data, such as measuring the distance between two POINT objects or the area of a POLYGON object.
ST_AREA
Returns the area of the specified geospatial object in the specified unit of measurement. 
Syntax
SQL
ST_AREA(geo [, units] [, use_spheroid ] )
ST_AREA(geo [, units] [, use_spheroid ] )
﻿
Argument
Data Type
Description
geo
POINT, LINESTRING, or POLYGON
A geospatial object to be measured in the specified measurement unit. 
units
STRING
Optional. 
﻿
Supported units include "FEET", "KILOMETERS", "MILES", and "METERS".
﻿
If you do not specify this argument, the value defaults to "METERS".
use_spheroid
BOOLEAN
Optional. 
﻿
If you set this value to TRUE, this function uses a spheroid model instead of a spherical model. 
﻿
Defaults to FALSE. 
Example
SQL
SELECT ST_AREA(
        ST_POLYGON(ST_LINESTRING('LINESTRING(2 3, 2 4, 4 2, 2 3)')),
        'MILES');
SELECT ST_AREA(
        ST_POLYGON(ST_LINESTRING('LINESTRING(2 3, 2 4, 4 2, 2 3)')),
        'MILES');
﻿
Output: 196932665.2369081
ST_ANGLE
Calculates the angle between two lines. The lines are represented by three POINT values, including one point for each line (a, b), and a third point (c) that represents the vertex where they intersect. The function calculates the spherical angle as formed by the two great circles defined by (a, c) and (b, c). 
ST_ANGLE returns the value in radians, in the range [0, 2pi], which excludes the value 2pi. 
If either a or b is the same or exactly antipodal to c, the function returns NULL. If any argument is NULL, the function returns NULL.
Syntax
SQL
ST_ANGLE(endpoint_a, vertex_c, endpoint_b)
ST_ANGLE(endpoint_a, vertex_c, endpoint_b)
﻿
Argument
Data Type
Description
endpoint_a
POINT
A POINT that represents an endpoint for a line between its position and the vertex_c value.
vertex_c
POINT
A POINT that represents the intersection between two lines. The lines comprise the endpoints between endpoint_a and vertex_c, and endpoint_b and vertex_c.
endpoint_b
POINT
A POINT that represents an endpoint for a line between its position and the vertex_c value.
Example
SQL
SELECT ST_ANGLE(ST_POINT(1,0), ST_POINT(0,0), ST_POINT(1,1));
SELECT ST_ANGLE(ST_POINT(1,0), ST_POINT(0,0), ST_POINT(1,1));
﻿
Output: 5.49778714378213
ST_AZIMUTH
Returns the azimuth of the line from point1 to point2 in radians. 
Returns NULL if either of the points are empty. Returns 0 if both of the points are the same.
Syntax
SQL
ST_AZIMUTH(point1, point2)
ST_AZIMUTH(point1, point2)
﻿
Argument
Data Type
Description
point1
POINT
An endpoint for a line to be calculated for its azimuth value. 
point2
POINT
An endpoint for a line to be calculated for its azimuth value. 
Example
SQL
SELECT ST_AZIMUTH(ST_POINT(1,1), ST_POINT(2,2));
SELECT ST_AZIMUTH(ST_POINT(1,1), ST_POINT(2,2));
﻿
Output: 0.785398163397448
ST_DISTANCE
Returns the minimum distance between the specified arguments.
ST_DISTANCE returns the minimum distance in the specified unit of measurement. The use_spheroid optional argument enables the computation to use a spheroid model rather than a spherical one. 
Syntax
SQL
ST_DISTANCE(geo1, geo2 [, units] [, use_spheroid] )
ST_DISTANCE(geo1, geo2 [, units] [, use_spheroid] )
﻿
Argument
Data Type
Description
geo1
POINT, LINESTRING, or POLYGON
A geospatial object to be measured for its minimum distance to geo2.
geo2
POINT, LINESTRING, or POLYGON
A geospatial object to be measured for its minimum distance to geo1.
units
STRING
Optional. 
﻿
Supported units include "FEET", "KILOMETERS", "MILES", and "METERS".
﻿
If you do not  specify this argument, the value defaults to "METERS".
use_spheroid
BOOLEAN
Optional. 
﻿
If you set this value to TRUE, this function uses a spheroid model instead of a spherical model. 
﻿
Defaults to FALSE. 
Example
SQL
SELECT ST_DISTANCE(
        ST_LINESTRING('LINESTRING(2 3, 2 4)'),
        ST_LINESTRING('LINESTRING(1 2, 1 4, 1 5)'),
        'METERS',
        true);
SELECT ST_DISTANCE(
        ST_LINESTRING('LINESTRING(2 3, 2 4)'),
        ST_LINESTRING('LINESTRING(1 2, 1 4, 1 5)'),
        'METERS',
        true);
﻿
Output: 111050.10339481
To use ST_DISTANCE as a spatiotemporal function to calculate the minimum simultaneous distance between two linestring-timestamp array pairs, see the ST_DISTANCE﻿ function in Spatiotemporal Measurement﻿. 
ST_DISTANCESPHERE
Returns the minimum distance between the specified arguments, using a spherical computation.  
This function is identical to ST_DISTANCE with the use_spheroid argument set to FALSE. 
SQL
ST_DISTANCESPHERE(geo1, geo2 [, units] )
ST_DISTANCESPHERE(geo1, geo2 [, units] )
﻿
See ST_DISTANCE﻿ for usage example.  
ST_DISTANCESPHEROID
Returns the minimum distance between the specified arguments, using a spheroid computation.  
This function is identical to ST_DISTANCE with the use_spheroid argument set to TRUE. 
SQL
ST_DISTANCESPHEROID(geo1, geo2 [, units] )
ST_DISTANCESPHEROID(geo1, geo2 [, units] )
﻿
See ST_DISTANCE﻿ for usage example. 
ST_HAUSDORFFDISTANCE
Returns the Hausdorff distance between two geographies in a specified measurement. If any argument is NULL or empty, the function returns NULL. 
The two geographies can be POINT, LINESTRING, or POLYGON values. The system promotes these geographies to filled polygons. Behavior is undefined if the resulting polygons are not convex.
Syntax
SQL
ST_HAUSDORFFDISTANCE(geo1, geo2 [, units] [, use_spheroid] )
ST_HAUSDORFFDISTANCE(geo1, geo2 [, units] [, use_spheroid] )
﻿
Argument
Data Type
Description
geo1
POINT, LINESTRING, or POLYGON
A geospatial object to be measured for its Hausdorff distance to geo2.
geo2
POINT, LINESTRING, or POLYGON
A geospatial object to be measured for its Hausdorff distance to geo1.
units
STRING
Optional. 
﻿
Supported units include "FEET", "KILOMETERS", "MILES", and "METERS".
﻿
Defaults to "METERS".
use_spheroid
BOOLEAN
Optional. 
﻿
If you set this argument to  TRUE, this function uses a spheroid model instead of a spherical model. 
﻿
Defaults to FALSE. 
Example
SQL
SELECT ST_HAUSDORFFDISTANCE(
        ST_POLYGON('POLYGON((1 1, 2 2, 1 2, 1 1))'),
        ST_POLYGON('POLYGON((0 0, 2 1, 2 0, 0 0))'),
        'METERS',
        TRUE);
SELECT ST_HAUSDORFFDISTANCE(
        ST_POLYGON('POLYGON((1 1, 2 2, 1 2, 1 1))'),
        ST_POLYGON('POLYGON((0 0, 2 1, 2 0, 0 0))'),
        'METERS',
        TRUE);
﻿
Output: 156899.5136831999
ST_LENGTH
Returns the length of the specified line in the specified measurement unit. 
Returns 0 for all geography types except for LINESTRING. To return the total length of a POLYGON, use ST_PERIMETER﻿.  
Syntax
SQL
ST_LENGTH(geo [, units] [, use_spheroid] )
ST_LENGTH(geo [, units] [, use_spheroid] )
﻿
Argument
Data Type
Description
geo
LINESTRING
A line that is to be measured for its length.
﻿
The function accepts POINT and POLYGON data types, but returns 0. 
units
STRING
Optional. 
﻿
Supported units include "FEET", "KILOMETERS", "MILES", and "METERS".
﻿
Defaults to "METERS".
use_spheroid
BOOLEAN
Optional. 
﻿
If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model. 
﻿
Defaults to FALSE. 
Example
SQL
SELECT ST_LENGTH(
        ST_LINESTRING('LINESTRING(1 2, 1 4)'),
        'METERS',
        false);
SELECT ST_LENGTH(
        ST_LINESTRING('LINESTRING(1 2, 1 4)'),
        'METERS',
        false);
﻿
Output: 221154.8586057658
ST_LENGTH2D
Alias for ST_LENGTH﻿. 
ST_MAXDISTANCE
Returns maximum distance between the specified arguments.
ST_MAXDISTANCE returns the maximum distance in the specified unit of measurement. The use_spheroid optional argument enables the computation to use a spheroid model rather than a spherical one. 
Syntax
SQL
ST_MAXDISTANCE(geo1, geo2 [, units] [, use_spheroid] )
ST_MAXDISTANCE(geo1, geo2 [, units] [, use_spheroid] )
﻿
Argument
Data Type
Description
geo1
POINT, LINESTRING, or POLYGON
A geospatial object to be measured for its maximum distance to geo2.
geo2
POINT, LINESTRING, or POLYGON
A geospatial object to be measured for its maximum distance to geo1.
units
STRING
Optional. 
﻿
Supported units include "FEET", "KILOMETERS", "MILES", and "METERS".
﻿
Defaults to "METERS".
use_spheroid
BOOLEAN
Optional. 
﻿
If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model. 
﻿
Defaults to FALSE. 
Example
SQL
SELECT ST_MAXDISTANCE(
        ST_POLYGON(ST_LINESTRING('LINESTRING(1 2, 1 4, 1 7, 1 2)')),
        ST_POLYGON(ST_LINESTRING('LINESTRING(1 2, 1 4, 1 5, 1 2)')),
        'METERS',
        false);
SELECT ST_MAXDISTANCE(
        ST_POLYGON(ST_LINESTRING('LINESTRING(1 2, 1 4, 1 7, 1 2)')),
        ST_POLYGON(ST_LINESTRING('LINESTRING(1 2, 1 4, 1 5, 1 2)')),
        'METERS',
        false);
﻿
Output: 555975.2598904524
To use ST_MAXDISTANCE as a spatiotemporal function to calculate the maximum simultaneous distance between two linestring-timestamp array pairs, see the ST_MAXDISTANCE﻿ function in Spatiotemporal Measurement﻿. 
ST_PERIMETER
Returns the length of the exterior (outer ring) of the POLYGON in the specified unit of measurement. 
Returns 0 for all geography types except for POLYGON. To return the length of a LINESTRING, use ST_LENGTH﻿.  
Syntax
SQL
ST_PERIMETER(geo, [, units] [, use_spheroid] )
ST_PERIMETER(geo, [, units] [, use_spheroid] )
﻿
Argument
Data Type
Description
geo
POLYGON
A POLYGON that is to be measured for its total perimeter length.
﻿
The function accepts POINT and LINESTRING data types, but returns 0. 
units
STRING
Optional. 
﻿
Supported units include "FEET", "KILOMETERS", "MILES", and "METERS".
﻿
Defaults to "METERS".
use_spheroid
BOOLEAN
Optional. 
﻿
If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model. 
﻿
Defaults to FALSE. 
Example
SQL
SELECT ST_PERIMETER(
        ST_POLYGON(ST_LINESTRING('LINESTRING(1 2, 1 3, 1 3, 1 2)')),
        'METERS',
        false);
SELECT ST_PERIMETER(
        ST_POLYGON(ST_LINESTRING('LINESTRING(1 2, 1 3, 1 3, 1 2)')),
        'METERS',
        false);
﻿
Output: 222390.1039561809
ST_PERIMETER2D
Alias for ST_PERIMETER﻿. 
Related Links
﻿Geospatial Data Types﻿﻿
﻿Spatial Operators﻿﻿
﻿Spatial Relationships﻿﻿

Argument	Data Type	Description
geo	POINT, LINESTRING, or POLYGON	A geospatial object to be measured in the specified measurement unit.
units	STRING	Optional. Supported units include "FEET", "KILOMETERS", "MILES", and "METERS". If you do not specify this argument, the value defaults to "METERS".
use_spheroid	BOOLEAN	Optional. If you set this value to TRUE, this function uses a spheroid model instead of a spherical model. Defaults to FALSE.

Argument	Data Type	Description
endpoint_a	POINT	A POINT that represents an endpoint for a line between its position and the vertex_c value.
vertex_c	POINT	A POINT that represents the intersection between two lines. The lines comprise the endpoints between endpoint_a and vertex_c, and endpoint_b and vertex_c.
endpoint_b	POINT	A POINT that represents an endpoint for a line between its position and the vertex_c value.

Argument	Data Type	Description
point1	POINT	An endpoint for a line to be calculated for its azimuth value.
point2	POINT	An endpoint for a line to be calculated for its azimuth value.

Argument	Data Type	Description
geo1	POINT, LINESTRING, or POLYGON	A geospatial object to be measured for its minimum distance to geo2.
geo2	POINT, LINESTRING, or POLYGON	A geospatial object to be measured for its minimum distance to geo1.
units	STRING	Optional. Supported units include "FEET", "KILOMETERS", "MILES", and "METERS". If you do not specify this argument, the value defaults to "METERS".
use_spheroid	BOOLEAN	Optional. If you set this value to TRUE, this function uses a spheroid model instead of a spherical model. Defaults to FALSE.

Argument	Data Type	Description
geo1	POINT, LINESTRING, or POLYGON	A geospatial object to be measured for its Hausdorff distance to geo2.
geo2	POINT, LINESTRING, or POLYGON	A geospatial object to be measured for its Hausdorff distance to geo1.
units	STRING	Optional. Supported units include "FEET", "KILOMETERS", "MILES", and "METERS". Defaults to "METERS".
use_spheroid	BOOLEAN	Optional. If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model. Defaults to FALSE.

Argument	Data Type	Description
geo	LINESTRING	A line that is to be measured for its length. The function accepts POINT and POLYGON data types, but returns 0.
units	STRING	Optional. Supported units include "FEET", "KILOMETERS", "MILES", and "METERS". Defaults to "METERS".
use_spheroid	BOOLEAN	Optional. If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model. Defaults to FALSE.

Argument	Data Type	Description
geo1	POINT, LINESTRING, or POLYGON	A geospatial object to be measured for its maximum distance to geo2.
geo2	POINT, LINESTRING, or POLYGON	A geospatial object to be measured for its maximum distance to geo1.
units	STRING	Optional. Supported units include "FEET", "KILOMETERS", "MILES", and "METERS". Defaults to "METERS".
use_spheroid	BOOLEAN	Optional. If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model. Defaults to FALSE.

Argument	Data Type	Description
geo	POLYGON	A POLYGON that is to be measured for its total perimeter length. The function accepts POINT and LINESTRING data types, but returns 0.
units	STRING	Optional. Supported units include "FEET", "KILOMETERS", "MILES", and "METERS". Defaults to "METERS".
use_spheroid	BOOLEAN	Optional. If you set this argument to TRUE, this function uses a spheroid model instead of a spherical model. Defaults to FALSE.

Updated 16 May 2024

Did this page help you?

Polygon Constructors

Spatial Operators