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

# Locate on Road

> Check if coordinates are on a routable road and get the nearest snapped position. Returns distance, on-road status, and optionally edge metadata (road class, surface, speed).



## OpenAPI

````yaml POST /v1/routing/locate
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/locate:
    post:
      tags:
        - Routing
      summary: Snap coordinates to the nearest road
      description: >-
        Check if coordinates are on a routable road and get the nearest snapped
        position. Returns distance, on-road status, and optionally edge metadata
        (road class, surface, speed).
      operationId: locateOnRoad
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocateRequest'
            examples:
              basic:
                summary: Check if points are on roads
                value:
                  locations:
                    - lat: 51.5322
                      lon: -0.124
                    - lat: 51.5055
                      lon: -0.0754
              verbose:
                summary: With road metadata
                value:
                  locations:
                    - lat: 51.5322
                      lon: -0.124
                  verbose: true
      responses:
        '200':
          description: Locate results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocateResponse'
            application/geo+json:
              schema:
                type: object
                description: >-
                  GeoJSON FeatureCollection of Point features for each located
                  point.
        '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:
    LocateRequest:
      type: object
      required:
        - locations
      properties:
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Coordinate'
          minItems: 1
          maxItems: 100
        travel:
          type: string
          enum:
            - auto
            - bicycle
            - pedestrian
            - bus
            - truck
          default: auto
          description: Filter edges by travel type
        verbose:
          type: boolean
          default: false
          description: Include edge metadata
        format:
          $ref: '#/components/schemas/Format'
    LocateResponse:
      type: object
      required:
        - locations
      properties:
        locations:
          type: array
          items:
            type: object
            required:
              - input
              - distance_meters
              - on_road
            properties:
              input:
                $ref: '#/components/schemas/Coordinate'
              snapped:
                $ref: '#/components/schemas/Coordinate'
                description: Snapped position (absent if not near road)
              distance_meters:
                type: number
                description: Distance to nearest road in meters
              on_road:
                type: boolean
                description: Whether near a routable road
              edges:
                type: array
                description: Present when verbose=true
                items:
                  type: object
                  required:
                    - names
                  properties:
                    names:
                      type: array
                      items:
                        type: string
                    road_class:
                      type: string
                      enum:
                        - motorway
                        - trunk
                        - primary
                        - secondary
                        - tertiary
                        - unclassified
                        - residential
                        - service
                      description: >-
                        Road classification (motorway, trunk, primary,
                        secondary, tertiary, unclassified, residential, service)
                    speed_kph:
                      type: number
                    surface:
                      type: string
                      enum:
                        - paved_smooth
                        - paved
                        - paved_rough
                        - compacted
                        - dirt
                        - gravel
                        - ground
                        - impassable
                      description: >-
                        Surface type (paved_smooth, paved, paved_rough,
                        compacted, dirt, gravel, ground, impassable)
                    elevation_meters:
                      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
    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

````