openapi: 3.0.0
info:
  title: Elevation API
  description: The Elevation API returns elevation data for given locations. Provide coordinates and get elevation values in meters or feet. This API is ideal for terrain analysis, route planning with elevation profiles, outdoor activity planning, and environmental studies.
  version: 1.0.0
  contact:
    name: Geoapify
    url: https://geoapify.com
    email: info@geoapify.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.geoapify.com/v1
    description: Primary Geoapify API endpoint

tags:
  - name: Elevation API
    description: API for retrieving elevation data for specified coordinates.

paths:
  /geodata/elevation:
    post:
      tags:
        - Elevation API
      summary: Get Elevation Data
      description: |
        Returns elevation data for a set of coordinates. The API accepts multiple location formats and returns elevation values in the specified units (meters or feet).
      operationId: getElevation
      parameters:
        - name: apiKey
          in: query
          required: true
          description: Your Geoapify API key to authenticate the request. You can sign up and obtain an API key for free at [https://myprojects.geoapify.com/](https://myprojects.geoapify.com/). The Free plan includes up to 3,000 credits per day.
          schema:
            type: string
            example: "YOUR_API_KEY"
        - name: billing_details
          in: query
          required: false
          description: Set to `credits` to include request billing information in the response as `billing.credits`.
          schema:
            type: string
            enum: [credits]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ElevationRequest'
            example:
              format: json
              units: metric
              includeDistance: true
              locations:
                - latlon: [52.52, 13.405]
                - lat: 48.137
                  lon: 11.575
                - [-122.4194, 37.7749]
      responses:
        '200':
          description: Successful response containing elevation data for the requested locations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElevationJsonResponse'
              example:
                billing:
                  credits: 1
                results:
                  - location:
                      lon: 52.52
                      lat: 13.405
                    elevation: -2189
                    units: m
                    distance: 0
                    distance_units: m
                  - location:
                      lon: 11.575
                      lat: 48.137
                    elevation: 523
                    units: m
                    distance: 5395784
                    distance_units: m
                  - location:
                      lon: -122.4194
                      lat: 37.7749
                    elevation: 17
                    units: m
                    distance: 14840969
                    distance_units: m
            application/geo+json:
              schema:
                $ref: '#/components/schemas/ElevationGeoJsonResponse'
              example:
                type: FeatureCollection
                features:
                  - type: Feature
                    geometry:
                      type: Point
                      coordinates: [13.405, 52.52]
                    properties:
                      elevation: 49
                      units: m
        '400':
          description: Bad Request. The input provided is invalid or improperly formatted. Please verify and correct your request parameters.
        '401':
          description: Unauthorized. The API key is missing, incorrect, or invalid. Please provide a valid API key to authenticate the request.
        '429':
          description: Request limit exceeded. Too many requests have been sent in a short period, surpassing the allowed rate limits.
        '500':
          description: Internal Server Error. The server encountered an unexpected condition that prevented it from fulfilling the request. Please try again later or [contact support](mailto:info@geoapify.com) if the issue persists.

components:
  schemas:
    ElevationRequest:
      type: object
      required:
        - locations
      properties:
        locations:
          type: array
          minItems: 1
          maxItems: 1000
          description: Array of location coordinates. Max 1000 locations per request.
          items:
            oneOf:
              - $ref: '#/components/schemas/LocationArray'
              - $ref: '#/components/schemas/LocationObject'
              - $ref: '#/components/schemas/LocationLatLon'
              - $ref: '#/components/schemas/LocationLonLat'
        format:
          type: string
          enum: [json, geojson]
          default: json
          description: Response format. Use `json` for a simple results array or `geojson` for a GeoJSON FeatureCollection.
        units:
          $ref: '../common/shared-components.yaml#/components/schemas/UnitsEnum'
        includeDistance:
          type: boolean
          default: false
          description: When true, includes the distance from the previous point in the response. Useful for creating elevation profiles along a route.
    
    LocationArray:
      type: array
      items:
        type: number
      minItems: 2
      maxItems: 2
      description: Location as [longitude, latitude] array
      example: [-122.4194, 37.7749]
    
    LocationObject:
      type: object
      required:
        - lat
        - lon
      properties:
        lat:
          type: number
          minimum: -90
          maximum: 90
          description: Latitude of the location
        lon:
          type: number
          minimum: -180
          maximum: 180
          description: Longitude of the location
      example:
        lat: 48.137
        lon: 11.575
    
    LocationLatLon:
      type: object
      required:
        - latlon
      properties:
        latlon:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
          description: Coordinates as [latitude, longitude]
      example:
        latlon: [52.52, 13.405]
    
    LocationLonLat:
      type: object
      required:
        - lonlat
      properties:
        lonlat:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
          description: Coordinates as [longitude, latitude]
      example:
        lonlat: [13.405, 52.52]
    
    ElevationJsonResponse:
      type: object
      properties:
        billing:
          $ref: '#/components/schemas/BillingDetails'
        results:
          type: array
          description: Array of elevation results for each requested location
          items:
            $ref: '#/components/schemas/ElevationResult'

    BillingDetails:
      type: object
      properties:
        credits:
          type: number
          description: Credits charged for this request.
    
    ElevationResult:
      type: object
      properties:
        location:
          type: object
          description: Location coordinates
          properties:
            lon:
              type: number
              description: Longitude of the location
            lat:
              type: number
              description: Latitude of the location
        elevation:
          type: number
          description: Elevation value in the requested units
        units:
          type: string
          enum: [m, ft]
          description: Elevation unit of measurement (m for meters, ft for feet)
        distance:
          type: number
          description: Distance from the previous point (included when includeDistance is true)
        distance_units:
          type: string
          enum: [m, ft]
          description: Distance unit of measurement (m for meters, ft for feet)
    
    ElevationGeoJsonResponse:
      allOf:
        - $ref: '../common/shared-components.yaml#/components/schemas/GeoJsonFeatureCollection'
        - type: object
          properties:
            billing:
              $ref: '#/components/schemas/BillingDetails'
            features:
              type: array
              items:
                $ref: '#/components/schemas/ElevationFeature'
    
    ElevationFeature:
      allOf:
        - $ref: '../common/shared-components.yaml#/components/schemas/GeoJsonFeature'
        - type: object
          properties:
            geometry:
              $ref: '../common/shared-components.yaml#/components/schemas/PointGeometry'
            properties:
              $ref: '#/components/schemas/ElevationFeatureProperties'
    
    ElevationFeatureProperties:
      type: object
      properties:
        elevation:
          type: number
          description: Elevation value in the requested units
        units:
          type: string
          enum: [m, ft]
          description: Elevation unit of measurement (m for meters, ft for feet)
        distance:
          type: number
          description: Distance from the previous point (included when includeDistance is true)
        distance_units:
          type: string
          enum: [m, ft]
          description: Distance unit of measurement (m for meters, ft for feet)
