# Elevation

## Look up elevation at one or more points

`elevation.lookup(**kwargs) -> ElevationLookupResult`

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

Look up elevation at one or more points

### Parameters

- `lat: Float`

  Latitude (single point)

- `lng: Float`

  Longitude (single point)

- `locations: String`

  Pipe-separated lng,lat pairs (batch)

- `output_fields: String`

  Comma-separated property fields to include

- `output_include: String`

  Extra computed fields: bbox, center

- `output_precision: Integer`

  Coordinate decimal precision (1-15, default 7)

### Returns

- `class ElevationLookupResult`

  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: GeoJsonGeometry`

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

    - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

      - `Array[Float]`

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

      - `Array[Array[Float]]`

        Array of [lng, lat] positions

      - `Array[Array[Array[Float]]]`

        Array of linear rings / line strings

      - `Array[Array[Array[Array[Float]]]]`

        Array of polygons

    - `type: :Point | :LineString | :Polygon | 3 more`

      Geometry type

      - `:Point`

      - `:LineString`

      - `:Polygon`

      - `:MultiPoint`

      - `:MultiLineString`

      - `:MultiPolygon`

  - `properties: { elevation_m}`

    - `elevation_m: Float`

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

  - `type: :Feature`

    - `:Feature`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

elevation_lookup_result = plaza.elevation.lookup

puts(elevation_lookup_result)
```

#### 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

`elevation.lookup_post(**kwargs) -> ElevationLookupResult`

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

Look up elevation at one or more points

### Parameters

- `lat: Float`

  Latitude (single point)

- `lng: Float`

  Longitude (single point)

- `locations: String`

  Pipe-separated lng,lat pairs (batch)

- `output_fields: String`

  Comma-separated property fields to include

- `output_include: String`

  Extra computed fields: bbox, center

- `output_precision: Integer`

  Coordinate decimal precision (1-15, default 7)

### Returns

- `class ElevationLookupResult`

  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: GeoJsonGeometry`

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

    - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

      - `Array[Float]`

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

      - `Array[Array[Float]]`

        Array of [lng, lat] positions

      - `Array[Array[Array[Float]]]`

        Array of linear rings / line strings

      - `Array[Array[Array[Array[Float]]]]`

        Array of polygons

    - `type: :Point | :LineString | :Polygon | 3 more`

      Geometry type

      - `:Point`

      - `:LineString`

      - `:Polygon`

      - `:MultiPoint`

      - `:MultiLineString`

      - `:MultiPolygon`

  - `properties: { elevation_m}`

    - `elevation_m: Float`

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

  - `type: :Feature`

    - `:Feature`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

elevation_lookup_result = plaza.elevation.lookup_post

puts(elevation_lookup_result)
```

#### Response

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

## Look up elevation for multiple coordinates

`elevation.batch(**kwargs) -> ElevationBatchResult`

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

Look up elevation for multiple coordinates

### Parameters

- `coordinates: Array[{ lat, lng}]`

  Coordinates to look up elevations for (max 50)

  - `lat: Float`

    Latitude in decimal degrees (-90 to 90)

  - `lng: Float`

    Longitude in decimal degrees (-180 to 180)

### Returns

- `class ElevationBatchResult`

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

  - `features: Array[ElevationLookupResult]`

    Elevation results in the same order as input coordinates

    - `geometry: GeoJsonGeometry`

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

      - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

        - `Array[Float]`

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

        - `Array[Array[Float]]`

          Array of [lng, lat] positions

        - `Array[Array[Array[Float]]]`

          Array of linear rings / line strings

        - `Array[Array[Array[Array[Float]]]]`

          Array of polygons

      - `type: :Point | :LineString | :Polygon | 3 more`

        Geometry type

        - `:Point`

        - `:LineString`

        - `:Polygon`

        - `:MultiPoint`

        - `:MultiLineString`

        - `:MultiPolygon`

    - `properties: { elevation_m}`

      - `elevation_m: Float`

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

    - `type: :Feature`

      - `:Feature`

  - `type: :FeatureCollection`

    - `:FeatureCollection`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

elevation_batch_result = plaza.elevation.batch(coordinates: [{lat: 48.8566, lng: 2.3522}, {lat: 45.764, lng: 4.8357}])

