# Elevation

## Look up elevation at one or more points

`$ plaza elevation lookup`

**get** `/api/v1/elevation`

Look up elevation at one or more points

### Parameters

- `--lat: optional number`

  Latitude (single point)

- `--lng: optional number`

  Longitude (single point)

- `--locations: optional string`

  Pipe-separated lng,lat pairs (batch)

- `--output-fields: optional string`

  Comma-separated property fields to include

- `--output-include: optional string`

  Extra computed fields: bbox, center

- `--output-precision: optional number`

  Coordinate decimal precision (1-15, default 7)

### Returns

- `elevation_lookup_result: object { geometry, properties, type }`

  GeoJSON Point Feature with a 3D coordinate [lng, lat, elevation] per RFC 7946 §3.1.1. The elevation is also available in `properties.elevation_m` for convenience.

  - `geometry: object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

      - `Point: array of number`

        [longitude, latitude] or [longitude, latitude, elevation]

      - `LineString or MultiPoint: array of array of number`

        Array of [lng, lat] positions

      - `Polygon or MultiLineString: array of array of array of number`

        Array of linear rings / line strings

      - `MultiPolygon: array of array of array of array of number`

        Array of polygons

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { elevation_m }`

    - `elevation_m: number`

      Elevation in meters above mean sea level (WGS84 EGM96 geoid)

  - `type: "Feature"`

    - `"Feature"`

### Example

```cli
plaza elevation lookup \
  --api-key 'My API Key'
```

#### Response

```json
{
  "geometry": {
    "coordinates": [
      2.3522,
      48.8566
    ],
    "type": "Point"
  },
  "properties": {
    "elevation_m": 35.2
  },
  "type": "Feature"
}
```

## Look up elevation at one or more points

`$ plaza elevation lookup-post`

**post** `/api/v1/elevation`

Look up elevation at one or more points

### Parameters

- `--lat: optional number`

  Latitude (single point)

- `--lng: optional number`

  Longitude (single point)

- `--locations: optional string`

  Pipe-separated lng,lat pairs (batch)

- `--output-fields: optional string`

  Comma-separated property fields to include

- `--output-include: optional string`

  Extra computed fields: bbox, center

- `--output-precision: optional number`

  Coordinate decimal precision (1-15, default 7)

### Returns

- `elevation_lookup_result: object { geometry, properties, type }`

  GeoJSON Point Feature with a 3D coordinate [lng, lat, elevation] per RFC 7946 §3.1.1. The elevation is also available in `properties.elevation_m` for convenience.

  - `geometry: object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

      - `Point: array of number`

        [longitude, latitude] or [longitude, latitude, elevation]

      - `LineString or MultiPoint: array of array of number`

        Array of [lng, lat] positions

      - `Polygon or MultiLineString: array of array of array of number`

        Array of linear rings / line strings

      - `MultiPolygon: array of array of array of array of number`

        Array of polygons

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { elevation_m }`

    - `elevation_m: number`

      Elevation in meters above mean sea level (WGS84 EGM96 geoid)

  - `type: "Feature"`

    - `"Feature"`

### Example

```cli
plaza elevation lookup-post \
  --api-key 'My API Key'
```

#### Response

```json
{
  "geometry": {
    "coordinates": [
      2.3522,
      48.8566
    ],
    "type": "Point"
  },
  "properties": {
    "elevation_m": 35.2
  },
  "type": "Feature"
}
```

## Look up elevation for multiple coordinates

`$ plaza elevation batch`

**post** `/api/v1/elevation/batch`

Look up elevation for multiple coordinates

### Parameters

- `--coordinate: array of object { lat, lng }`

  Coordinates to look up elevations for (max 50)

### Returns

- `elevation_batch_result: object { features, type }`

  GeoJSON FeatureCollection of elevation Point Features with 3D coordinates. Order matches the input coordinates array.

  - `features: array of ElevationLookupResult`

    Elevation results in the same order as input coordinates

    - `geometry: object { coordinates, type }`

      GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

      - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

        Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

        - `Point: array of number`

          [longitude, latitude] or [longitude, latitude, elevation]

        - `LineString or MultiPoint: array of array of number`

          Array of [lng, lat] positions

        - `Polygon or MultiLineString: array of array of array of number`

          Array of linear rings / line strings

        - `MultiPolygon: array of array of array of array of number`

          Array of polygons

      - `type: "Point" or "LineString" or "Polygon" or 3 more`

        Geometry type

        - `"Point"`

        - `"LineString"`

        - `"Polygon"`

        - `"MultiPoint"`

        - `"MultiLineString"`

        - `"MultiPolygon"`

    - `properties: object { elevation_m }`

      - `elevation_m: number`

        Elevation in meters above mean sea level (WGS84 EGM96 geoid)

    - `type: "Feature"`

      - `"Feature"`

  - `type: "FeatureCollection"`

    - `"FeatureCollection"`

### Example

```cli
plaza elevation batch \
  --api-key 'My API Key' \
  --coordinate '{lat: 48.8566, lng: 2.3522}' \
  --coordinate '{lat: 45.764, lng: 4.8357}'
```

#### Response

```json
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "elevation_m": 35.2
      },
      "type": "Feature"
    }
  ],
  "type": "FeatureCollection"
}
```

## Elevation profile along coordinates

`$ plaza elevation profile`

**post** `/api/v1/elevation/profile`

Elevation profile along coordinates

### Parameters

- `--coordinate: array of object { lat, lng }`

  Path coordinates in order of travel (min 2, max 50)

