---
title: Spatial Measurement
slug: 6i4XCFGQTSmzXPbtCZw6S
description: Use spatial measurement functions in OcientGeo to calculate distances, areas, and more in spatial datasets.
docTags: 
createdAt: Mon Aug 01 2022 18:28:21 GMT+0000 (Coordinated Universal Time)
updatedAt: Mon Mar 30 2026 18:52:41 GMT+0000 (Coordinated Universal Time)
---

OcientGeo™ 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.&#x20;

**Syntax**

```sql
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. <br />Supported units are `'FEET'`, `'KILOMETERS'`, `'MILES'`, and `'METERS'`.<br />The default value is `'METERS'`.                 |
| `use_spheroid` | `BOOLEAN`                           | Optional. <br />If you set this value to `TRUE`, this function uses a spheroid model instead of a spherical model. <br />Defaults to `FALSE`.  |

**Example**

```sql
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) representing 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).&#x20;

ST\_ANGLE returns the value in radians, in the range `[0, 2pi]`, excluding the value `2pi`.&#x20;

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)
```

| **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));
```

*Output*: `5.49778714378213`

# ST\_AZIMUTH

Returns the azimuth of the line from `point1` to `point2` in radians.&#x20;

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)
```

| **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));
```

*Output*: `0.785398163397448`

# ST\_DISTANCE

Returns the minimum distance between the specified arguments.

The `ST_DISTANCE` function 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.&#x20;

**Syntax**

```sql
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. <br />Supported units include `'FEET'`, `'KILOMETERS'`, `'MILES'`, and `'METERS'`.<br />If you do not specify this argument, the value defaults to `'METERS'`. |
| `use_spheroid` | `BOOLEAN`                           | Optional. <br />If you set this value to `TRUE`, this function uses a spheroid model instead of a spherical model. <br />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);
```

*Output*: `111050.10339481`

:::hint{type="info"}
To use ST\_DISTANCE as a spatiotemporal function to calculate the minimum simultaneous distance between two linestring-timestamp array pairs, see the [ST\_DISTANCE](<./Spatiotemporal Measurement.md>) function in [Spatiotemporal Measurement](<./Spatiotemporal Measurement.md>).&#x20;
:::

# ST\_DISTANCESPHERE

Returns the minimum distance between the specified arguments using a spherical computation. &#x20;

This function is identical to ST\_DISTANCE with the `use_spheroid` argument set to `FALSE`.&#x20;

```sql
ST_DISTANCESPHERE(geo1, geo2 [, units] )
```

See [ST\_DISTANCE](./#stdistance) for usage example. &#x20;

# ST\_DISTANCESPHEROID

Returns the minimum distance between the specified arguments using a spheroid computation. &#x20;

This function is identical to ST\_DISTANCE with the `use_spheroid` argument set to `TRUE`.&#x20;

```sql
ST_DISTANCESPHEROID(geo1, geo2 [, units] )
```

See [ST\_DISTANCE](./#stdistance) for usage example.&#x20;

# ST\_EUCLIDEANDISTANCE3D

Returns the minimum distance between two geospatial points with altitude values. The distance represents the length of a Euclidean line between the points.&#x20;

**Syntax**

```sql
ST_EUCLIDEANDISTANCE3D(point1, altitude1, point2, altitude2 [, units] )
```

| **Argument** | **Data** **Type** | **Description**                                                                                                                                                                                                                          |
| ------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `point1`     | `POINT`           | A geospatial point that represents a Euclidean line with `point2`.                                                                                                                                                                       |
| `altitude1`  | `DOUBLE`          | Distance from the surface of the Earth for `point1`. <br />This argument uses meters, unless you specify a different unit of measurement with the `units` argument.                                                                      |
| `point2`     | `POINT`           | A geospatial point that represents a Euclidean line with `point1`.                                                                                                                                                                       |
| `altitude2`  | `DOUBLE`          | Distance from the surface of the Earth for `point2`. <br />This argument uses meters, unless you specify a different unit of measurement with the `units` argument.                                                                      |
| `units`      | `VARCHAR`         | Optional. <br />This argument specifies the unit of measurement for the distance input arguments and the function output. Supported units are `'FEET'`, `'KILOMETERS'`, `'MILES'`, and `'METERS'`.<br />The default value is `'METERS'`. |

**Example**

```sql
SELECT ST_EUCLIDEANDISTANCE3D(
    ST_POINT(0,0),1000.0,
	ST_POINT(0,1),1000.0,
	'METERS');
```

*Output*: `111211.09372321835`

# ST\_HAUSDORFFDISTANCE

Returns the Hausdorff distance between two geographies in a specified measurement. If any argument is NULL or empty, the function returns NULL.&#x20;

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] )
```

| **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. <br />Supported units are `'FEET'`, `'KILOMETERS'`, `'MILES'`, and `'METERS'`.<br />The default value is `'METERS'`.                     |
| `use_spheroid` | `BOOLEAN`                           | Optional. <br />If you set this argument to  `TRUE`, this function uses a spheroid model instead of a spherical model. <br />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);
```

*Output*: `156899.5136831999`

# ST\_LENGTH

Returns the length of the specified line in the specified measurement unit.&#x20;

