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

# Calculate Matrix

> Compute a time and distance matrix between sources and targets. Returns a 2D matrix indexed by [source][target] with distance_meters and duration_seconds for each pair. Null cells indicate unreachable pairs. All distances are in meters regardless of request units.



## OpenAPI

````yaml POST /v1/routing/matrix
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/matrix:
    post:
      tags:
        - Routing
      summary: Calculate time/distance matrix
      description: >-
        Compute a time and distance matrix between sources and targets. Returns
        a 2D matrix indexed by [source][target] with distance_meters and
        duration_seconds for each pair. Null cells indicate unreachable pairs.
        All distances are in meters regardless of request units.
      operationId: calculateMatrix
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatrixRequest'
            examples:
              basic:
                summary: 2x2 distance matrix
                value:
                  sources:
                    - lat: 51.5322
                      lon: -0.124
                    - lat: 51.5055
                      lon: -0.0754
                  targets:
                    - lat: 51.5178
                      lon: -0.0823
                    - lat: 51.5055
                      lon: -0.0862
      responses:
        '200':
          description: Time/distance matrix
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatrixResponse'
            application/geo+json:
              schema:
                type: object
                description: >-
                  GeoJSON FeatureCollection where each source-target pair is a
                  Feature with straight-line LineString geometry. Properties
                  include distance_meters, duration_seconds, and source/target
                  indices.
        '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:
    MatrixRequest:
      type: object
      required:
        - sources
        - targets
      properties:
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Coordinate'
          minItems: 1
          maxItems: 50
        targets:
          type: array
          items:
            $ref: '#/components/schemas/Coordinate'
          minItems: 1
          maxItems: 50
        travel:
          type: string
          enum:
            - auto
            - bicycle
            - pedestrian
            - bus
            - truck
          default: auto
        travel_options:
          $ref: '#/components/schemas/TravelOptions'
        units:
          type: string
          enum:
            - kilometers
            - miles
          default: kilometers
        format:
          $ref: '#/components/schemas/Format'
    MatrixResponse:
      type: object
      required:
        - matrix
      description: Time/distance matrix with explicit units
      properties:
        matrix:
          type: array
          description: >-
            2D matrix indexed as matrix[source_index][target_index]. null =
            unreachable pair.
          items:
            type: array
            items:
              oneOf:
                - type: object
                  required:
                    - distance_meters
                    - duration_seconds
                  properties:
                    distance_meters:
                      type: number
                      description: Distance in meters
                    duration_seconds:
                      type: number
                      description: Duration in seconds
                - type: 'null'
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
    Coordinate:
      type: object
      required:
        - lat
        - lon
      properties:
        lat:
          type: number
          minimum: -90
          maximum: 90
        lon:
          type: number
          minimum: -180
          maximum: 180
    TravelOptions:
      type: object
      description: Fine-tuning options. Include only the key matching your travel type.
      properties:
        auto:
          type: object
          properties:
            use_highways:
              type: number
              minimum: 0
              maximum: 1
              description: 0 = avoid, 1 = prefer
            use_tolls:
              type: number
              minimum: 0
              maximum: 1
            use_ferry:
              type: number
              minimum: 0
              maximum: 1
            height:
              type: number
              description: Vehicle height in meters
            width:
              type: number
              description: Vehicle width in meters
            weight:
              type: number
              description: Vehicle weight in tonnes
        pedestrian:
          type: object
          properties:
            use_hills:
              type: number
              minimum: 0
              maximum: 1
              description: 0 = avoid hills, 1 = prefer hills
            walking_speed:
              type: number
              minimum: 0.5
              maximum: 25
              description: Speed in km/h
            max_hiking_difficulty:
              type: number
              minimum: 0
              maximum: 6
              description: SAC hiking scale (0-6)
            use_lit:
              type: number
              minimum: 0
              maximum: 1
              description: Prefer lit streets
            step_penalty:
              type: number
              description: Seconds penalty per stair transition
        bicycle:
          type: object
          properties:
            use_hills:
              type: number
              minimum: 0
              maximum: 1
              description: 0 = avoid hills, 1 = prefer hills
            cycling_speed:
              type: number
              minimum: 5
              maximum: 50
              description: Speed in km/h
            bicycle_type:
              type: string
              enum:
                - road
                - hybrid
                - cross
                - mountain
            use_roads:
              type: number
              minimum: 0
              maximum: 1
            avoid_bad_surfaces:
              type: number
              minimum: 0
              maximum: 1
        truck:
          type: object
          properties:
            use_highways:
              type: number
              minimum: 0
              maximum: 1
            use_tolls:
              type: number
              minimum: 0
              maximum: 1
            height:
              type: number
              description: Vehicle height in meters
            width:
              type: number
              description: Vehicle width in meters
            weight:
              type: number
              description: Vehicle weight in tonnes
            hazmat:
              type: boolean
            axle_load:
              type: number
              description: Axle load in tonnes
    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).
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Footstep API key

````