Geoapify Isoline API

openapi: 3.2.0
info:
  title: Geoapify Isoline API
  version: 1.1.0
  description: Calculate reachable areas as travel-time isochrones or travel-distance isodistances, or retrieve a previously generated isoline by ID.
servers:
- url: https://api.geoapify.com/v1
  description: Default API endpoint.
- url: https://api-eu.geoapify.com/v1
  description: EU-focused endpoint. Geoapify service processing uses EU infrastructure.
security:
- ApiKeyInQuery: []
- ApiKeyInHeader: []
tags:
- name: Isoline
paths:
  /isoline:
    get:
      tags:
      - Isoline
      operationId: calculateIsoline
      summary: Calculate an isochrone or isodistance
      description: 'Calculates the area reachable from an origin within one or more travel-time or travel-distance limits.


        - To calculate an isoline, provide `lat`, `lon`, `type`, `mode`, and one or more `range` values.

        - With `type=time`, each range is travel time in seconds. With `type=distance`, ranges use meters for `units=metric` or miles for `units=imperial`.

        - Up to 10 ranges can be requested; the GeoJSON response contains one Polygon or MultiPolygon feature per range.

        - `transit` and `approximated_transit` support time-based isolines only.

        - Alternatively, provide only `id` to retrieve a previously generated isoline.

        - The default `format=geojson` response is a GeoJSON FeatureCollection. `topojson` and `geobuf` are available for clients that support those formats.


        **Example:** `lat=36.9743711&lon=-76.4166222&type=time&mode=drive&range=900`'
      parameters:
      - name: lat
        in: query
        required: false
        description: Origin latitude in decimal degrees. Required when calculating an isoline; omit when retrieving by `id`.
        schema:
          type: number
          minimum: -90
          maximum: 90
          example: 36.9743711
      - name: lon
        in: query
        required: false
        description: Origin longitude in decimal degrees. Required when calculating an isoline; omit when retrieving by `id`.
        schema:
          type: number
          minimum: -180
          maximum: 180
          example: -76.4166222
      - name: range
        in: query
        required: false
        description: One to 10 reachability limits. Required when calculating. Values are seconds for `type=time`; for `type=distance`, values are meters with metric units or miles with imperial units.
        schema:
          type: array
          minItems: 1
          maxItems: 10
          items:
            type: number
            minimum: 1
          example:
          - 900
        style: form
        explode: false
      - name: type
        in: query
        required: false
        description: Isoline kind. Use `time` for an isochrone or `distance` for an isodistance. Required when calculating.
        schema:
          type: string
          enum:
          - time
          - distance
          example: time
      - name: mode
        in: query
        required: false
        description: Travel mode used to calculate reachability. `drive` represents passenger-car routing. Required when calculating.
        schema:
          type: string
          enum:
          - walk
          - hike
          - scooter
          - motorcycle
          - drive
          - light_truck
          - bicycle
          - mountain_bike
          - road_bike
          - bus
          - medium_truck
          - truck
          - truck_dangerous_goods
          - heavy_truck
          - long_truck
          - transit
          - approximated_transit
          example: drive
      - name: units
        in: query
        required: false
        description: Unit system for distance ranges and `max_speed`. Metric uses meters and km/h; imperial uses miles and mph. Time ranges are always seconds.
        schema:
          type: string
          enum:
          - metric
          - imperial
          default: metric
      - name: avoid
        in: query
        required: false
        description: Routing features or areas to avoid. Examples include `tolls`, `highways`, `ferries`, `location:latitude,longitude`, `polygon:lat,lon;lat,lon;...`, and `country_codes:us,ca`.
        schema:
          type: array
          items:
            type: string
            pattern: ^(tolls|ferries|highways|green_zones|transfers|location|location_lonlat|location_latlon|polygon|polygon_lonlat|polygon_latlon|country_codes)(:.*)?$
        style: form
        explode: true
      - name: route_type
        in: query
        required: false
        description: 'Route optimization preference: balanced, shortest distance, or fewer maneuvers.'
        schema:
          type: string
          enum:
          - balanced
          - short
          - less_maneuvers
          default: balanced
      - name: traffic
        in: query
        required: false
        description: Traffic model. Use `approximated` to account for typical traffic where supported.
        schema:
          type: string
          enum:
          - free_flow
          - approximated
          default: free_flow
      - name: max_speed
        in: query
        required: false
        description: 'Optional maximum travel speed: 10–252 km/h with metric units or 6.5–155 mph with imperial units.'
        schema:
          type: number
          minimum: 6.5
          maximum: 252
      - name: details
        in: query
        required: false
        description: Optional detail datasets to add to every isoline feature, such as `population`.
        schema:
          type: array
          items:
            type: string
            minLength: 5
            maxLength: 100
        style: form
        explode: false
      - name: id
        in: query
        required: false
        description: ID returned for a previously generated isoline. Use `id` by itself instead of the calculation parameters.
        schema:
          type: string
          pattern: ^[a-f0-9]{32}$
      - name: format
        in: query
        required: false
        description: Response encoding. The documented success schema and example describe the default `geojson` format.
        schema:
          type: string
          enum:
          - geojson
          - topojson
          - geobuf
          default: geojson
      responses:
        '200':
          description: Calculated or retrieved isoline. The example represents a 900-second passenger-car isochrone; its coordinates are intentionally simplified to demonstrate the GeoJSON MultiPolygon structure. Actual responses contain more detailed geometry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IsolineFeatureCollection'
              example:
                type: FeatureCollection
                properties:
                  id: 768fc88900268ab0ec5aa67fbfa09cc2
                features:
                - type: Feature
                  properties:
                    lat: 36.9743711
                    lon: -76.4166222
                    mode: drive
                    type: time
                    range: 900
                    id: 768fc88900268ab0ec5aa67fbfa09cc2
                  geometry:
                    type: MultiPolygon
                    coordinates:
                    - - - - -76.44
                          - 36.97
                        - - -76.42
                          - 36.95
                        - - -76.39
                          - 36.97
                        - - -76.41
                          - 36.99
                        - - -76.44
                          - 36.97
                    - - - - -76.38
                          - 36.975
                        - - -76.37
                          - 36.97
                        - - -76.365
                          - 36.98
                        - - -76.375
                          - 36.985
                        - - -76.38
                          - 36.975
        '400':
          description: Invalid calculation parameters, an unsupported mode and range-type combination, or a range that exceeds the API limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              examples:
                missingLatitude:
                  summary: Missing calculation origin
                  value:
                    statusCode: 400
                    error: Bad Request
                    message: '"lat" is required'
                timeRangeTooLarge:
                  summary: Isochrone range exceeds the regular-request limit
                  value:
                    statusCode: 400
                    error: Bad Request
                    message: '"range" must be less than or equal to 3600 seconds'
                distanceRangeTooLarge:
                  summary: Isodistance range exceeds the regular-request limit
                  value:
                    statusCode: 400
                    error: Bad Request
                    message: '"range" must be less than or equal to 100000 meters'
                unsupportedTransitIsodistance:
                  summary: Distance isoline requested for transit
                  value:
                    statusCode: 400
                    error: Bad Request
                    message: type=distance is not supported for multimodal transit routing
        '401':
          description: Missing or invalid Geoapify API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                statusCode: 401
                error: Unauthorized
                message: Invalid apiKey
        '429':
          description: Rate limit or quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                statusCode: 429
                error: Too Many Requests
                message: Quota exceeded
        '500':
          description: Internal gateway error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                statusCode: 500
                error: Internal Server Error
                message: Request failed, please try again later