Returns `0` for all geography types except for `LINESTRING`. To return the total length of a `POLYGON`, use [ST\_PERIMETER](./#stperimeter). &#x20;

**Syntax**

```sql
ST_LENGTH(geo [, units] [, use_spheroid] )
```

| **Argument**   | **Data** **Type** | **Description**                                                                                                                                   |
| -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `geo`          | `LINESTRING`      | A line that is to be measured for its length.<br />The function accepts `POINT` and `POLYGON` data types, but returns `0`.                        |
| `units`        | `STRING`          | Optional. <br />Supported units are `'FEET'`, `'KILOMETERS'`, `'MILES'`, and `'METERS'`.<br />The default value is `'METERS'`.                    |
| `use_spheroid` | `BOOLEAN`         | Optional. <br />If you set this argument to `TRUE`, this function uses a spheroid model instead of a spherical model. <br />Defaults to `FALSE`.  |

**Example**

```sql
SELECT ST_LENGTH(
        ST_LINESTRING('LINESTRING(1 2, 1 4)'),
        'METERS',
        false);
```

*Output*: `222390.10395618092`

# ST\_LENGTH2D

Alias for [ST\_LENGTH](./#stlength).&#x20;

# ST\_MINIMUMDISTANCETOSURFACE

Calculates the shortest distance between any point along a Euclidean line segment in three-dimensional space and the surface of the Earth. Two input points and their altitudes define this line segment. The line can go above or below the surface of the Earth.&#x20;

The function takes the difference of both points from the center of the Earth to calculate the distance between the nearest point of the line and the surface of the Earth.&#x20;

The function returns the distance in meters or another unit of measurement if specified. If the returned distance is positive, the shortest distance is above the surface. If the result is negative, the shortest distance is below the surface.&#x20;

**Syntax**

```sql
ST_MINIMUMDISTANCETOSURFACE(point1, altitude1, point2, altitude2 [, units] )
```

| **Argument** | **Data** **Type** | **Description**                                                                                                                                                                                                                          |
| ------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `point1`     | `POINT`           | A geospatial point that represents a Euclidean line with `point2`.                                                                                                                                                                       |
| `altitude1`  | `DOUBLE`          | Distance from the surface of the Earth for `point1`. <br />This argument uses meters, unless you specify a different unit of measurement with the `units` argument.                                                                      |
| `point2`     | `POINT`           | A geospatial point that represents a Euclidean line with `point1`.                                                                                                                                                                       |
| `altitude2`  | `DOUBLE`          | Distance from the surface of the Earth for `point2`. <br />This argument uses meters, unless you specify a different unit of measurement with the `units` argument.                                                                      |
| `units`      | `VARCHAR`         | Optional. <br />This argument specifies the unit of measurement for the distance input arguments and the function output. Supported units are `'FEET'`, `'KILOMETERS'`, `'MILES'`, and `'METERS'`.<br />The default value is `'METERS'`. |

**Examples**

This example takes a line from two points and calculates the distance of the nearest point to the surface of the Earth.&#x20;

```sql
SELECT ST_MINIMUMDISTANCETOSURFACE(
    ST_POINT(0,0),1000.0,
	ST_POINT(0,1),1000.0,
	'METERS');
```

*Output*: `757.3734914669767`

In this example, the output is negative, meaning the smallest distance is actually below the surface of the Earth.&#x20;

```sql
SELECT ST_MINIMUMDISTANCETOSURFACE(
    ST_POINT(0,0),1000.0,
	ST_POINT(0,5),1000.0,
	'METERS');
```

*Output*: `-5064.738915202208`

# ST\_MAXDISTANCE

Returns the 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.&#x20;

**Syntax**

```sql
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. <br />Supported units are `'FEET'`, `'KILOMETERS'`, `'MILES'`, and `'METERS'`.<br />The default value is `'METERS'`.                    |
| `use_spheroid` | `BOOLEAN`                           | Optional. <br />If you set this argument to `TRUE`, this function uses a spheroid model instead of a spherical model. <br />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);
```

*Output*: `555975.2598904524`

:::hint{type="info"}
To use ST\_MAXDISTANCE as a spatiotemporal function to calculate the maximum simultaneous distance between two linestring-timestamp array pairs, see the [ST\_MAXDISTANCE](<./Spatiotemporal Measurement.md>) function in [Spatiotemporal Measurement](<./Spatiotemporal Measurement.md>).&#x20;
:::

# ST\_PERIMETER

Returns the length of the exterior (outer ring) of the `POLYGON` in the specified unit of measurement.&#x20;

Returns `0` for all geography types except for `POLYGON`. To return the length of a `LINESTRING`, use [ST\_LENGTH](./#stlength). &#x20;

**Syntax**

```sql
ST_PERIMETER(geo, [, units] [, use_spheroid] )
```

| **Argument**   | **Data** **Type** | **Description**                                                                                                                                     |
| -------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `geo`          | `POLYGON`         | A `POLYGON` that is to be measured for its total perimeter length.<br />The function accepts `POINT` and `LINESTRING` data types, but returns `0`.  |
| `units`        | `STRING`          | Optional. <br />Supported units are `'FEET'`, `'KILOMETERS'`, `'MILES'`, and `'METERS'`.<br />The default value is `'METERS'`.                      |
| `use_spheroid` | `BOOLEAN`         | Optional. <br />If you set this argument to `TRUE`, this function uses a spheroid model instead of a spherical model. <br />Defaults to `FALSE`.    |

**Example**

```sql
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](./#stperimeter).&#x20;

# Related Links

[Geospatial Data Types](<././Data Types.md>)

[Spatial Operators](<./Spatial Operators.md>)

[Spatial Relationships](<./Spatial Relationships.md>)
