> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapshit.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Route

> Retrieve a route resource by its ID.

<Note>Completed routes are cached for 6 hours, then expire. Use `DELETE` to remove them earlier if needed.</Note>


## OpenAPI

````yaml GET /v1/routes/{route_id}
openapi: 3.1.0
info:
  title: Motion Freight Router API
  description: >-
    Drop-in replacement for Google Routes API with segment-level physics
    enrichment for heavy freight. Provides both a Google-compatible synchronous
    endpoint and stateful route management endpoints.
  version: 1.0.0
  license:
    name: MIT
servers:
  - url: http://localhost:8000
    description: Local development
security: []
tags:
  - name: Google-Compatible
    description: Drop-in replacement for Google Routes API. Same request/response format.
  - name: Routes
    description: Stateful route management with sync/async computation.
  - name: Telemetry
    description: Segment-level physics telemetry data (grade, curvature, fuel burn).
  - name: Health
    description: API health and status.
paths:
  /v1/routes/{route_id}:
    get:
      tags:
        - Routes
      summary: Get Route
      description: Retrieve a route resource by its ID.
      operationId: getRoute
      parameters:
        - name: route_id
          in: path
          required: true
          description: The unique route resource ID (prefixed with `route_`)
          schema:
            type: string
            example: route_01HYX3MPK5XJQJG0NB0PRSDVWC
      responses:
        '200':
          description: Route resource found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteResource'
        '404':
          description: Route not found or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: invalid_request_error
                  code: route_not_found
                  message: Route route_01HYX3MPK5XJQJG0NB0PRSDVWC not found.
                  param: route_id
                  doc_url: null
