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

# Distance Matrix

> Compute a matrix of travel distances and durations between multiple origins and destinations. Returns pairwise distance and duration values for route planning and optimization.

Compute travel distances and durations between multiple origins and destinations at once.

### Optimal Planning

The distance matrix is essential for logistics and dispatching. It allows you to quickly find the nearest driver or service point across the road network.

### Request Body

* `coordinates`: A list of all unique points involved.
* `sources`: Indices into the `coordinates` list for start points.
* `destinations`: Indices into the `coordinates` list for end points.

### Note on Large Requests

The maximum number of source-destination pairs in a single request is limited. Contact us if you need to perform high-volume computations.


## OpenAPI

````yaml POST /routing/matrix
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/matrix:
    post:
      tags:
        - Routing
      summary: Distance Matrix
      description: >-
        Compute a matrix of travel distances and durations between multiple
        origins and destinations. Returns pairwise distance and duration values
        for route planning and optimization.
      operationId: Matrix
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatrixRequest'
              summary: request
              description: Coordinates with source and destination indices
        description: Coordinates with source and destination indices
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-MatrixResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Invalid coordinates or out-of-range indices
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Missing or invalid API key
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Internal server error
      security:
        - BearerAuth: []
components:
  schemas:
    MatrixRequest:
      description: >-
        Origins, destinations, and coordinates for computing a distance/duration
        matrix
      properties:
        coordinates:
          description: List of geographic coordinates (at least one required)
          items:
            $ref: '#/components/schemas/GeoPoint'
          type: array
          uniqueItems: false
        destinations:
          description: >-
            Zero-based indices into coordinates identifying destination points.
            If omitted, all coordinates are used as destinations.
          example:
            - 1
          items:
            type: integer
          type: array
          uniqueItems: false
        sources:
          description: >-
            Zero-based indices into coordinates identifying source points. If
            omitted, all coordinates are used as sources.
          example:
            - 0
          items:
            type: integer
          type: array
          uniqueItems: false
      required:
        - coordinates
      type: object
    Response-MatrixResponse:
      properties:
        data:
          $ref: '#/components/schemas/MatrixResponse'
        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
    MatrixResponse:
      description: Response payload
      properties:
        destinations:
          description: Snapped destination locations used for the matrix computation
          items:
            $ref: '#/components/schemas/MatrixItem'
          type: array
          uniqueItems: false
        distances:
          description: Matrix of travel distances in meters (sources x destinations)
          items:
            items:
              type: number
            type: array
          type: array
          uniqueItems: false
        durations:
          description: Matrix of travel durations in seconds (sources x destinations)
          items:
            items:
              type: number
            type: array
          type: array
          uniqueItems: false
        sources:
          description: Snapped source locations used for the matrix computation
          items:
            $ref: '#/components/schemas/MatrixItem'
          type: array
          uniqueItems: false
      type: object
    MatrixItem:
      description: Nearest routable point matched from the input coordinate
      properties:
        distance:
          description: >-
            Distance in meters between the input coordinate and this snapped
            location
          type: number
        location:
          $ref: '#/components/schemas/GeoPoint'
      type: object
  securitySchemes:
    BearerAuth:
      description: >-
        JWT Bearer token for authentication. Example: "Bearer
        YOUR_API_TOKEN_HERE"
      in: header
      name: Authorization
      type: apiKey

````