> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spatiotemporal Measurement

export const OcientGeo = "OcientGeo™";

{OcientGeo} spatiotemporal measurement functions can perform basic calculations on geospatial data that is paired with TIMESTAMP data.

## ST\_DISTANCE

Returns the two-dimensional interpolated minimum simultaneous distance between two `LINESTRING-TIMESTAMP` array pairs in the specified unit of measurement.

If any argument is NULL or empty, the function returns NULL. If either `LINESTRING-TIMESTAMP` array pair has a mismatched number of points and timestamps, the function returns an error.

Behavior is undefined if either timestamp array is not monotonically increasing.

```sql SQL theme={null}
ST_DISTANCE(geo1, ts_arr1, geo2, ts_arr2, units [, use_spheroid] )
```

| **Argument**   | **Data** **Type** | **Description**                                                                                                                                                                            |
| -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `geo1`         | `LINESTRING`      | A geospatial object to be evaluated for its minimum cotemporal distance from `geo2`.                                                                                                       |
| `ts_arr1`      | `TIMESTAMP ARRAY` | A timestamp array that is paired with `geo1`.                                                                                                                                              |
| `geo2`         | `LINESTRING`      | A geospatial object to be evaluated for its minimum cotemporal distance from `geo1`.                                                                                                       |
| `ts_arr2`      | `TIMESTAMP ARRAY` | A timestamp array that is paired with `geo2`.                                                                                                                                              |
| `units`        | `STRING`          | The unit of measurement used for the minimum cotemporal distance. <br />Accepted options include `'FEET'`, `'KILOMETERS'`, `'MILES'`, or `'METERS'`.<br />The default value is `'METERS'`. |
| `use_spheroid` | `BOOLEAN`         | Optional. <br /><br />If you set this argument to `TRUE`, this function uses a spheroid model instead of a spherical model.<br /> <br />The default value is `FALSE`.                      |

**Example**

```sql SQL theme={null}
SELECT ST_DISTANCE(
        ST_LINESTRING('linestring(0 0,0 12)'),
        TIMESTAMP [](
            '2020-07-04 07:00:00.000000000',
            '2020-07-04 11:00:00.000000000'),
        ST_LINESTRING('linestring(0 0,6 0)'),
        TIMESTAMP [](
            '2020-07-04 08:00:00.000000000',
            '2020-07-04 10:00:00.00000000'),
        'MILES',
        TRUE);
```

*Output*: `206.124`

<Info>
  To use ST\_DISTANCE as a spatial function to calculate the minimum distance between two points, see the [ST\_DISTANCE](/spatial-measurement#st_distance) function in the Spatial Measurement section.
</Info>

## ST\_MAXDISTANCE

Returns the two-dimensional interpolated maximum cotemporal distance between two `LINESTRING-TIMESTAMP` array pairs in the specified unit of measurement.

If any argument is NULL or empty, the function returns NULL. If either `LINESTRING-TIMESTAMP` array pair has a mismatched number of points and timestamps, the function returns an error.

Behavior is undefined if either timestamp array is not monotonically increasing.

```sql SQL theme={null}
ST_MAXDISTANCE(geo1, ts_arr1, geo2, ts_arr2, units [, use_spheroid] )
```

| **Argument**   | **Data** **Type** | **Description**                                                                                                                                                                            |
| -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `geo1`         | `LINESTRING`      | A geospatial object to be evaluated for its maximum cotemporal distance from `geo2`.                                                                                                       |
| `ts_arr1`      | `TIMESTAMP ARRAY` | A `TIMESTAMP ARRAY` that is paired with `geo1`.                                                                                                                                            |
| `geo2`         | `LINESTRING`      | A geospatial object to be evaluated for its maximum cotemporal distance from `geo1`.                                                                                                       |
| `ts_arr2`      | `TIMESTAMP ARRAY` | A `TIMESTAMP ARRAY` that is paired with `geo2`.                                                                                                                                            |
| `units`        | `STRING`          | The unit of measurement used for the maximum cotemporal distance. <br />Accepted options include `'FEET'`, `'KILOMETERS'`, `'MILES'`, or `'METERS'`.<br />The default value is `'METERS'`. |
| `use_spheroid` | `BOOLEAN`         | Optional. <br /><br />If you set this argument to `TRUE`, this function uses a spheroid model instead of a spherical model. <br /><br />The default value is `FALSE`.                      |

**Example**

```sql SQL theme={null}
SELECT ST_MAXDISTANCE(
    ST_LINESTRING('linestring(0 0,0 12)'),
        TIMESTAMP[]('2020-07-04 07:00:00.000000000', '2020-07-04 11:00:00.000000000'),
    ST_LINESTRING('linestring(0 0,6 0)'),
        TIMESTAMP[]('2020-07-04 08:00:00.000000000', '2020-07-04 10:00:00.00000000'),
    'MILES',
    TRUE);
```

*Output*: `743.83`

<Info>
  To use ST\_MAXDISTANCE as a spatial function to calculate the maximum distance between two points, see the [ST\_MAXDISTANCE](/spatial-measurement#st_maxdistance) function in the Spatial Measurement section.
</Info>

## ST\_TOTALSECONDSININTERSECTION

Returns the total number of seconds spent in the intersection result calculated by the spatiotemporal version of [ST\_INTERSECTION](/spatiotemporal-operators#st_intersection).

Execute this function only with the result from ST\_INTERSECTION. If the input is an empty, correctly typed tuple, this function returns 0 seconds. If the input is NULL, this function returns NULL.

```sql SQL theme={null}
ST_TOTALSECONDSININTERSECTION(tpl)
```

| **Argument** | **Data** **Type**                     | **Description**                                                                            |
| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `tpl`        | Tuple of `LINESTRING-TIMESTAMP` pairs | A tuple of `LINESTRING-TIMESTAMP` pairs used to evaluate how long an intersection existed. |

**Example**

```sql SQL theme={null}
SELECT ST_TOTALSECONDSININTERSECTION(
    ST_INTERSECTION(
        ST_LINESTRING('LINESTRING(1 1,2 2,1 1)'),
            TIMESTAMP[](
                '2020-07-04 07:00:00.000000000',
                '2020-07-04 11:00:00.000000000',
                '2020-07-04 12:00:00.000000000'),
        ST_LINESTRING('LINESTRING(2 2,1 1)')));
```

*Output*: `18000.0`

## Related Links

[Geospatial Data Types](/data-types#geospatial-data-types)

[Spatiotemporal Operators](/spatiotemporal-operators)