# Elevation

## Look up elevation at one or more points

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

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

Look up elevation at one or more points

### Parameters

- `lat: Optional[float]`

  Latitude (single point)

- `lng: Optional[float]`

  Longitude (single point)

- `locations: Optional[str]`

  Pipe-separated lng,lat pairs (batch)

- `output_fields: Optional[str]`

  Comma-separated property fields to include

- `output_include: Optional[str]`

  Extra computed fields: bbox, center

- `output_precision: Optional[int]`

  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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

      - `List[float]`

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

      - `List[List[float]]`

        Array of [lng, lat] positions

      - `List[List[List[float]]]`

        Array of linear rings / line strings

      - `List[List[List[List[float]]]]`

        Array of polygons

    - `type: Literal["Point", "LineString", "Polygon", 3 more]`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: Properties`

    - `elevation_m: float`

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

  - `type: Literal["Feature"]`

    - `"Feature"`

### Example

```python
import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
elevation_lookup_result = client.elevation.lookup()
print(elevation_lookup_result.geometry)
```

#### 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(ElevationLookupPostParams**kwargs)  -> ElevationLookupResult`

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

Look up elevation at one or more points

### Parameters

- `lat: Optional[float]`

  Latitude (single point)

- `lng: Optional[float]`

  Longitude (single point)

- `locations: Optional[str]`

  Pipe-separated lng,lat pairs (batch)

- `output_fields: Optional[str]`

  Comma-separated property fields to include

- `output_include: Optional[str]`

  Extra computed fields: bbox, center

- `output_precision: Optional[int]`

  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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

      - `List[float]`

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

      - `List[List[float]]`

        Array of [lng, lat] positions

      - `List[List[List[float]]]`

        Array of linear rings / line strings

      - `List[List[List[List[float]]]]`

        Array of polygons

    - `type: Literal["Point", "LineString", "Polygon", 3 more]`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: Properties`

    - `elevation_m: float`

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

  - `type: Literal["Feature"]`

    - `"Feature"`

### Example

```python
import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
elevation_lookup_result = client.elevation.lookup_post()
print(elevation_lookup_result.geometry)
```

#### 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(ElevationBatchParams**kwargs)  -> ElevationBatchResult`

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

Look up elevation for multiple coordinates

### Parameters

- `coordinates: Iterable[Coordinate]`

  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: List[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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

        - `List[float]`

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

        - `List[List[float]]`

          Array of [lng, lat] positions

        - `List[List[List[float]]]`

          Array of linear rings / line strings

        - `List[List[List[List[float]]]]`

          Array of polygons

      - `type: Literal["Point", "LineString", "Polygon", 3 more]`

        Geometry type

        - `"Point"`

        - `"LineString"`

        - `"Polygon"`

        - `"MultiPoint"`

        - `"MultiLineString"`

        - `"MultiPolygon"`

    - `properties: Properties`

      - `elevation_m: float`

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

    - `type: Literal["Feature"]`

      - `"Feature"`

  - `type: Literal["FeatureCollection"]`

    - `"FeatureCollection"`

### Example

```python
import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
elevation_batch_result = client.elevation.batch(
    coordinates=[{
        "lat": 48.8566,
        "lng": 2.3522,
    }, {
        "lat": 45.764,
        "lng": 4.8357,
    }],
)
print(elevation_batch_result.features)
```

#### 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(ElevationProfileParams**kwargs)  -> ElevationProfileResult`

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

Elevation profile along coordinates

### Parameters

- `coordinates: Iterable[Coordinate]`

  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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

      - `List[float]`

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

      - `List[List[float]]`

        Array of [lng, lat] positions

      - `List[List[List[float]]]`

        Array of linear rings / line strings

      - `List[List[List[List[float]]]]`

        Array of polygons

    - `type: Literal["Point", "LineString", "Polygon", 3 more]`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: Properties`

    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: Literal["Feature"]`

    - `"Feature"`

### Example

```python
import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
elevation_profile_result = client.elevation.profile(
    coordinates=[{
        "lat": 48.8566,
        "lng": 2.3522,
    }, {
        "lat": 48.858,
        "lng": 2.34,
    }, {
        "lat": 48.8584,
        "lng": 2.2945,
    }],
)
print(elevation_profile_result.geometry)
```

#### 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: List[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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

        - `List[float]`

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

        - `List[List[float]]`

          Array of [lng, lat] positions

        - `List[List[List[float]]]`

          Array of linear rings / line strings

        - `List[List[List[List[float]]]]`

          Array of polygons

      - `type: Literal["Point", "LineString", "Polygon", 3 more]`

        Geometry type

        - `"Point"`

        - `"LineString"`

        - `"Polygon"`

        - `"MultiPoint"`

        - `"MultiLineString"`

        - `"MultiPolygon"`

    - `properties: Properties`

      - `elevation_m: float`

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

    - `type: Literal["Feature"]`

      - `"Feature"`

  - `type: Literal["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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

      - `List[float]`

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

      - `List[List[float]]`

        Array of [lng, lat] positions

      - `List[List[List[float]]]`

        Array of linear rings / line strings

      - `List[List[List[List[float]]]]`

        Array of polygons

    - `type: Literal["Point", "LineString", "Polygon", 3 more]`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: Properties`

    - `elevation_m: float`

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

  - `type: Literal["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: List[Coordinate]`

    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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

      - `List[float]`

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

      - `List[List[float]]`

        Array of [lng, lat] positions

      - `List[List[List[float]]]`

        Array of linear rings / line strings

      - `List[List[List[List[float]]]]`

        Array of polygons

    - `type: Literal["Point", "LineString", "Polygon", 3 more]`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: Properties`

    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: Literal["Feature"]`

    - `"Feature"`