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

# Routing Directions

> Calculate turn-by-turn routing directions between two or more coordinates. Returns routes with optional step-by-step navigation instructions, voice guidance, and banner instructions.



## OpenAPI

````yaml /swagger.json post /routing/directions
openapi: 3.1.0
info:
  description: >-
    Hudhud Maps provides the most accurate, real-time mapping data for the
    Kingdom of Saudi Arabia.
  title: Next-Generation Geospatial Intelligence for Saudi Arabia
  version: '1.0'
servers:
  - description: Production
    url: https://b.hudhud.sa/v1
security: []
externalDocs:
  description: ''
  url: ''
paths:
  /routing/directions:
    post:
      tags:
        - Routing
      summary: Routing Directions
      description: >-
        Calculate turn-by-turn routing directions between two or more
        coordinates. Returns routes with optional step-by-step navigation
        instructions, voice guidance, and banner instructions.
      operationId: RoutingDirections
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoutingDirectionsRequest'
              summary: request
              description: routing directions request body
        description: routing directions request body
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-RoutingDirectionsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Invalid request body or coordinates
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: code=unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: code=not_found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Internal Server Error
      security:
        - BearerAuth: []
components:
  schemas:
    RoutingDirectionsRequest:
      description: >-
        Coordinates for calculating turn-by-turn route directions. Instruction
        language is taken from the Accept-Language header (defaults to Arabic).
      properties:
        coordinates:
          description: 'Coordinates for the route: [ [lng, lat], [lng, lat] ]'
          items:
            $ref: '#/components/schemas/GeoPoint'
          type: array
          uniqueItems: false
      type: object
    Response-RoutingDirectionsResponse:
      properties:
        data:
          $ref: '#/components/schemas/RoutingDirectionsResponse'
        error:
          description: Error message (only present when ok is false)
          example: ''
          type: string
        ok:
          description: Whether the request was successful
          example: true
          type: boolean
      type: object
    Response-any:
      properties:
        data:
          description: Response payload
        error:
          description: Error message (only present when ok is false)
          example: ''
          type: string
        ok:
          description: Whether the request was successful
          example: true
          type: boolean
      type: object
    GeoPoint:
      description: The location used as the proximity pivot for relevance
      properties:
        lat:
          example: 24.7136
          format: double
          type: number
        lon:
          example: 46.6753
          format: double
          type: number
      required:
        - lat
        - lon
      type: object
    RoutingDirectionsResponse:
      description: Response payload
      properties:
        code:
          description: Status code of the response (e.g., Ok, NoRoute)
          example: Ok
          type: string
        routes:
          description: Array of calculated route objects
          items:
            $ref: '#/components/schemas/SimpleRoute'
          type: array
          uniqueItems: false
        waypoints:
          description: Details about the input coordinates snapped to the road network
          items:
            $ref: '#/components/schemas/DirectionsWaypoint'
          type: array
          uniqueItems: false
      type: object
    SimpleRoute:
      properties:
        distance:
          $ref: '#/components/schemas/SimpleDistance'
        duration:
          $ref: '#/components/schemas/SimpleDuration'
        geometry:
          type: string
        legs:
          items:
            $ref: '#/components/schemas/SimpleLeg'
          type: array
          uniqueItems: false
      type: object
    DirectionsWaypoint:
      properties:
        location:
          items:
            type: number
          type: array
          uniqueItems: false
        name:
          type: string
      type: object
    SimpleDistance:
      properties:
        text:
          description: |-
            Human-readable rendering: "X km" (1 decimal) at or above 1000m,
            otherwise "X m" (rounded to the nearest meter).
          example: 1.5 km
          type: string
        value:
          description: Raw distance in meters.
          example: 1500
          type: number
      type: object
    SimpleDuration:
      properties:
        text:
          description: |-
            Human-readable rendering: "1 min" for anything under two minutes,
            otherwise "X mins" rounded to the nearest minute.
          example: 3 mins
          type: string
        value:
          description: Raw duration in seconds.
          example: 180
          type: number
      type: object
    SimpleLeg:
      properties:
        distance:
          $ref: '#/components/schemas/SimpleDistance'
        duration:
          $ref: '#/components/schemas/SimpleDuration'
        steps:
          items:
            $ref: '#/components/schemas/SimpleStep'
          type: array
          uniqueItems: false
      type: object
    SimpleStep:
      properties:
        distance:
          $ref: '#/components/schemas/SimpleDistance'
        duration:
          $ref: '#/components/schemas/SimpleDuration'
        end_location:
          $ref: '#/components/schemas/GeoPoint'
        maneuver:
          example: turn-right
          type: string
        mode:
          example: driving
          type: string
        start_location:
          $ref: '#/components/schemas/GeoPoint'
        text_instruction:
          example: Turn right onto King Fahd Road
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      description: >-
        JWT Bearer token for authentication. Example: "Bearer
        YOUR_API_TOKEN_HERE"
      in: header
      name: Authorization
      type: apiKey

````