puts(elevation_batch_result)
```

#### Response

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

## Elevation profile along coordinates

`elevation.profile(**kwargs) -> ElevationProfileResult`

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

Elevation profile along coordinates

### Parameters

- `coordinates: Array[{ lat, lng}]`

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

  - `lat: Float`

    Latitude in decimal degrees (-90 to 90)

  - `lng: Float`

    Longitude in decimal degrees (-180 to 180)

### Returns

- `class ElevationProfileResult`

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

  - `geometry: GeoJsonGeometry`

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

    - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

      - `Array[Float]`

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

      - `Array[Array[Float]]`

        Array of [lng, lat] positions

      - `Array[Array[Array[Float]]]`

        Array of linear rings / line strings

      - `Array[Array[Array[Array[Float]]]]`

        Array of polygons

    - `type: :Point | :LineString | :Polygon | 3 more`

      Geometry type

      - `:Point`

      - `:LineString`

      - `:Polygon`

      - `:MultiPoint`

      - `:MultiLineString`

      - `:MultiPolygon`

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

    Elevation profile summary statistics

    - `avg_elevation_m: Float`

      Average elevation along the profile in meters

    - `max_elevation_m: Float`

      Maximum elevation along the profile in meters

    - `min_elevation_m: Float`

      Minimum elevation along the profile in meters

    - `total_ascent_m: Float`

      Total cumulative elevation gain in meters

    - `total_descent_m: Float`

      Total cumulative elevation loss in meters

  - `type: :Feature`

    - `:Feature`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

elevation_profile_result = plaza.elevation.profile(
  coordinates: [{lat: 48.8566, lng: 2.3522}, {lat: 48.858, lng: 2.34}, {lat: 48.8584, lng: 2.2945}]
)

puts(elevation_profile_result)
```

#### 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

- `class ElevationBatchResult`

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

  - `features: Array[ElevationLookupResult]`

    Elevation results in the same order as input coordinates

    - `geometry: GeoJsonGeometry`

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

      - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

        - `Array[Float]`

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

        - `Array[Array[Float]]`

          Array of [lng, lat] positions

        - `Array[Array[Array[Float]]]`

          Array of linear rings / line strings

        - `Array[Array[Array[Array[Float]]]]`

          Array of polygons

      - `type: :Point | :LineString | :Polygon | 3 more`

        Geometry type

        - `:Point`

        - `:LineString`

        - `:Polygon`

        - `:MultiPoint`

        - `:MultiLineString`

        - `:MultiPolygon`

    - `properties: { elevation_m}`

      - `elevation_m: Float`

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

    - `type: :Feature`

      - `:Feature`

  - `type: :FeatureCollection`

    - `:FeatureCollection`

### Elevation Lookup Result

- `class ElevationLookupResult`

  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: GeoJsonGeometry`

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

    - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

      - `Array[Float]`

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

      - `Array[Array[Float]]`

        Array of [lng, lat] positions

      - `Array[Array[Array[Float]]]`

        Array of linear rings / line strings

      - `Array[Array[Array[Array[Float]]]]`

        Array of polygons

    - `type: :Point | :LineString | :Polygon | 3 more`

      Geometry type

      - `:Point`

      - `:LineString`

      - `:Polygon`

      - `:MultiPoint`

      - `:MultiLineString`

      - `:MultiPolygon`

  - `properties: { elevation_m}`

    - `elevation_m: Float`

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

  - `type: :Feature`

    - `:Feature`

### Elevation Profile Request

- `class ElevationProfileRequest`

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

  - `coordinates: Array[{ lat, lng}]`

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

    - `lat: Float`

      Latitude in decimal degrees (-90 to 90)

    - `lng: Float`

      Longitude in decimal degrees (-180 to 180)

### Elevation Profile Result

- `class ElevationProfileResult`

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

  - `geometry: GeoJsonGeometry`

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

    - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

      - `Array[Float]`

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

      - `Array[Array[Float]]`

        Array of [lng, lat] positions

      - `Array[Array[Array[Float]]]`

        Array of linear rings / line strings

      - `Array[Array[Array[Array[Float]]]]`

        Array of polygons

    - `type: :Point | :LineString | :Polygon | 3 more`

      Geometry type

      - `:Point`

      - `:LineString`

      - `:Polygon`

      - `:MultiPoint`

      - `:MultiLineString`

      - `:MultiPolygon`

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

    Elevation profile summary statistics

    - `avg_elevation_m: Float`

      Average elevation along the profile in meters

    - `max_elevation_m: Float`

      Maximum elevation along the profile in meters

    - `min_elevation_m: Float`

      Minimum elevation along the profile in meters

    - `total_ascent_m: Float`

      Total cumulative elevation gain in meters

    - `total_descent_m: Float`

      Total cumulative elevation loss in meters

  - `type: :Feature`

    - `:Feature`