> ## 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. # Compute Routes (Google-compatible) > Drop-in replacement for the Google Routes API. Returns the standard response with additional physics enrichment per step. ## OpenAPI ````yaml POST /directions/v2:computeRoutes 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: /directions/v2:computeRoutes: post: tags: - Google-Compatible summary: Compute Routes (Google-compatible) description: >- Drop-in replacement for the Google Routes API. Returns the standard response with additional physics enrichment per step. operationId: googleComputeRoutes parameters: - name: X-Goog-FieldMask in: header required: false description: >- Accepted for Google compatibility but ignored. The full response is always returned. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ComputeRoutesRequest' examples: simple: summary: Simple A to B route value: origin: location: latLng: latitude: 41.878 longitude: -87.636 destination: location: latLng: latitude: 41.705 longitude: -87.613 with_vehicle: summary: Route with vehicle spec value: origin: location: latLng: latitude: 41.878 longitude: -87.636 destination: location: latLng: latitude: 41.705 longitude: -87.613 vehicleSpec: type: SEMI_TRAILER grossWeightKg: 36000 departureTime: '2026-03-01T14:00:00Z' with_alternatives: summary: Request alternative routes value: origin: location: latLng: latitude: 41.878 longitude: -87.636 destination: location: latLng: latitude: 41.705 longitude: -87.613 computeAlternativeRoutes: true responses: '200': description: >- Successfully computed route(s). The response matches the Google Routes API `computeRoutes` response shape exactly, with an additional `enrichment` field on each step. headers: X-Route-Id: description: >- The internal route resource ID. Use this to access the route via the `/v1/routes/{id}` endpoint. schema: type: string example: route_01HYX3MPK5XJQJG0NB0PRSDVWC content: application/json: schema: $ref: '#/components/schemas/GoogleComputeRoutesResponse' '400': description: Invalid request (e.g. unsupported waypoint type, missing location) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unsupported_waypoint: summary: Unsupported waypoint type value: error: type: invalid_request_error code: unsupported_waypoint_type message: >- Address and placeId waypoints are not supported; use latLng coordinates. param: origin doc_url: null missing_location: summary: Missing location value: error: type: invalid_request_error code: missing_location message: >- Waypoint origin must have a location with latLng coordinates. param: origin doc_url: null '422': description: Routing engine could not compute a route content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: no_route_found: summary: No route found value: error: type: routing_error code: no_route_found message: No route could be found between the specified locations. param: null doc_url: null invalid_location: summary: Invalid location value: error: type: routing_error code: invalid_location message: >- One or more locations could not be mapped to the road network. param: null doc_url: null '429': description: Rate limit exceeded (60 requests per minute per IP) headers: X-RateLimit-Limit: description: Maximum requests per window schema: type: integer example: 60 X-RateLimit-Remaining: description: Requests remaining schema: type: integer example: 0 X-RateLimit-Reset: description: Unix timestamp when window resets schema: type: integer Retry-After: description: Seconds to wait schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: rate_limit_error code: rate_limit_exceeded message: Rate limit exceeded. Maximum 60 requests per minute. param: null doc_url: null '503': description: Routing engine unavailable (connection error or timeout) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: routing_error code: routing_engine_unavailable message: Routing engine is unavailable. Please try again later. param: null doc_url: null components: schemas: ComputeRoutesRequest: type: object description: >- Request body for route computation. Accepts all Google Routes API fields — unsupported fields are silently ignored. required: - origin - destination properties: origin: $ref: '#/components/schemas/Waypoint' description: Origin waypoint (required) destination: $ref: '#/components/schemas/Waypoint' description: Destination waypoint (required) intermediates: type: array items: $ref: '#/components/schemas/Waypoint' default: [] description: Intermediate waypoints (stops or pass-through points) travelMode: type: string default: DRIVE description: Travel mode. Only `DRIVE` is supported (truck routing). routingPreference: type: string default: TRAFFIC_UNAWARE description: Routing preference. Traffic is not currently modeled. departureTime: type: string format: date-time description: >- Departure time in ISO 8601 UTC format. Affects school zone detection and time-based routing. computeAlternativeRoutes: type: boolean default: false description: >- When true and no intermediate waypoints, returns up to 3 alternative routes. routeModifiers: $ref: '#/components/schemas/RouteModifiers' description: Route modifiers (avoid tolls, highways, ferries) languageCode: type: string default: en-US description: Language for navigation instructions vehicleSpec: $ref: '#/components/schemas/VehicleSpec' description: >- Vehicle specification for physics enrichment. Defaults to SEMI_TRAILER preset if omitted. routingProfile: type: string default: balanced enum: - balanced - fuel_optimal - time_optimal - fatigue_aware description: Routing profile that adjusts enrichment weights profileOverrides: type: object additionalProperties: type: number default: {} description: 'Override individual profile weights (e.g. `{"fuelWeight": 1.5}`)' webhookUrl: type: string format: uri description: >- Webhook URL for async route completion notifications. Only used by `POST /v1/routes`. GoogleComputeRoutesResponse: type: object description: >- Response from the Google-compatible computeRoutes endpoint. Returns one or more routes in the same format as the Google Routes API, enriched with segment-level physics data (grade, curvature, fuel burn, zone flags). properties: routes: type: array items: $ref: '#/components/schemas/Route' description: Computed routes (primary + alternatives if requested) fallbackInfo: type: object nullable: true description: Google field — always null geocodingResults: type: object nullable: true description: Google field — always null required: - routes ErrorResponse: type: object description: Structured error response. properties: error: $ref: '#/components/schemas/ErrorDetail' required: - error Waypoint: type: object description: >- A waypoint for route computation. Only `location` with `latLng` is supported. `placeId` and `address` are not supported and will return an error. properties: location: $ref: '#/components/schemas/Location' description: Geographic location (required — must use latLng coordinates) placeId: type: string description: >- **Not supported.** Providing this will return an error. Use `location` with `latLng` instead. address: type: string description: >- **Not supported.** Providing this will return an error. Use `location` with `latLng` instead. via: type: boolean default: false description: >- If true, the waypoint is a pass-through point (no stop). If false, the waypoint is a stop. vehicleStopover: type: boolean default: false description: Accepted for Google compatibility, ignored. sideOfRoad: type: boolean default: false description: Accepted for Google compatibility, ignored. RouteModifiers: type: object description: Modifiers that affect route computation properties: avoidTolls: type: boolean default: false description: When true, avoids toll roads avoidHighways: type: boolean default: false description: When true, avoids highways avoidFerries: type: boolean default: false description: When true, avoids ferries avoidIndoor: type: boolean default: false description: Accepted for Google compatibility, ignored. VehicleSpec: type: object description: >- Vehicle specification for physics-based enrichment. All fields are optional — unset fields fall back to the preset for the given `type`. properties: type: type: string default: SEMI_TRAILER enum: - SEMI_TRAILER - BOX_TRUCK description: Vehicle preset type. Defaults to SEMI_TRAILER. grossWeightKg: type: number description: Gross vehicle weight in kilograms example: 36000 dragCoefficient: type: number description: Aerodynamic drag coefficient example: 0.65 frontalAreaM2: type: number description: Frontal area in square meters example: 9 rollingResistance: type: number description: Rolling resistance coefficient example: 0.007 heightM: type: number description: Vehicle height in meters example: 4.11 widthM: type: number description: Vehicle width in meters example: 2.6 lengthM: type: number description: Vehicle length in meters example: 21.64 axleLoadTonnes: type: number description: Maximum axle load in tonnes example: 9 fuelType: type: string default: DIESEL description: Fuel type example: DIESEL idleFuelLitersPerHour: type: number description: Fuel consumption at idle in liters per hour example: 2.5 engineEfficiency: type: number description: Engine thermal efficiency (0-1) example: 0.4 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 Location: type: object description: A geographic location properties: latLng: $ref: '#/components/schemas/LatLng' heading: type: integer description: Compass heading 0-360 (optional) minimum: 0 maximum: 360 required: - latLng 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') ````