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

# Find and Route

> Find a place by name or address, then calculate a route to it from your origin. Combines geocoding and routing in a single call. Returns the matched destination, the full route with terrain analytics, and alternative geocoding matches.



## OpenAPI

````yaml POST /v1/routing/find-and-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/find-and-route:
    post:
      tags:
        - Routing
      summary: Geocode a destination and route to it
      description: >-
        Find a place by name or address, then calculate a route to it from your
        origin. Combines geocoding and routing in a single call. Returns the
        matched destination, the full route with terrain analytics, and
        alternative geocoding matches.
      operationId: findAndRoute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindAndRouteRequest'
            examples:
              place_name:
                summary: Route to a landmark
                value:
                  origin:
                    lat: 51.5322
                    lon: -0.124
                  destination: Tower Bridge, London
                  travel: pedestrian
              with_country:
                summary: With country hint
                value:
                  origin:
                    lat: 51.5322
                    lon: -0.124
                  destination: 10 Downing Street
                  destination_country: GBR
                  travel: auto
      responses:
        '200':
          description: Geocoded destination with route
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindAndRouteResponse'
        '400':
          description: Invalid request or destination not found
          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:
    FindAndRouteRequest:
      type: object
      required:
        - origin
        - destination
      properties:
        origin:
          oneOf:
            - $ref: '#/components/schemas/Coordinate'
            - type: string
              minLength: 1
          description: >-
            Starting location. Either lat/lon coordinates, or a place name /
            postcode / address (geocoded internally).
        destination:
          type: string
          description: Place name, address, or landmark to find and route to
        destination_country:
          type: string
          description: ISO 3166-1 alpha-3 country code hint for geocoding (e.g. GBR, USA)
        travel:
          type: string
          enum:
            - auto
            - bicycle
            - pedestrian
            - bus
            - truck
          default: auto
        travel_options:
          $ref: '#/components/schemas/TravelOptions'
        elevation_interval:
          type: number
          minimum: 10
          maximum: 200
          default: 30
        narrative:
          type: boolean
          default: false
          description: Include a natural language route summary. Adds ~500ms.
        format:
          $ref: '#/components/schemas/Format'
        origin_country:
          type: string
          description: ISO 3166-1 alpha-3 country hint applied when origin is a string.
    FindAndRouteResponse:
      type: object
      required:
        - origin
        - destination
        - route
      properties:
        destination:
          $ref: '#/components/schemas/GeocodingResult'
          description: The geocoded destination that was routed to
        route:
          $ref: '#/components/schemas/Route'
          description: Route from origin to the geocoded destination
        alternatives:
          type: array
          items:
            $ref: '#/components/schemas/GeocodingResult'
          description: >-
            Other geocoding matches (up to 3) in case the primary result wasn't
            what you meant. Filtered to the same country as the primary match
            with a minimum confidence threshold; absent when nothing useful
            survives the filter.
        narrative:
          type: string
          description: >-
            AI-generated 1-3 sentence summary of the route. Present only when
            `narrative: true` was requested and the LLM service was available.
        origin:
          $ref: '#/components/schemas/Origin'
          description: >-
            Echoed origin — coordinates always present; geocoded label/name
            fields present only when the caller passed a string.
    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).
    GeocodingResult:
      type: object
      required:
        - coordinates
        - label
        - name
        - confidence
        - place_type
      properties:
        coordinates:
          $ref: '#/components/schemas/GeocodingCoordinate'
        label:
          type: string
          description: Full human-readable label (e.g. 'London, England, United Kingdom')
        name:
          type: string
          description: Short name of the place
        country:
          type: string
          description: Country name
        country_code:
          type: string
          description: ISO 3166-1 alpha-3 country code
        region:
          type: string
          description: Region/state/province
        county:
          type: string
          description: County/district
        locality:
          type: string
          description: City/town
        neighbourhood:
          type: string
          description: Neighbourhood/suburb
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: Result confidence score (0-1)
        place_type:
          type: string
          description: 'Place type: venue, address, street, locality, region, country'
    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.
    Origin:
      type: object
      required:
        - coordinates
        - resolved_from
      description: >-
        Echoed origin of the route. Always carries coordinates; geocoded fields
        (name/label/place_type/country_code) are present when the caller passed
        a string and omitted when the caller passed coordinates directly.
      properties:
        coordinates:
          type: object
          required:
            - lat
            - lng
          properties:
            lat:
              type: number
            lng:
              type: number
        resolved_from:
          type: string
          enum:
            - string
            - coordinates
          description: >-
            How the origin was supplied: `string` (geocoded internally) or
            `coordinates` (passed through verbatim).
        name:
          type: string
        label:
          type: string
        place_type:
          type: string
        country:
          type: string
        country_code:
          type: string
    GeocodingCoordinate:
      type: object
      required:
        - lat
        - lng
      properties:
        lat:
          type: number
          minimum: -90
          maximum: 90
        lng:
          type: number
          minimum: -180
          maximum: 180
    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

````