DistanceMatrixResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/google-maps/json-schema/google-maps-distance-matrix-response-schema.json",
  "title": "DistanceMatrixResponse",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/google-maps-platform-openapi.yml#/components/schemas/DistanceMatrixResponse",
  "type": "object",
  "required": [
    "origin_addresses",
    "destination_addresses",
    "rows",
    "status"
  ],
  "properties": {
    "origin_addresses": {
      "description": "An array of addresses as returned by the API from your original request. These are formatted by the geocoder and localized according to the language parameter passed with the request. This content is meant to be read as-is. Do not programatically parse the formatted addresses.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "destination_addresses": {
      "description": "An array of addresses as returned by the API from your original request. As with `origin_addresses`, these are localized if appropriate. This content is meant to be read as-is. Do not programatically parse the formatted addresses.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "rows": {
      "description": "An array of elements, which in turn each contain a `status`, `duration`, and `distance` element.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/DistanceMatrixRow"
      }
    },
    "status": {
      "description": "Contains the status of the request, and may contain debugging information to help you track down why the request failed.",
      "$ref": "#/$defs/DistanceMatrixStatus"
    },
    "error_message": {
      "description": "A string containing the human-readable text of any errors encountered while the request was being processed.",
      "type": "string"
    }
  },
  "$defs": {
    "DistanceMatrixElement": {
      "type": "object",
      "title": "DistanceMatrixElement",
      "required": [
        "status"
      ],
      "properties": {
        "fare": {
          "description": "If present, contains the total fare (that is, the total ticket costs) on this route. This property is only returned for transit requests and only for transit providers where fare information is available.",
          "$ref": "#/$defs/Fare"
        },
        "distance": {
          "description": "The total distance of this route, expressed in meters (value) and as text. The textual value uses the unit system specified with the unit parameter of the original request, or the origin's region.",
          "$ref": "#/$defs/TextValueObject"
        },
        "duration_in_traffic": {
          "description": "The length of time it takes to travel this route, based on current and historical traffic conditions. See the `traffic_model` request parameter for the options you can use to request that the returned value is optimistic, pessimistic, or a best-guess estimate. The duration is expressed in seconds (the value field) and as text. The textual representation is localized according to the query's language parameter. The duration in traffic is returned only if all of the following are true:\n\n* The request includes a `departure_time` parameter.\n* Traffic conditions are available for the requested route.\n* The mode parameter is set to driving.\n",
          "$ref": "#/$defs/TextValueObject"
        },
        "duration": {
          "description": "The length of time it takes to travel this route, expressed in seconds (the value field) and as text. The textual representation is localized according to the query's language parameter.",
          "$ref": "#/$defs/TextValueObject"
        },
        "status": {
          "description": "A status for the element.",
          "$ref": "#/$defs/DistanceMatrixElementStatus"
        }
      }
    },
    "DistanceMatrixElementStatus": {
      "type": "string",
      "title": "DistanceMatrixElementStatus",
      "description": "- `OK` indicates the response contains a valid result.\n- `NOT_FOUND` indicates that the origin and/or destination of this pairing could not be geocoded.\n- `ZERO_RESULTS` indicates no route could be found between the origin and destination.\n- `MAX_ROUTE_LENGTH_EXCEEDED` indicates the requested route is too long and cannot be processed.\n",
      "enum": [
        "OK",
        "NOT_FOUND",
        "ZERO_RESULTS",
        "MAX_ROUTE_LENGTH_EXCEEDED"
      ]
    },
    "DistanceMatrixRow": {
      "type": "object",
      "title": "DistanceMatrixRow",
      "required": [
        "elements"
      ],
      "properties": {
        "elements": {
          "description": "When the Distance Matrix API returns results, it places them within a JSON rows array. Even if no results are returned (such as when the origins and/or destinations don't exist), it still returns an empty array. \n\nRows are ordered according to the values in the origin parameter of the request. Each row corresponds to an origin, and each element within that row corresponds to a pairing of the origin with a destination value.\n\nEach row array contains one or more element entries, which in turn contain the information about a single origin-destination pairing.\n",
          "type": "array",
          "items": {
            "$ref": "#/$defs/DistanceMatrixElement"
          }
        }
      }
    },
    "DistanceMatrixStatus": {
      "type": "string",
      "title": "DistanceMatrixStatus",
      "description": "Status codes returned by service.\n- `OK` indicates the response contains a valid result.\n- `INVALID_REQUEST` indicates that the provided request was invalid.\n- `MAX_ELEMENTS_EXCEEDED` indicates that the product of origins and destinations exceeds the per-query limit.\n- `MAX_DIMENSIONS_EXCEEDED` indicates that the number of origins or destinations exceeds the per-query limit.\n- `OVER_DAILY_LIMIT` indicates any of the following:\n  - The API key is missing or invalid.\n  - Billing has not been enabled on your account.\n  - A self-imposed usage cap has been exceeded.\n  - The provided method of payment is no longer valid (for example, a credit card has expired).\n- `OVER_QUERY_LIMIT` indicates the service has received too many requests from your application within the allowed time period.\n- `REQUEST_DENIED` indicates that the service denied use of the Distance Matrix service by your application.\n- `UNKNOWN_ERROR` indicates a Distance Matrix request could not be processed due to a server error. The request may succeed if you try again.\n",
      "enum": [
        "OK",
        "INVALID_REQUEST",
        "MAX_ELEMENTS_EXCEEDED",
        "MAX_DIMENSIONS_EXCEEDED",
        "OVER_DAILY_LIMIT",
        "OVER_QUERY_LIMIT",
        "REQUEST_DENIED",
        "UNKNOWN_ERROR"
      ]
    },
    "Fare": {
      "type": "object",
      "title": "Fare",
      "description": "The total fare for the route.\n\n```\n{\n  \"currency\" : \"USD\",\n  \"value\" : 6,\n  \"text\" : \"$6.00\"\n}\n```\n",
      "required": [
        "currency",
        "value",
        "text"
      ],
      "properties": {
        "currency": {
          "type": "string",
          "description": "An [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) indicating the currency that the amount is expressed in."
        },
        "value": {
          "type": "number",
          "description": "The total fare amount, in the currency specified."
        },
        "text": {
          "type": "string",
          "description": "The total fare amount, formatted in the requested language."
        }
      }
    },
    "TextValueObject": {
      "type": "object",
      "title": "TextValueObject",
      "description": "An object containing a numeric value and its formatted text representation.",
      "required": [
        "text",
        "value"
      ],
      "properties": {
        "text": {
          "description": "String value.",
          "type": "string"
        },
        "value": {
          "description": "Numeric value.",
          "type": "number"
        }
      }
    }
  }
}