components:
  schemas:
    RouteResource:
      type: object
      description: A route resource. Used by the `/v1/routes` endpoint family.
      properties:
        id:
          type: string
          description: Unique route ID (prefixed with `route_`)
          example: route_01HYX3MPK5XJQJG0NB0PRSDVWC
        object:
          type: string
          enum:
            - route
          description: Object type (always `route`)
        status:
          type: string
          enum:
            - processing
            - complete
            - failed
          description: >-
            Current status of the route computation.


            - `processing` - route is still being computed (routes array is
            empty)

            - `complete` - route computation finished (routes array is
            populated)

            - `failed` - route computation failed (error object is populated)
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp of creation
          example: '2026-02-28T15:12:32Z'
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
          description: Computed routes (empty while `processing`)
        fallbackInfo:
          type: object
          nullable: true
        geocodingResults:
          type: object
          nullable: true
        warnings:
          type: array
          items:
            type: string
        error:
          type: object
          nullable: true
          description: Error details (populated when `status` is `failed`)
          properties:
            code:
              type: string
            message:
              type: string
      required:
        - id
        - object
        - status
        - createdAt
        - routes
    ErrorResponse:
      type: object
      description: Structured error response.
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
        - error
    Route:
      type: object
      description: >-
        A computed route. Matches Google's Route object with enrichment on each
        step.
      properties:
        routeLabels:
          type: array
          items:
            type: string
            enum:
              - DEFAULT_ROUTE
              - DEFAULT_ROUTE_ALTERNATE
          description: >-
            Route labels. Primary route is `DEFAULT_ROUTE`, alternatives are
            `DEFAULT_ROUTE_ALTERNATE`.
        legs:
          type: array
          items:
            $ref: '#/components/schemas/RouteLeg'
        distanceMeters:
          type: integer
          description: Total route distance in meters
        duration:
          type: string
          description: Total route duration (e.g. `"3600s"`)
        staticDuration:
          type: string
          description: Same as duration (traffic not modeled)
        polyline:
          $ref: '#/components/schemas/Polyline'
          description: Full route polyline
        description:
          type: string
          description: Route description
        warnings:
          type: array
          items:
            type: string
          description: Route warnings
        viewport:
          $ref: '#/components/schemas/Viewport'
        travelAdvisory:
          type: object
          nullable: true
        optimizedIntermediateWaypointIndex:
          type: array
          items:
            type: integer
        localizedValues:
          type: object
          nullable: true
        routeToken:
          type: string
          nullable: true
        polylineDetails:
          type: object
          nullable: true
      required:
        - routeLabels
        - legs
        - distanceMeters
        - duration
        - staticDuration
        - polyline
    ErrorDetail:
      type: object
      description: Error detail object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
            - routing_error
            - rate_limit_error
            - api_error
            - enrichment_error
          description: Error type category
        code:
          type: string
          description: Machine-readable error code
          example: route_not_found
        message:
          type: string
          description: Human-readable error message
        param:
          type: string
          nullable: true
          description: The parameter that caused the error
        doc_url:
          type: string
          nullable: true
          description: URL to relevant documentation
      required:
        - type
        - code
        - message
    RouteLeg:
      type: object
      description: >-
        A leg of a route (between two consecutive stops). Matches Google's
        RouteLeg.
      properties:
        distanceMeters:
          type: integer
          description: Total leg distance in meters
        duration:
          type: string
          description: Total leg duration (e.g. `"1820s"`)
        staticDuration:
          type: string
          description: Same as duration (traffic not modeled)
        polyline:
          $ref: '#/components/schemas/Polyline'
        startLocation:
          type: object
          properties:
            latLng:
              $ref: '#/components/schemas/LatLng'
        endLocation:
          type: object
          properties:
            latLng:
              $ref: '#/components/schemas/LatLng'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/RouteLegStep'
          description: Individual steps within this leg
        travelAdvisory:
          type: object
          nullable: true
          description: Google field — always null
        localizedValues:
          type: object
          nullable: true
          description: Google field — always null
        stepsOverview:
          type: object
          nullable: true
          description: Google field — always null
      required:
        - distanceMeters
        - duration
        - staticDuration
        - polyline
        - startLocation
        - endLocation
        - steps
    Polyline:
      type: object
      description: An encoded polyline string (Google precision 5)
      properties:
        encodedPolyline:
          type: string
          description: Encoded polyline string at precision 5 (Google standard)
      required:
        - encodedPolyline
    Viewport:
      type: object
      description: A bounding box for the route
      properties:
        low:
          type: object
          description: Southwest corner
          properties:
            latitude:
              type: number
            longitude:
              type: number
        high:
          type: object
          description: Northeast corner
          properties:
            latitude:
              type: number
            longitude:
              type: number
    LatLng:
      type: object
      description: A latitude/longitude coordinate pair
      properties:
        latitude:
          type: number
          format: double
          description: Latitude in degrees
          example: 41.878
        longitude:
          type: number
          format: double
          description: Longitude in degrees
          example: -87.636
      required:
        - latitude
        - longitude
    RouteLegStep:
      type: object
      description: >-
        A step within a route leg. Matches Google's RouteLegStep with an
        additional `enrichment` field.
      properties:
        distanceMeters:
          type: integer
          description: Step distance in meters
        staticDuration:
          type: string
          description: Step duration as a string (e.g. `"28s"`)
          example: 28s
        polyline:
          $ref: '#/components/schemas/Polyline'
        startLocation:
          type: object
          description: Start location
          properties:
            latLng:
              $ref: '#/components/schemas/LatLng'
        endLocation:
          type: object
          description: End location
          properties:
            latLng:
              $ref: '#/components/schemas/LatLng'
        navigationInstruction:
          $ref: '#/components/schemas/NavigationInstruction'
        travelMode:
          type: string
          default: DRIVE
          description: Always `DRIVE`
        enrichment:
          $ref: '#/components/schemas/StepEnrichment'
          description: Physics-based enrichment data (Motion extension)
        travelAdvisory:
          type: object
          nullable: true
          description: Google field — always null
        localizedValues:
          type: object
          nullable: true
          description: Google field — always null
        transitDetails:
          type: object
          nullable: true
          description: Google field — always null
      required:
        - distanceMeters
        - staticDuration
        - polyline
        - startLocation
        - endLocation
        - navigationInstruction
    NavigationInstruction:
      type: object
      description: Navigation instruction for a route step
      properties:
        maneuver:
          type: string
          description: Google-compatible maneuver type
          enum:
            - DEPART
            - STRAIGHT
            - NAME_CHANGE
            - TURN_SLIGHT_RIGHT
            - TURN_RIGHT
            - TURN_SHARP_RIGHT
            - TURN_SLIGHT_LEFT
            - TURN_LEFT
            - TURN_SHARP_LEFT
            - UTURN_RIGHT
            - UTURN_LEFT
            - RAMP_RIGHT
            - RAMP_LEFT
            - FORK_RIGHT
            - FORK_LEFT
            - MERGE
            - ROUNDABOUT_RIGHT
            - ROUNDABOUT_LEFT
            - FERRY
            - FERRY_TRAIN
            - MANEUVER_UNSPECIFIED
        instructions:
          type: string
          description: Human-readable navigation instruction text
      required:
        - maneuver
        - instructions
    StepEnrichment:
      type: object
      description: >-
        Physics-based enrichment data for a route step. This is the extension
        data that rides alongside Google's standard step fields.
      properties:
        gradePercent:
          type: number
          nullable: true
          description: Road grade as a percentage (positive = uphill, negative = downhill)
          example: 2.5
        curvatureDegreesPerKm:
          type: number
          nullable: true
          description: Road curvature in degrees of bearing change per kilometer
          example: 15.3
        fuelBurnLiters:
          type: number
          nullable: true
          description: Estimated fuel burn for this step in liters
          example: 0.42
        zoneFlags:
          type: array
          items:
            type: string
            enum:
              - SCHOOL_ZONE
              - RESIDENTIAL
          description: Active zone flags for this step
          example:
            - SCHOOL_ZONE
        speedLimitKmh:
          type: number
          nullable: true
          description: Speed limit in km/h (if available)
        roadClass:
          type: string
          nullable: true
          description: Road classification
          enum:
            - MOTORWAY
            - TRUNK
            - PRIMARY
            - SECONDARY
            - TERTIARY
            - UNCLASSIFIED
            - RESIDENTIAL
            - SERVICE_ROAD
        degradedFields:
          type: array
          items:
            type: string
          description: >-
            List of fields that could not be computed (e.g. elevation
            unavailable)
        degradedReason:
          type: string
          nullable: true
          description: Reason for field degradation (e.g. 'elevation_unavailable')

````