> ## 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.

# Compare Routes

> Calculate routes between the same locations using multiple travel modes and return a side-by-side comparison. Includes distance, duration, and terrain difficulty for each mode, plus a summary showing which is fastest, shortest, and easiest. Useful for deciding how to travel.



## OpenAPI

````yaml POST /v1/routing/compare
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/compare:
    post:
      tags:
        - Routing
      summary: Compare travel modes between two locations
      description: >-
        Calculate routes between the same locations using multiple travel modes
        and return a side-by-side comparison. Includes distance, duration, and
        terrain difficulty for each mode, plus a summary showing which is
        fastest, shortest, and easiest. Useful for deciding how to travel.
      operationId: compareRoutes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompareRoutesRequest'
            examples:
              walk_vs_cycle:
                summary: Walking vs cycling
                value:
                  locations:
                    - lat: 51.5322
                      lon: -0.124
                    - lat: 51.5055
                      lon: -0.0754
                  travel_modes:
                    - pedestrian
                    - bicycle
              three_modes:
                summary: Walk vs cycle vs drive
                value:
                  locations:
                    - lat: 51.5322
                      lon: -0.124
                    - lat: 51.5055
                      lon: -0.0754
                  travel_modes:
                    - pedestrian
                    - bicycle
                    - auto
      responses:
        '200':
          description: Routes for each travel mode with comparison
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompareRoutesResponse'
        '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:
    CompareRoutesRequest:
      type: object
      required:
        - locations
        - travel_modes
      properties:
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Coordinate'
          minItems: 2
          maxItems: 20
          description: Waypoints (min 2, max 20)
        travel_modes:
          type: array
          items:
            type: string
            enum:
              - auto
              - bicycle
              - pedestrian
              - bus
              - truck
          minItems: 2
          maxItems: 4
          description: Travel modes to compare (2-4)
        travel_options:
          $ref: '#/components/schemas/TravelOptions'
        elevation_interval:
          type: number
          minimum: 10
          maximum: 200
          default: 30
          description: Elevation sampling interval in meters
        format:
          $ref: '#/components/schemas/Format'
    CompareRoutesResponse:
      type: object
      required:
        - routes
        - comparison
      properties:
        routes:
          type: object
          description: >-
            Routes keyed by travel mode (e.g. { "pedestrian": Route, "bicycle":
            Route })
          additionalProperties:
            $ref: '#/components/schemas/Route'
        comparison:
          type: object
          required:
            - fastest
            - shortest
            - easiest
            - summary
          properties:
            fastest:
              type: string
              description: Travel mode with the shortest duration
            shortest:
              type: string
              description: Travel mode with the shortest distance
            easiest:
              type: string
              description: Travel mode with the lowest terrain difficulty
            summary:
              type: string
              description: Natural language comparison of the routes
    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).
    Route:
      type: object
      required:
        - waypoints
        - legs
        - distance_meters
        - duration_seconds
        - flags
        - bounds
        - terrain
        - units
      description: A complete route with terrain analytics
      properties:
        waypoints:
          type: array
          items:
            $ref: '#/components/schemas/Waypoint'
        legs:
          type: array
          items:
            $ref: '#/components/schemas/Leg'
        distance_meters:
          type: number
          description: Total route distance in meters
        duration_seconds:
          type: number
          description: Total route duration in seconds
        flags:
          $ref: '#/components/schemas/RouteFlags'
        bounds:
          $ref: '#/components/schemas/BoundingBox'
        terrain:
          $ref: '#/components/schemas/TerrainSummary'
        units:
          type: string
          description: >-
            Echo of request units (informational only, response values are
            always in meters/seconds)
        narrative:
          type: string
          description: >-
            Natural language summary of the route including distance, duration,
            terrain, and key landmarks. Present when narrative=true in the
            request.
    Waypoint:
      type: object
      required:
        - lat
        - lon
      properties:
        lat:
          type: number
        lon:
          type: number
        original_index:
          type: number
          description: Original input index (present in optimise responses)
    Leg:
      type: object
      required:
        - distance_meters
        - duration_seconds
        - shape
        - steps
        - terrain
        - flags
        - bounds
      description: A route leg between two waypoints
      properties:
        distance_meters:
          type: number
          description: Leg distance in meters
        duration_seconds:
          type: number
          description: Leg duration in seconds
        shape:
          type: string
          description: Encoded polyline6 geometry
        steps:
          type: array
          items:
            $ref: '#/components/schemas/Step'
          description: Turn-by-turn navigation steps
        terrain:
          $ref: '#/components/schemas/TerrainSummary'
        flags:
          $ref: '#/components/schemas/RouteFlags'
        bounds:
          $ref: '#/components/schemas/BoundingBox'
    RouteFlags:
      type: object
      required:
        - has_toll
        - has_highway
        - has_ferry
      properties:
        has_toll:
          type: boolean
        has_highway:
          type: boolean
        has_ferry:
          type: boolean
    BoundingBox:
      type: object
      required:
        - min_lat
        - min_lon
        - max_lat
        - max_lon
      properties:
        min_lat:
          type: number
        min_lon:
          type: number
        max_lat:
          type: number
        max_lon:
          type: number
      description: Bounding box for map.fitBounds()
    TerrainSummary:
      type: object
      description: >-
        Terrain analytics computed from elevation data. Included automatically
        in routing responses.
      required:
        - total_ascent_meters
        - total_descent_meters
        - max_elevation_meters
        - min_elevation_meters
        - avg_grade_percent
        - max_grade_percent
        - elevation_profile
        - difficulty
      properties:
        total_ascent_meters:
          type: number
          description: Total uphill gain in meters
        total_descent_meters:
          type: number
          description: Total downhill loss in meters
        max_elevation_meters:
          type: number
          description: Highest point
        min_elevation_meters:
          type: number
          description: Lowest point
        avg_grade_percent:
          type: number
          description: Average absolute grade %
        max_grade_percent:
          type: number
          description: Maximum absolute grade %
        elevation_profile:
          type: array
          description: Sampled elevation profile for charting
          items:
            type: object
            required:
              - distance_meters
              - elevation_meters
            properties:
              distance_meters:
                type: number
              elevation_meters:
                type: number
        difficulty:
          type: string
          enum:
            - flat
            - rolling
            - hilly
            - mountainous
          description: Terrain difficulty classification based on grade distribution
    Step:
      type: object
      required:
        - type
        - instruction
        - street_names
        - distance_meters
        - duration_seconds
        - begin_shape_index
        - end_shape_index
        - travel_mode
        - flags
      description: A turn-by-turn navigation step
      properties:
        type:
          $ref: '#/components/schemas/StepType'
        instruction:
          type: string
          description: Human-readable navigation instruction
        verbal_alert:
          type: string
          description: Spoken alert before the step
        verbal_instruction:
          type: string
          description: Spoken instruction at the step
        street_names:
          type: array
          items:
            type: string
          description: Street name(s) for this step
        distance_meters:
          type: number
          description: Step distance in meters
        duration_seconds:
          type: number
          description: Step duration in seconds
        begin_shape_index:
          type: number
          description: Index into the leg shape where this step starts
        end_shape_index:
          type: number
          description: Index into the leg shape where this step ends
        travel_mode:
          type: string
          description: 'Mode of travel: drive, pedestrian, bicycle, transit'
        bearing_before:
          type: number
          description: Bearing in degrees approaching the step (0-360)
        bearing_after:
          type: number
          description: Bearing in degrees leaving the step (0-360)
        flags:
          $ref: '#/components/schemas/StepFlags'
        roundabout_exit_count:
          type: number
          description: Which exit to take in a roundabout
        exit_sign:
          $ref: '#/components/schemas/ExitSign'
        lanes:
          type: array
          items:
            $ref: '#/components/schemas/Lane'
          description: Lane guidance at the step
    StepType:
      type: string
      enum:
        - none
        - start
        - start_right
        - start_left
        - destination
        - destination_right
        - destination_left
        - becomes
        - continue
        - slight_right
        - right
        - sharp_right
        - u_turn_right
        - u_turn_left
        - sharp_left
        - left
        - slight_left
        - ramp_straight
        - ramp_right
        - ramp_left
        - exit_right
        - exit_left
        - stay_straight
        - stay_right
        - stay_left
        - merge
        - merge_right
        - merge_left
        - roundabout_enter
        - roundabout_exit
        - ferry_enter
        - ferry_exit
        - unknown
      description: >-
        Turn-by-turn manoeuvre type. Grouped by category in the docs (direction
        / continuation / start-end / highway / roundabout / ferry / fallback).
    StepFlags:
      type: object
      required:
        - toll
        - ferry
        - rough
        - gate
        - highway
      properties:
        toll:
          type: boolean
        ferry:
          type: boolean
        rough:
          type: boolean
        gate:
          type: boolean
        highway:
          type: boolean
    ExitSign:
      type: object
      properties:
        exit_number:
          type: string
        exit_branch:
          type: string
        exit_toward:
          type: string
        exit_name:
          type: string
      description: Highway exit sign information
    Lane:
      type: object
      required:
        - indications
        - valid
      properties:
        indications:
          type: array
          items:
            type: string
        valid:
          type: boolean
        active:
          type: boolean
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Footstep API key

````