> ## 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. # Snap GPS Trace > Map-match a GPS trace to the road network. Returns a snapped polyline with confidence score. Optionally includes directions with terrain analytics, road attributes (surface, grade, road class), and per-point match quality. ## OpenAPI ````yaml POST /v1/routing/snap 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/snap: post: tags: - Routing summary: Snap a GPS trace to the road network description: >- Map-match a GPS trace to the road network. Returns a snapped polyline with confidence score. Optionally includes directions with terrain analytics, road attributes (surface, grade, road class), and per-point match quality. operationId: snapTrace requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SnapRequest' examples: basic: summary: Snap GPS trace to roads value: shape: - lat: 51.5322 lon: -0.124 - lat: 51.5013 lon: -0.1228 - lat: 51.5019 lon: -0.1209 - lat: 51.5025 lon: -0.119 with_attributes: summary: Get road details too value: shape: - lat: 51.5322 lon: -0.124 - lat: 51.5013 lon: -0.1228 - lat: 51.5019 lon: -0.1209 output: both gps_accuracy: 10 responses: '200': description: Snapped trace with optional route and attributes content: application/json: schema: $ref: '#/components/schemas/SnapResponse' '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: SnapRequest: type: object description: Provide either shape or encoded_polyline properties: shape: type: array items: type: object required: - lat - lon properties: lat: type: number lon: type: number time: type: number description: Unix timestamp accuracy: type: number description: GPS accuracy in meters minItems: 2 maxItems: 20000 encoded_polyline: type: string travel: type: string enum: - auto - bicycle - pedestrian - bus - truck default: auto output: type: string enum: - route - attributes - both default: route description: >- route = directions with terrain, attributes = road details, both = combined gps_accuracy: type: number minimum: 1 maximum: 100 default: 10 description: >- Expected GPS accuracy in meters. Default 10 reflects typical urban phone GPS; bump higher for noisy traces, lower for high-quality recordings. search_radius: type: number minimum: 1 maximum: 100 default: 25 description: Search radius in meters elevation_interval: type: number minimum: 10 maximum: 200 default: 30 shape_match: type: string enum: - edge_walk - map_snap - walk_or_snap default: walk_or_snap description: >- Matching strategy. `edge_walk` requires the trace to follow exact road edges (high-quality data only). `map_snap` is strict per-point snapping. `walk_or_snap` (default) is forgiving — falls back to walking the closest edges when an exact snap fails, which matches typical phone-GPS behaviour. format: $ref: '#/components/schemas/Format' SnapResponse: type: object required: - snapped_shape - confidence properties: snapped_shape: type: string description: Encoded polyline of snapped trace confidence: type: number minimum: 0 maximum: 1 description: Match confidence score (0-1) match_quality: type: string enum: - low description: >- Present when the match is unreliable. Currently the only value is `low` (confidence below 0.5). Distance, duration, edges, and terrain are still populated but should be treated as approximate. match_quality_reason: type: string description: >- Human-readable explanation of why match_quality is set. Present whenever match_quality is set. route: type: object description: Present when output includes 'route'. Includes terrain analytics. properties: legs: type: array items: $ref: '#/components/schemas/Leg' distance_meters: type: number description: Total distance in meters duration_seconds: type: number description: Total duration in seconds terrain: $ref: '#/components/schemas/TerrainSummary' edges: type: array description: Present when output includes 'attributes'. Road segment details. items: type: object required: - names - length_meters properties: names: type: array items: type: string description: Road name(s) length_meters: type: number description: Edge length in meters speed_kph: type: number description: Speed limit in km/h road_class: type: string enum: - motorway - trunk - primary - secondary - tertiary - unclassified - residential - service description: >- Road classification (motorway, trunk, primary, secondary, tertiary, unclassified, residential, service) 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) grade_percent: type: number description: Grade as a percentage matched_points: type: array description: Per-point match quality details items: type: object required: - lat - lon - type - distance_from_trace_meters - edge_index properties: lat: type: number lon: type: number type: type: string enum: - matched - interpolated - unmatched distance_from_trace_meters: type: number description: Distance from original trace point in meters edge_index: type: number description: Index into the edges array Error: type: object required: - error - message properties: error: type: string message: type: string 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). 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' 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 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() 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 ````