> ## Documentation Index
> Fetch the complete documentation index at: https://docs.footstep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculate Isochrone

> Compute reachability polygons (isochrones) from an origin point. Pass `from` as a place name and the origin is geocoded for you, or pass `locations` if you already have coordinates. Returns one or more contour polygons capped by time or distance.


## OpenAPI

````yaml POST /v1/routing/isochrone
openapi: 3.1.0
info:
  title: Footstep API
  description: >-
    Terrain-intelligent routing, geocoding, elevation, and spatial analysis.
    Every routing response includes terrain analytics by default. Routing
    endpoints support two response formats: footstep (default, compact) and
    geojson (standard GeoJSON).
  version: 1.0.0
servers:
  - url: https://api.footstep.ai
    description: Production
security:
  - apiKey: []
paths:
  /v1/routing/isochrone:
    post:
      tags:
        - Routing
      summary: Calculate reachability polygons
      description: >-
        Compute reachability polygons (isochrones) from an origin point. Pass
        `from` as a place name and the origin is geocoded for you, or pass
        `locations` if you already have coordinates. Returns one or more contour
        polygons capped by time or distance.
      operationId: calculateIsochrone
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IsochroneRequest'
            examples:
              time_based:
                summary: 15-minute walking isochrone
                value:
                  locations:
                    - lat: 51.5322
                      lon: -0.124
                  travel: pedestrian
                  contours:
                    - time: 5
                      color: ff0000
                    - time: 10
                      color: ffff00
                    - time: 15
                      color: 00ff00
              distance_based:
                summary: 5km cycling range
                value:
                  locations:
                    - lat: 51.5322
                      lon: -0.124
                  travel: bicycle
                  contours:
                    - distance: 5
      responses:
        '200':
          description: Isochrone contours
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IsochroneResponse'
            application/geo+json:
              schema:
                type: object
                description: >-
                  GeoJSON FeatureCollection with polygon features for each
                  contour. Properties include contour value, metric, and color.
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Routing engine unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    IsochroneRequest:
      type: object
      required:
        - contours
      properties:
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Coordinate'
          minItems: 1
          maxItems: 1
          description: >-
            Single origin location as coordinates (length 1). Use this when you
            already have lat/lon; otherwise prefer `from`.
        travel:
          type: string
          enum:
            - auto
            - bicycle
            - pedestrian
            - bus
            - truck
          default: pedestrian
        travel_options:
          $ref: '#/components/schemas/TravelOptions'
        contours:
          type: array
          minItems: 1
          maxItems: 4
          items:
            type: object
            description: Provide time (minutes) or distance (km)
            properties:
              time:
                type: number
                minimum: 1
                maximum: 120
              distance:
                type: number
                minimum: 0.1
                maximum: 200
              color:
                type: string
        polygons:
          type: boolean
          default: true
        denoise:
          type: number
          minimum: 0
          maximum: 1
          default: 0.5
          description: 0 = detailed, 1 = smoothed
        show_locations:
          type: boolean
          default: false
        format:
          $ref: '#/components/schemas/Format'
        from:
          type: string
          description: >-
            Origin place name (e.g. 'Kings Cross, London'). Geocoded internally.
            Provide either `from` OR `locations`, not both.
    IsochroneResponse:
      type: object
      required:
        - origin
        - travel
        - contours
      description: Structured isochrone response with typed contours
      properties:
        origin:
          $ref: '#/components/schemas/Coordinate'
        travel:
          type: string
          description: Travel type used
        contours:
          type: array
          items:
            type: object
            required:
              - metric
              - value
              - geometry
            properties:
              metric:
                type: string
                enum:
                  - time
                  - distance
                description: Whether this contour is time or distance based
              value:
                type: number
                description: Contour value (minutes or km)
              geometry:
                type: object
                description: GeoJSON geometry of the contour
                properties:
                  type:
                    type: string
                    enum:
                      - Polygon
                      - LineString
                  coordinates:
                    description: Coordinate arrays
              reachable_places:
                type: array
                description: >-
                  Named anchors (venues, neighbourhoods, landmarks) within this
                  contour, ordered by relevance. Best-effort enrichment; may be
                  absent if no named anchors can be resolved.
                items:
                  type: object
                  required:
                    - name
                    - label
                    - place_type
                    - coordinates
                  properties:
                    name:
                      type: string
                    label:
                      type: string
                    place_type:
                      type: string
                    coordinates:
                      type: object
                      required:
                        - lat
                        - lng
                      properties:
                        lat:
                          type: number
                        lng:
                          type: number
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
    Coordinate:
      type: object
      required:
        - lat
        - lon
      properties:
        lat:
          type: number
          minimum: -90
          maximum: 90
        lon:
          type: number
          minimum: -180
          maximum: 180
    TravelOptions:
      type: object
      description: Fine-tuning options. Include only the key matching your travel type.
      properties:
        auto:
          type: object
          properties:
            use_highways:
              type: number
              minimum: 0
              maximum: 1
              description: 0 = avoid, 1 = prefer
            use_tolls:
              type: number
              minimum: 0
              maximum: 1
            use_ferry:
              type: number
              minimum: 0
              maximum: 1
            height:
              type: number
              description: Vehicle height in meters
            width:
              type: number
              description: Vehicle width in meters
            weight:
              type: number
              description: Vehicle weight in tonnes
        pedestrian:
          type: object
          properties:
            use_hills:
              type: number
              minimum: 0
              maximum: 1
              description: 0 = avoid hills, 1 = prefer hills
            walking_speed:
              type: number
              minimum: 0.5
              maximum: 25
              description: Speed in km/h
            max_hiking_difficulty:
              type: number
              minimum: 0
              maximum: 6
              description: SAC hiking scale (0-6)
            use_lit:
              type: number
              minimum: 0
              maximum: 1
              description: Prefer lit streets
            step_penalty:
              type: number
              description: Seconds penalty per stair transition
        bicycle:
          type: object
          properties:
            use_hills:
              type: number
              minimum: 0
              maximum: 1
              description: 0 = avoid hills, 1 = prefer hills
            cycling_speed:
              type: number
              minimum: 5
              maximum: 50
              description: Speed in km/h
            bicycle_type:
              type: string
              enum:
                - road
                - hybrid
                - cross
                - mountain
            use_roads:
              type: number
              minimum: 0
              maximum: 1
            avoid_bad_surfaces:
              type: number
              minimum: 0
              maximum: 1
        truck:
          type: object
          properties:
            use_highways:
              type: number
              minimum: 0
              maximum: 1
            use_tolls:
              type: number
              minimum: 0
              maximum: 1
            height:
              type: number
              description: Vehicle height in meters
            width:
              type: number
              description: Vehicle width in meters
            weight:
              type: number
              description: Vehicle weight in tonnes
            hazmat:
              type: boolean
            axle_load:
              type: number
              description: Axle load in tonnes
    Format:
      type: string
      enum:
        - footstep
        - geojson
      default: footstep
      description: >-
        Response format. footstep = optimised for app developers (encoded
        polyline, flat structure). geojson = standard GeoJSON FeatureCollection
        (decoded coordinates, immediately usable in Leaflet/Mapbox GL/deck.gl).
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Footstep API key

````