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

# Search Along Route

> Calculate a route between locations and search for places along the corridor. Results are ranked by how little detour they add. Useful for finding stops (petrol stations, restaurants, charging points) on the way to a destination.



## OpenAPI

````yaml POST /v1/routing/search-along-route
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/search-along-route:
    post:
      tags:
        - Routing
      summary: Find places along a route
      description: >-
        Calculate a route between locations and search for places along the
        corridor. Results are ranked by how little detour they add. Useful for
        finding stops (petrol stations, restaurants, charging points) on the way
        to a destination.
      operationId: searchAlongRoute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchAlongRouteRequest'
            examples:
              coffee_on_way:
                summary: Coffee shops on route
                value:
                  locations:
                    - lat: 51.5322
                      lon: -0.124
                    - lat: 51.5055
                      lon: -0.0754
                  search: coffee shop
                  max_detour_seconds: 300
              petrol_stations:
                summary: Petrol stations on a drive
                value:
                  locations:
                    - lat: 51.5074
                      lon: -0.1278
                    - lat: 52.2053
                      lon: 0.1218
                  search: petrol station
                  travel: auto
                  max_detour_seconds: 600
                  size: 5
      responses:
        '200':
          description: Route with places found along the corridor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchAlongRouteResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Routing or geocoding engine unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SearchAlongRouteRequest:
      type: object
      required:
        - locations
        - search
      properties:
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Coordinate'
          minItems: 2
          maxItems: 20
          description: Route waypoints (min 2, max 20)
        search:
          type: string
          description: >-
            What to search for along the route (e.g. 'coffee shop', 'petrol
            station', 'supermarket')
        travel:
          type: string
          enum:
            - auto
            - bicycle
            - pedestrian
            - bus
            - truck
          default: auto
        travel_options:
          $ref: '#/components/schemas/TravelOptions'
        max_detour_seconds:
          type: number
          minimum: 60
          maximum: 3600
          default: 300
          description: Maximum acceptable detour in seconds (1 min to 1 hour)
        size:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
          description: Maximum number of places to return
        format:
          $ref: '#/components/schemas/Format'
    SearchAlongRouteResponse:
      type: object
      required:
        - route
        - places
      properties:
        route:
          $ref: '#/components/schemas/Route'
          description: The original route between the locations
        places:
          type: array
          description: Places found along the route, ranked by detour time
          items:
            type: object
            required:
              - place
              - detour_seconds
              - detour_meters
              - position_along_route_percent
            properties:
              place:
                $ref: '#/components/schemas/PlaceResult'
              detour_seconds:
                type: number
                description: How many seconds of detour this stop adds
              detour_meters:
                type: number
                description: How many meters of detour this stop adds
              position_along_route_percent:
                type: number
                minimum: 0
                maximum: 100
                description: Where along the route this place is (0 = start, 100 = end)
    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.
    PlaceResult:
      type: object
      required:
        - coordinates
        - label
        - name
        - distance_meters
        - confidence
        - place_type
      properties:
        coordinates:
          $ref: '#/components/schemas/GeocodingCoordinate'
        label:
          type: string
          description: Full human-readable label
        name:
          type: string
          description: Short name of the place
        country:
          type: string
        country_code:
          type: string
          description: ISO 3166-1 alpha-3
        region:
          type: string
        locality:
          type: string
          description: City or town
        distance_meters:
          type: number
          description: Distance from the search point in meters
        confidence:
          type: number
          minimum: 0
          maximum: 1
        place_type:
          type: string
    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
    GeocodingCoordinate:
      type: object
      required:
        - lat
        - lng
      properties:
        lat:
          type: number
          minimum: -90
          maximum: 90
        lng:
          type: number
          minimum: -180
          maximum: 180
    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

````