openapi: 3.0.3
info:
  description: 'Confidently create beautiful maps for all your users with our tools. Choose your style from our library or build your own. With a rich palette of choices to fit any context and support for dozens of languages and scripts, you can deliver a quality experience for your customers no matter what part of the globe they call home. '
  version: 7.1.0
  title: Stadia Maps Geospatial API
  contact:
    name: Stadia Maps Support
    url: https://www.stadiamaps.com
    email: support@stadiamaps.com
servers:
- url: https://api.stadiamaps.com
- url: https://api-eu.stadiamaps.com
tags:
- name: Geospatial
paths:
  /elevation/v1:
    post:
      tags:
      - Geospatial
      operationId: elevation
      summary: Get the elevation profile along a polyline or at a point.
      description: The Stadia elevation API allows you to get the elevation of any point on earth. You can pass either a simple set of points or a Google encoded polyline string. This pairs well with our routing APIs, so you can generate an elevation profile for your next bike or run.
      security:
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/heightRequest'
      responses:
        '200':
          description: A list of elevations along the polyline, in meters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/heightResponse'
        '400':
          description: Bad request; more details will be included
components:
  schemas:
    coordinate:
      type: object
      properties:
        lat:
          type: number
          format: double
          description: The latitude of a point in the shape.
          example: 59.436884
          minimum: -90
          maximum: 90
        lon:
          type: number
          format: double
          description: The longitude of a point in the shape.
          example: 24.742595
          minimum: -180
          maximum: 180
      required:
      - lat
      - lon
    heightResponse:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/requestId'
        shape:
          type: array
          items:
            $ref: '#/components/schemas/coordinate'
        encoded_polyline:
          type: string
          description: The input polyline.
        height:
          type: array
          description: The list of heights for each point, in meters. Present only if `range` is `false`. Null values indicate missing data.
          items:
            type: number
            format: float
        range_height:
          type: array
          description: The list of ranges and heights for each point in the shape, where each entry is an array of length 2. Present only if `range` is `true`. In each pair, the first element represents the range or distance along the input locations. It is the cumulative distance along the previous coordinates in the shape up to the current coordinate. This value for the first coordinate in the shape will always be 0. The second element in the pair represents the height or elevation at the associated coordinate. The height is null if no height data exists for a given location. Both values are expressed in meters.
          items:
            type: array
            items:
              type: number
              format: float
            minItems: 2
            maxItems: 2
      example:
        id: kesklinn
        shape:
        - lat: 59.436884
          lon: 24.742595
        height:
        - 37
    requestId:
      type: string
      description: An identifier to disambiguate requests (echoed by the server).
      example: kesklinn
    heightRequest:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/requestId'
        shape:
          type: array
          items:
            $ref: '#/components/schemas/coordinate'
          description: REQUIRED if `encoded_polyline` is not present.
        encoded_polyline:
          type: string
          description: REQUIRED if `shape` is not present. An encoded polyline (https://developers.google.com/maps/documentation/utilities/polylinealgorithm).
        shape_format:
          type: string
          enum:
          - polyline6
          - polyline5
          default: polyline6
          description: Specifies whether the polyline is encoded with 6 digit precision (polyline6) or 5 digit precision (polyline5).
        range:
          type: boolean
          default: false
          description: Controls whether or not the returned array is one-dimensional (height only) or two-dimensional (with a range and height). The range dimension can be used to generate a graph or steepness gradient along a route.
        height_precision:
          type: integer
          default: 0
          minimum: 0
          maximum: 2
          description: The decimal precision (number of digits after the point) of the output. When 0, integer values are returned. Valid values are 0, 1, and 2.
        resample_distance:
          type: integer
          minimum: 10
          description: The distance at which the input polyline should be sampled to provide uniform distances between points. If not set, the input shape will be used as-is.
      example:
        id: kesklinn
        shape:
        - lat: 59.436884
          lon: 24.742595
        shape_format: polyline6
        range: false
        height_precision: 0
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key