### Returns

- `elevation_profile_result: object { geometry, properties, type }`

  GeoJSON LineString Feature with 3D coordinates [lng, lat, elevation] representing the elevation profile along the input path. Summary statistics are in properties.

  - `geometry: object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

      - `Point: array of number`

        [longitude, latitude] or [longitude, latitude, elevation]

      - `LineString or MultiPoint: array of array of number`

        Array of [lng, lat] positions

      - `Polygon or MultiLineString: array of array of array of number`

        Array of linear rings / line strings

      - `MultiPolygon: array of array of array of array of number`

        Array of polygons

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { avg_elevation_m, max_elevation_m, min_elevation_m, 2 more }`

    Elevation profile summary statistics

    - `avg_elevation_m: number`

      Average elevation along the profile in meters

    - `max_elevation_m: number`

      Maximum elevation along the profile in meters

    - `min_elevation_m: number`

      Minimum elevation along the profile in meters

    - `total_ascent_m: number`

      Total cumulative elevation gain in meters

    - `total_descent_m: number`

      Total cumulative elevation loss in meters

  - `type: "Feature"`

    - `"Feature"`

### Example

```cli
plaza elevation profile \
  --api-key 'My API Key' \
  --coordinate '{lat: 48.8566, lng: 2.3522}' \
  --coordinate '{lat: 48.858, lng: 2.34}' \
  --coordinate '{lat: 48.8584, lng: 2.2945}'
```

#### Response

```json
{
  "geometry": {
    "coordinates": [
      2.3522,
      48.8566
    ],
    "type": "Point"
  },
  "properties": {
    "avg_elevation_m": 67.8,
    "max_elevation_m": 155.3,
    "min_elevation_m": 28.1,
    "total_ascent_m": 127.4,
    "total_descent_m": 89.2
  },
  "type": "Feature"
}
```

## Domain Types

### Elevation Batch Result

- `elevation_batch_result: object { features, type }`

  GeoJSON FeatureCollection of elevation Point Features with 3D coordinates. Order matches the input coordinates array.

  - `features: array of ElevationLookupResult`

    Elevation results in the same order as input coordinates

    - `geometry: object { coordinates, type }`

      GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

      - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

        Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

        - `Point: array of number`

          [longitude, latitude] or [longitude, latitude, elevation]

        - `LineString or MultiPoint: array of array of number`

          Array of [lng, lat] positions

        - `Polygon or MultiLineString: array of array of array of number`

          Array of linear rings / line strings

        - `MultiPolygon: array of array of array of array of number`

          Array of polygons

      - `type: "Point" or "LineString" or "Polygon" or 3 more`

        Geometry type

        - `"Point"`

        - `"LineString"`

        - `"Polygon"`

        - `"MultiPoint"`

        - `"MultiLineString"`

        - `"MultiPolygon"`

    - `properties: object { elevation_m }`

      - `elevation_m: number`

        Elevation in meters above mean sea level (WGS84 EGM96 geoid)

    - `type: "Feature"`

      - `"Feature"`

  - `type: "FeatureCollection"`

    - `"FeatureCollection"`

### Elevation Lookup Result

- `elevation_lookup_result: object { geometry, properties, type }`

  GeoJSON Point Feature with a 3D coordinate [lng, lat, elevation] per RFC 7946 §3.1.1. The elevation is also available in `properties.elevation_m` for convenience.

  - `geometry: object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

      - `Point: array of number`

        [longitude, latitude] or [longitude, latitude, elevation]

      - `LineString or MultiPoint: array of array of number`

        Array of [lng, lat] positions

      - `Polygon or MultiLineString: array of array of array of number`

        Array of linear rings / line strings

      - `MultiPolygon: array of array of array of array of number`

        Array of polygons

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { elevation_m }`

    - `elevation_m: number`

      Elevation in meters above mean sea level (WGS84 EGM96 geoid)

  - `type: "Feature"`

    - `"Feature"`

### Elevation Profile Request

- `elevation_profile_request: object { coordinates }`

  Request body for elevation profile along a path. Provide at least 2 coordinates defining the path. Maximum 50 coordinates per request.

  - `coordinates: array of object { lat, lng }`

    Path coordinates in order of travel (min 2, max 50)

    - `lat: number`

      Latitude in decimal degrees (-90 to 90)

    - `lng: number`

      Longitude in decimal degrees (-180 to 180)

### Elevation Profile Result

- `elevation_profile_result: object { geometry, properties, type }`

  GeoJSON LineString Feature with 3D coordinates [lng, lat, elevation] representing the elevation profile along the input path. Summary statistics are in properties.

  - `geometry: object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

      - `Point: array of number`

        [longitude, latitude] or [longitude, latitude, elevation]

      - `LineString or MultiPoint: array of array of number`

        Array of [lng, lat] positions

      - `Polygon or MultiLineString: array of array of array of number`

        Array of linear rings / line strings

      - `MultiPolygon: array of array of array of array of number`

        Array of polygons

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { avg_elevation_m, max_elevation_m, min_elevation_m, 2 more }`

    Elevation profile summary statistics

    - `avg_elevation_m: number`

      Average elevation along the profile in meters

    - `max_elevation_m: number`

      Maximum elevation along the profile in meters

    - `min_elevation_m: number`

      Minimum elevation along the profile in meters

    - `total_ascent_m: number`

      Total cumulative elevation gain in meters

    - `total_descent_m: number`

      Total cumulative elevation loss in meters

  - `type: "Feature"`

    - `"Feature"`