openapi: 3.0.3
info:
  title: Elevation service
  description: The elevation service is a location service which returns TopoBathy elevation values that combine topography (land elevation) and bathymetry (water depths).
  version: 0.1.7
  termsOfService: https://developers.arcgis.com/documentation/mapping-and-location-services/terms-of-use/
servers:
- url: https://elevation-api.arcgis.com/arcgis/rest/services/elevation-service/{apiVersion}
  description: Production service endpoint.
  variables:
    apiVersion:
      description: Beta version of the elevation service.
      default: beta
tags:
- name: Elevation values
  description: Endpoints which provide elevation values for either a single coordinate, or an array of coordinates.
security:
- ArcGISAuthorizationHeader: []
- ArcGISXEsriAuthorizationHeader: []
paths:
  /elevation/at-point:
    get:
      security:
      - ArcGISTokenParameter: []
      tags:
      - Elevation values
      parameters:
      - $ref: '#/components/parameters/LongitudeParam'
      - $ref: '#/components/parameters/LatitudeParam'
      - $ref: '#/components/parameters/RelativeToParam'
      - $ref: '#/components/parameters/TokenParam'
      - $ref: '#/components/parameters/FormatParam'
      responses:
        '200':
          $ref: '#/components/responses/ElevationResponse'
        '400':
          $ref: '#/components/responses/InvalidQueryErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ResourcePermissionErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
      operationId: ElevationAtPointGet
      x-arcgis-frontmatter:
        keywords:
        - elevation
      summary: Returns the elevation from a given input coordinate.
      description: |
        Returns the elevation in meters at a given longitude and latitude within the WGS84 coordinate system.

        By default the elevation is measured with respect to the Earth's mean sea level. It takes into account the local variations in gravity and provides a consistent vertical reference.

        If the `relativeTo` query parameter is set to `ellipsoid`, the elevation will be measured with respect to the ellipsoid. This is a mathematical model that approximates the shape of the Earth. It does not consider local variations in gravity and is commonly used in GPS positioning.

        Note: You cannot permanently store elevations. Please see the [Terms of use](https://developers.arcgis.com/documentation/mapping-apis-and-services/deployment/terms-of-use/).
  /elevation/at-many-points:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              description: |
                JSON structure which captures all the parameters for fetching elevations for multiple coordinates.
              type: object
              required:
              - coordinates
              properties:
                token:
                  description: |
                    The authentication token, used to access the elevation service.

                    The `token` parameter can be either an API Key or short-lived token.

                    Alternatively, you can supply a token in the request header with one of
                    the following keys using the "Bearer" scheme:

                    - `Authorization: Bearer <YOUR_TOKEN>`
                    - `X-Esri-Authorization: Bearer <YOUR_TOKEN>`

                    The provided `token` must be created from an ArcGIS Location Platform account and have the necessary `premium:user:elevation` privilege to use the elevation service.

                    **Developer guide**: To learn more, go to [Security and authentication](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/).
                  type: string
                  example: My token
                relativeTo:
                  type: string
                  enum:
                  - meanSeaLevel
                  - ellipsoid
                  example: meanSeaLevel
                  default: meanSeaLevel
                  description: |
                    The reference position (datum) from which to measure elevation.
                    The valid values are:
                    - meanSeaLevel: The elevation above or below the WGS84 geoid reference surface, which is approximately the mean sea level.
                                    It takes into account the local variations in gravity and provides a consistent vertical reference.
                    - ellipsoid: Ellipsoidal height is measured with respect to an ellipsoid, which is a mathematical model that approximates the shape of the Earth.
                                  It does not consider local variations in gravity and is commonly used in GPS positioning.
                f:
                  description: Optional, case-sensitive parameter to specify the format in which responses are given. Can either be `json` or `pjson`.
                  type: string
                  enum:
                  - json
                  - pjson
                  default: json
                coordinates:
                  type: array
                  description: Array of longitude and latitude pairs in the WGS84 spatial reference.
                  minItems: 1
                  maxItems: 100
                  items:
                    type: array
                    description: longitude and latitude pair in the WGS84 spatial reference.
                    minItems: 2
                    maxItems: 2
                    example:
                    - - 31.134167
                      - 29.979167
                    - - 31.130833
                      - 29.976111
                    - - 31.128333
                      - 29.9725
                    items:
                      oneOf:
                      - description: longitude
                        type: number
                        format: float
                        maximum: 179.99
                        minimum: -179.99
                      - description: latitude
                        type: number
                        format: float
                        maximum: 85.05
                        minimum: -85.05
      tags:
      - Elevation values
      responses:
        '200':
          $ref: '#/components/responses/MultipleElevationsResponse'
        '400':
          $ref: '#/components/responses/InvalidQueryErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ResourcePermissionErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
      operationId: ElevationAtManyPointsPost
      x-arcgis-frontmatter:
        keywords:
        - elevation
      summary: Returns elevations for up to 100 input coordinates.
      description: |
        Returns elevations in meters at given longitudes and latitudes within the WGS84 coordinate system.

        If the distance between the furthest West and furthest East coordinate exceeds 50km, the service will return a `400` HTTP response as the distance between these points is too large.

        If the distance between the furthest North and furthest South coordinate exceeds 50km, the service will return a `400` HTTP response as the distance between these points is too large.

        By default the elevation is measured with respect to the Earth's mean sea level. It takes into account the local variations in gravity and provides a consistent vertical reference.

        If the `relativeTo` parameter in the body is set to `ellipsoid`, the elevation will be measured with respect to the ellipsoid. This is a mathematical model that approximates the shape of the Earth. It does not consider local variations in gravity and is commonly used in GPS positioning.

        Note: You cannot permanently store elevations. Please see the [Terms of use](https://developers.arcgis.com/documentation/mapping-apis-and-services/deployment/terms-of-use/).

        The Post Body is a JSON structure which captures all of the following parameters for fetching elevations for multiple coordinates.

        **coordinates**
          - (Required) Array of (longitude, latitude) pairs in the WGS84 spatial reference. Maximum size of 100 coordinates.

        **f**
          - (Optional) Case-sensitive parameter to specify the format in which responses are given. Can either be `json` or `pjson`.

        **relativeTo**
          - (Optional) The reference position (datum) from which to measure elevation. The valid values are:

            - **meanSeaLevel**: The elevation above or below the WGS84 geoid reference surface, which is approximately the mean sea level. It takes into account the local variations in gravity and provides a consistent vertical reference.
            - **ellipsoid**: Ellipsoidal height is measured with respect to an ellipsoid, which is a mathematical model that approximates the shape of the Earth. It does not consider local variations in gravity and is commonly used in GPS positioning.

        **token**
          - (Optional) The authentication token, used to access the elevation service. Alternatively, you can supply a token in the request header with either the `Authorization` or `X-Esri-Authorization` key, using the "Bearer" scheme.

        Note: This Post body must be sent raw, i.e. not encoded. A future update will provide form-url-encoding support.
components:
  schemas:
    Point:
      description: A geometry point referring to a location on a map.
      type: object
      required:
      - x
      - y
      - z
      - spatialReference
      properties:
        spatialReference:
          description: The spatial reference system the point is relative to.
          type: object
          required:
          - wkid
          properties:
            wkid:
              description: The Well-Known ID (WKID) value of the spatial reference.
              type: number
              example: 4326
        x:
          description: The X coordinate which is measured along the east/west axis.
          type: number
          example: 86.925278
        y:
          description: The Y coordinate which is measured along the north/south axis.
          type: number
          example: 27.988333
        z:
          description: The Z coordinate represents the vertical position of a point above or below a reference level, such as sea level (in meters, rounded to the nearest meter).
          type: number
          example: 8744.0
    ElevationInfo:
      description: A structure containing human readable metadata about the specified point.
      required:
      - relativeTo
      properties:
        relativeTo:
          description: |
            The reference position (datum) from which to measure elevation.
            The valid values are:
            - meanSeaLevel: The elevation above or below the WGS84 geoid reference surface, which is approximately the mean sea level.
                            It takes into account the local variations in gravity and provides a consistent vertical reference.
            - ellipsoid: Ellipsoidal height is measured with respect to an ellipsoid, which is a mathematical model that approximates the shape of the Earth.
                          It does not consider local variations in gravity and is commonly used in GPS positioning.
          type: string
          enum:
          - meanSeaLevel
          - ellipsoid
          example: meanSeaLevel
          default: meanSeaLevel
    Elevation:
      description: A structure containing a point including an elevation value (defined as Z).
      required:
      - point
      properties:
        point:
          description: The point containing the elevation.
          $ref: '#/components/schemas/Point'
    Elevations:
      description: A structure containing a collection of points which contain elevation values (defined as Z).
      required:
      - points
      properties:
        points:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/Point'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          description: Error information
          type: object
          required:
          - code
          - message
          properties:
            code:
              description: A code identifying the type of error, either an HTTP error code, `498` (signifying invalid or expired token), or `499` (signifying missing token).
              type: integer
              example: 400
              enum:
              - 400
              - 401
              - 403
              - 404
              - 498
              - 499
              - 500
            message:
              description: A message describing the error.
              type: string
              minLength: 1
            details:
              description: List of details about the error.
              type: array
              items:
                type: string
            restInfoUrl:
              description: URL that provides the elevation service information.
              type: string
              example: https://elevation-api.arcgis.com/arcgis/rest/info
  responses:
    ElevationResponse:
      description: Response to a request for the elevation at a specified point.
      content:
        application/json:
          schema:
            additionalProperties: false
            type: object
            required:
            - result
            - elevationInfo
            properties:
              elevationInfo:
                $ref: '#/components/schemas/ElevationInfo'
              result:
                $ref: '#/components/schemas/Elevation'
          examples:
            esriRelativeToMeanSeaLevel:
              $ref: '#/components/examples/esriRelativeToMeanSeaLevelAtPoint'
            mountEverestRelativeToMeanSeaLevel:
              $ref: '#/components/examples/mountEverestRelativeToMeanSeaLevelAtPoint'
            cardiffCastleRelativeToEllipsoid:
              $ref: '#/components/examples/cardiffCastleRelativeToEllipsoidAtPoint'
            bozemanMontantaRelativeToEllipsoid:
              $ref: '#/components/examples/bozemanMontanaRelativeToEllipsoidAtPoint'
    MultipleElevationsResponse:
      description: Response to a request for the elevations at specified points.
      content:
        application/json:
          schema:
            additionalProperties: false
            type: object
            required:
            - result
            - elevationInfo
            properties:
              elevationInfo:
                $ref: '#/components/schemas/ElevationInfo'
              result:
                $ref: '#/components/schemas/Elevations'
          examples:
            pyramidsOfGizaRelativeToMeanSeaLevel:
              $ref: '#/components/examples/pyramidsOfGizaRelativeToMeanSeaLevelAtManyPoints'
            greatWallOfChinaRelativeToEllipsoid:
              $ref: '#/components/examples/greatWallOfChinaRelativeToEllipsoidAtManyPoints'
    UnauthorizedErrorResponse:
      description: Authentication Error. The API key or token is missing, invalid or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerErrorResponse:
      description: An error occurred on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidQueryErrorResponse:
      description: Invalid query parameters / Incorrect portal item type.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PermissionMissingErrorResponse:
      description: |
        The supplied authentication information is valid but does not have permission to access the service.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ResourcePermissionErrorResponse:
      description: The requested resource cannot be accessed because of incorrect sharing permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    FormatParam:
      name: f
      in: query
      required: false
      description: Optional, case-sensitive parameter to specify the format in which responses are given. Can either be `json` or `pjson`.
      schema:
        type: string
        enum:
        - json
        - pjson
        default: json
    TokenParam:
      name: token
      in: query
      required: false
      description: |
        The authentication token, used to access the elevation service.

        The `token` parameter can be either an API Key or short-lived token.

        Alternatively, you can supply a token in the request header with one of
        the following keys using the "Bearer" scheme:

        - `Authorization: Bearer <YOUR_TOKEN>`
        - `X-Esri-Authorization: Bearer <YOUR_TOKEN>`

        The provided `token` must be created from an ArcGIS Location Platform account and have the necessary `premium:user:elevation` privilege to use the elevation service.

        **Developer guide**: To learn more, go to [Security and authentication](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/).
      schema:
        type: string
    LongitudeParam:
      name: lon
      in: query
      schema:
        type: number
        minimum: -179.99
        maximum: 179.99
      required: true
      description: The longitude of the specified point.
    LatitudeParam:
      name: lat
      in: query
      schema:
        type: number
        minimum: -85.05
        maximum: 85.05
      required: true
      description: The latitude of the specified point.
    RelativeToParam:
      name: relativeTo
      in: query
      schema:
        type: string
        enum:
        - meanSeaLevel
        - ellipsoid
        example: ellipsoid
        default: meanSeaLevel
      required: false
      description: |
        The reference position (datum) from which to measure elevation.
        The valid values are:
        - meanSeaLevel: The elevation above or below the WGS84 geoid reference surface, which is approximately the mean sea level.
                        It takes into account the local variations in gravity and provides a consistent vertical reference.
        - ellipsoid: Ellipsoidal height is measured with respect to an ellipsoid, which is a mathematical model that approximates the shape of the Earth.
                      It does not consider local variations in gravity and is commonly used in GPS positioning.
  examples:
    esriRelativeToMeanSeaLevelAtPoint:
      summary: Esri Campus relative to mean sea level
      value:
        elevationInfo:
          relativeTo: meanSeaLevel
        result:
          point:
            spatialReference:
              wkid: 4326
            x: -117.194769
            y: 34.057289
            z: 396.0
    mountEverestRelativeToMeanSeaLevelAtPoint:
      summary: Mount Everest relative to mean sea level
      value:
        elevationInfo:
          relativeTo: meanSeaLevel
        result:
          point:
            spatialReference:
              wkid: 4326
            x: 86.925278
            y: 27.988333
            z: 8744.0
    cardiffCastleRelativeToEllipsoidAtPoint:
      summary: Cardiff Castle relative to ellipsoid
      value:
        elevationInfo:
          relativeTo: ellipsoid
        result:
          point:
            spatialReference:
              wkid: 4326
            x: -3.1837516
            y: 51.4822346
            z: 59.0
    bozemanMontanaRelativeToEllipsoidAtPoint:
      summary: Bozeman Montanna relative to ellipsoid
      value:
        elevationInfo:
          relativeTo: ellipsoid
        result:
          point:
            spatialReference:
              wkid: 4326
            x: -111.093244
            y: 45.6830173
            z: 1452.0
    pyramidsOfGizaRelativeToMeanSeaLevelAtManyPoints:
      summary: Pyramids of Giza relative to mean sea level
      value:
        elevationInfo:
          relativeTo: meanSeaLevel
        result:
          points:
          - spatialReference:
              wkid: 4326
            x: 31.134167
            y: 29.979167
            z: 82.0
          - spatialReference:
              wkid: 4326
            x: 31.130833
            y: 29.976111
            z: 90.0
          - spatialReference:
              wkid: 4326
            x: 31.128333
            y: 29.9725
            z: 74.0
    greatWallOfChinaRelativeToEllipsoidAtManyPoints:
      summary: Great Wall of China relative to ellipsoid
      value:
        elevationInfo:
          relativeTo: ellipsoid
        result:
          points:
          - spatialReference:
              wkid: 4326
            x: 116.5655434
            y: 40.4334671
            z: 483.0
          - spatialReference:
              wkid: 4326
            x: 116.5642703
            y: 40.4331226
            z: 502.0
          - spatialReference:
              wkid: 4326
            x: 116.5646503
            y: 40.4378045
            z: 452.0
          - spatialReference:
              wkid: 4326
            x: 116.5650703
            y: 40.4404094
            z: 482.0
          - spatialReference:
              wkid: 4326
            x: 116.5642957
            y: 40.4408222
            z: 495.0
          - spatialReference:
              wkid: 4326
            x: 116.5697131
            y: 40.4324535
            z: 437.0
  securitySchemes:
    ArcGISTokenParameter:
      type: apiKey
      in: query
      name: token
      description: |
        The authentication token, created from an ArcGIS Location Platform account, with the `premium:user:elevation` [privilege](https://developers.arcgis.com/rest/users-groups-and-items/privileges.htm), used to access the elevation service.

        The case-sensitive `token` parameter can be either an API Key or short-lived token. See
        [ArcGIS security
        documentation](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/)
        for more information on authenticating with a token or API key.
    ArcGISAuthorizationHeader:
      type: apiKey
      in: header
      name: Authorization
      description: |
        The authentication token, created from an ArcGIS Location Platform account, with the `premium:user:elevation` [privilege](https://developers.arcgis.com/rest/users-groups-and-items/privileges.htm), used to access the elevation service.

        The authorization parameter can be either an API Key or short-lived token. See
        [ArcGIS security
        documentation](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/)
        for more information on authenticating with a token or API key.

        Supply the token in the request header using the "Bearer" scheme:
        `Authorization: Bearer <YOUR_TOKEN>`
    ArcGISXEsriAuthorizationHeader:
      type: apiKey
      in: header
      name: X-Esri-Authorization
      description: |
        The authentication token, created from an ArcGIS Location Platform account, with the `premium:user:elevation` [privilege](https://developers.arcgis.com/rest/users-groups-and-items/privileges.htm), used to access the elevation service.

        The authorization parameter can be either an API Key or short-lived token. See
        [ArcGIS security
        documentation](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/)
        for more information on authenticating with a token or API key.

        Supply the token in the request header using the "Bearer" scheme:
        `X-Esri-Authorization: Bearer <YOUR_TOKEN>`