---
title: "Calculate distance matrix"
method: POST
path: "/distance-matrix"
tags: ["distance-matrix"]
---

# Calculate distance matrix

`POST /distance-matrix`

## Request body

- object
  - `origins` string[], required
  - `destinations` string[], required
  - `mode` 'driving' | 'haversine' | 'straightline'
  - `units` 'miles' | 'km'
  - `max_results` integer
  - `max_distance` number
  - `max_duration` integer
  - `order_by` 'distance' | 'duration'
  - `min_distance` number
  - `min_duration` integer
  - `sort_order` 'asc' | 'desc'
  - `country` string

## Response `200`

Successful response

- DistanceMatrixResponse
  - `mode` string
  - `results` DistanceMatrixRow[]
    - `origin` DistanceMatrixOriginRow
      - `query` string
      - `location` number[]
      - `id` string, nullable
      - `geocode` GeocodingResult
        - `stable_address_key` string, nullable
        - `address_components` AddressComponents
          - `number` string
          - `predirectional` string
          - `street` string
          - `suffix` string
          - `formatted_street` string
          - `city` string
          - `county` string
          - `state_province` string
          - `postal_code` string
          - `country` string
          - `building_name` string
          - `nation` string
          - `postdirectional` string
        - `address_lines` string[]
        - `formatted_address` string
        - `location` Location
          - `lat` number, float
          - `lng` number, float
        - `accuracy` number, float
        - `accuracy_type` string
        - `match_type` string, nullable
        - `source` string
        - `fields` FieldAppends
          - `congressional_districts` CongressionalDistricts[]
            - `name` string
            - `district_number` integer
            - `ocd_id` string
            - `congress_number` string
            - `congress_years` string
            - `proportion` integer
            - `current_legislators` CurrentLegislator[]
              - …
          - `timezone` Timezone
            - `name` string
            - `utc_offset` integer
            - `observes_dst` boolean
            - `abbreviation` string
            - `source` string
          - `census` Census
            - `2024` CensusGeography
              - …
            - `2025` CensusGeography
              - …
          - `acs` Acs
            - `meta` AcsAppendMeta
              - …
            - `demographics` Demographics
              - …
            - `economics` Economics
              - …
            - `families` Families
              - …
            - `housing` Housing
              - …
            - `social` AcsSocialData
              - …
          - `ffiec` Ffiec
            - `collection_year` integer
            - `msa_md_code` string
            - `fips_state_code` string
            - `fips_county_code` string
            - `census_tract` string
            - `principal_city` boolean
            - `small_county` SmallCounty
              - …
            - `split_tract` SmallCounty
              - …
            - `demographic_data` SmallCounty
              - …
            - `urban_rural_flag` SmallCounty
              - …
            - `msa_md_median_family_income` integer
            - `msa_md_median_household_income` integer
            - `tract_median_family_income_percentage` number, float
            - `ffiec_estimated_msa_md_median_family_income` integer
            - `income_indicator` string
            - `cra_poverty_criteria` boolean
            - `cra_unemployment_criteria` boolean
            - `cra_distressed_criteria` boolean
            - `cra_remote_rural_low_density_criteria` boolean
            - `previous_year_cra_distressed_criteria` boolean
            - `previous_year_cra_underserved_criterion` boolean
            - `meets_current_previous_criteria` boolean
            - `tract_minority_population_percentage` number, float
          - `school_districts` object
            - `unified` Unified
              - …
          - `state_legislative_districts` StateLegislativeDistricts
            - `house` House[]
              - …
            - `senate` House[]
              - …
          - `uk_devolved` UKLegislativeDistrict[]
            - `district_type` string
            - `gss_code` string
            - `ocd_id` string
            - `name` string
            - `is_upcoming_district` boolean
            - `source` string
          - `uk_local` UKLegislativeDistrict[]
            - `district_type` string
            - `gss_code` string
            - `ocd_id` string
            - `name` string
            - `is_upcoming_district` boolean
            - `source` string
          - `uk_westminster` UKLegislativeDistrict[]
            - `district_type` string
            - `gss_code` string
            - `ocd_id` string
            - `name` string
            - `is_upcoming_district` boolean
            - `source` string
          - `zip4` Zip4
            - `record_type` RecordType
              - …
            - `residential` boolean
            - `carrier_route` CarrierRoute
              - …
            - `building_or_firm_name` string, nullable
            - `plus4` string[]
            - `zip9` string[]
            - `government_building` string, nullable
            - `facility_code` RecordType
              - …
            - `city_delivery` boolean
            - `valid_delivery_area` boolean
            - `exact_match` boolean
        - `destinations` DistanceDestination[]
          - `query` string
          - `location` number[]
          - `distance_miles` number
          - `distance_km` number, float
          - `duration_seconds` integer, nullable
          - `id` string, nullable
          - `geocode` GeocodingResult — recursive
    - `destinations` DistanceMatrixCell[]
      - `query` string
      - `location` number[]
      - `id` string, nullable
      - `distance_miles` number, float
      - `distance_km` number, float
      - `geocode` GeocodingResult
        - `stable_address_key` string, nullable
        - `address_components` AddressComponents
          - `number` string
          - `predirectional` string
          - `street` string
          - `suffix` string
          - `formatted_street` string
          - `city` string
          - `county` string
          - `state_province` string
          - `postal_code` string
          - `country` string
          - `building_name` string
          - `nation` string
          - `postdirectional` string
        - `address_lines` string[]
        - `formatted_address` string
        - `location` Location
          - `lat` number, float
          - `lng` number, float
        - `accuracy` number, float
        - `accuracy_type` string
        - `match_type` string, nullable
        - `source` string
        - `fields` FieldAppends
          - `congressional_districts` CongressionalDistricts[]
            - `name` string
            - `district_number` integer
            - `ocd_id` string
            - `congress_number` string
            - `congress_years` string
            - `proportion` integer
            - `current_legislators` CurrentLegislator[]
              - …
          - `timezone` Timezone
            - `name` string
            - `utc_offset` integer
            - `observes_dst` boolean
            - `abbreviation` string
            - `source` string
          - `census` Census
            - `2024` CensusGeography
              - …
            - `2025` CensusGeography
              - …
          - `acs` Acs
            - `meta` AcsAppendMeta
              - …
            - `demographics` Demographics
              - …
            - `economics` Economics
              - …
            - `families` Families
              - …
            - `housing` Housing
              - …
            - `social` AcsSocialData
              - …
          - `ffiec` Ffiec
            - `collection_year` integer
            - `msa_md_code` string
            - `fips_state_code` string
            - `fips_county_code` string
            - `census_tract` string
            - `principal_city` boolean
            - `small_county` SmallCounty
              - …
            - `split_tract` SmallCounty
              - …
            - `demographic_data` SmallCounty
              - …
            - `urban_rural_flag` SmallCounty
              - …
            - `msa_md_median_family_income` integer
            - `msa_md_median_household_income` integer
            - `tract_median_family_income_percentage` number, float
            - `ffiec_estimated_msa_md_median_family_income` integer
            - `income_indicator` string
            - `cra_poverty_criteria` boolean
            - `cra_unemployment_criteria` boolean
            - `cra_distressed_criteria` boolean
            - `cra_remote_rural_low_density_criteria` boolean
            - `previous_year_cra_distressed_criteria` boolean
            - `previous_year_cra_underserved_criterion` boolean
            - `meets_current_previous_criteria` boolean
            - `tract_minority_population_percentage` number, float
          - `school_districts` object
            - `unified` Unified
              - …
          - `state_legislative_districts` StateLegislativeDistricts
            - `house` House[]
              - …
            - `senate` House[]
              - …
          - `uk_devolved` UKLegislativeDistrict[]
            - `district_type` string
            - `gss_code` string
            - `ocd_id` string
            - `name` string
            - `is_upcoming_district` boolean
            - `source` string
          - `uk_local` UKLegislativeDistrict[]
            - `district_type` string
            - `gss_code` string
            - `ocd_id` string
            - `name` string
            - `is_upcoming_district` boolean
            - `source` string
          - `uk_westminster` UKLegislativeDistrict[]
            - `district_type` string
            - `gss_code` string
            - `ocd_id` string
            - `name` string
            - `is_upcoming_district` boolean
            - `source` string
          - `zip4` Zip4
            - `record_type` RecordType
              - …
            - `residential` boolean
            - `carrier_route` CarrierRoute
              - …
            - `building_or_firm_name` string, nullable
            - `plus4` string[]
            - `zip9` string[]
            - `government_building` string, nullable
            - `facility_code` RecordType
              - …
            - `city_delivery` boolean
            - `valid_delivery_area` boolean
            - `exact_match` boolean
        - `destinations` DistanceDestination[]
          - `query` string
          - `location` number[]
          - `distance_miles` number
          - `distance_km` number, float
          - `duration_seconds` integer, nullable
          - `id` string, nullable
          - `geocode` GeocodingResult — recursive
      - `duration_seconds` integer

## Other responses

- `403` — Invalid API key, or feature not available.
- `422` — Validation error.

---

[API](https://skmtc.net/geocod/apis/geocodio.md) · [All operations](https://skmtc.net/geocod/apis/geocodio/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/geocod/geocodio/versions/cfb0f76c8af3/schema)