components:
  schemas:
    LocationData:
      type: object
      required:
      - lat
      - lon
      properties:
        lat:
          type: number
          minimum: -90
          maximum: 90
        lon:
          type: number
          minimum: -180
          maximum: 180
        address:
          type: string
    Avoid:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - tolls
          - ferries
          - highways
          - locations
          - polygons
          - green_zones
          - country_codes
          - transfers
        importance:
          type: number
          minimum: 0
          maximum: 1
        values:
          oneOf:
          - type: array
            items:
              type: string
          - type: array
            items:
              $ref: '#/components/schemas/LocationData'
          - type: array
            items:
              type: array
              items:
                $ref: '#/components/schemas/LocationData'
    IsolineDetails:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      properties:
        population:
          type: object
          required: []
          properties:
            attribution:
              type: string
            value:
              type: number
    IsolineFeature:
      type: object
      required:
      - type
      - geometry
      - properties
      properties:
        type:
          const: Feature
        geometry:
          $ref: '#/components/schemas/IsolineGeometry'
        properties:
          $ref: '#/components/schemas/IsolineFeatureProperties'
        id:
          oneOf:
          - type: string
          - type: number
        bbox:
          type: array
          minItems: 4
          maxItems: 6
          items:
            type: number
    JsonValue:
      oneOf:
      - type: string
      - type: number
      - type: boolean
      - type: 'null'
      - type: array
        items:
          $ref: '#/components/schemas/JsonValue'
      - $ref: '#/components/schemas/JsonObject'
    IsolineCollectionProperties:
      type: object
      required:
      - id
      properties:
        id:
          type: string
    JsonObject:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
    MultiPolygonGeometry:
      type: object
      required:
      - type
      - coordinates
      properties:
        type:
          const: MultiPolygon
        coordinates:
          type: array
          items:
            type: array
            items:
              type: array
              minItems: 4
              items:
                $ref: '#/components/schemas/LongitudeLatitude'
    IsolineGeometry:
      oneOf:
      - $ref: '#/components/schemas/PolygonGeometry'
      - $ref: '#/components/schemas/MultiPolygonGeometry'
    LongitudeLatitude:
      type: array
      minItems: 2
      maxItems: 2
      prefixItems:
      - type: number
        minimum: -180
        maximum: 180
      - type: number
        minimum: -90
        maximum: 90
      items: false
    PolygonGeometry:
      type: object
      required:
      - type
      - coordinates
      properties:
        type:
          const: Polygon
        coordinates:
          type: array
          items:
            type: array
            minItems: 4
            items:
              $ref: '#/components/schemas/LongitudeLatitude'
    IsolineFeatureProperties:
      type: object
      required:
      - id
      - lat
      - lon
      - mode
      - type
      - range
      properties:
        id:
          type: string
        lat:
          type: number
          minimum: -90
          maximum: 90
        lon:
          type: number
          minimum: -180
          maximum: 180
        mode:
          type: string
          enum:
          - walk
          - hike
          - scooter
          - motorcycle
          - drive
          - light_truck
          - bicycle
          - mountain_bike
          - road_bike
          - bus
          - medium_truck
          - truck
          - truck_dangerous_goods
          - heavy_truck
          - long_truck
          - transit
          - approximated_transit
        type:
          type: string
          enum:
          - time
          - distance
        range:
          type: number
        details:
          $ref: '#/components/schemas/IsolineDetails'
        route_type:
          type: string
          enum:
          - balanced
          - short
          - less_maneuvers
        max_speed:
          type: number
        units:
          type: string
          enum:
          - metric
          - imperial
        traffic:
          type: string
          enum:
          - free_flow
          - approximated
        avoid:
          type: array
          items:
            $ref: '#/components/schemas/Avoid'
    IsolineFeatureCollection:
      type: object
      required:
      - type
      - features
      - properties
      properties:
        type:
          const: FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/IsolineFeature'
        bbox:
          type: array
          minItems: 4
          maxItems: 6
          items:
            type: number
        properties:
          $ref: '#/components/schemas/IsolineCollectionProperties'
    GatewayError:
      type: object
      required:
      - statusCode
      - error
      - message
      properties:
        statusCode:
          type: integer
          description: HTTP status code returned by the API gateway.
        error:
          type: string
          description: Standard HTTP error name.
        message:
          type: string
          description: Human-readable explanation of the error.
  securitySchemes:
    ApiKeyInQuery:
      type: apiKey
      in: query
      name: apiKey
      description: Geoapify API key query parameter. Recommended authentication method for public APIs. API keys in URLs can be logged; use x-api-key for server-to-server clients.
    ApiKeyInHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Geoapify API key header. Supported as an alternative authentication method for public APIs.
x-provenance:
  method: harvested
  publisher: Geoapify
  source: https://apidocs.geoapify.com/assets/openapi/specs/isoline/isoline-api-openapi-specs.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)