Distance Matrix API 요청 및 응답

유럽 경제 지역 (EEA) 개발자

소개

Distance Matrix API 요청의 형식은 다음과 같습니다.

https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters

여기서 outputFormat은 다음 값 중 하나일 수 있습니다.

  • json (권장)은 JavaScript 객체 표기법 (JSON)으로 출력을 나타냅니다.
  • xml은 출력을 XML로 나타냅니다.

필수인 매개변수와 선택사항인 매개변수가 있습니다. URL에서와 마찬가지로 모든 매개변수는 앰퍼샌드(&) 문자를 사용하여 구분합니다. 모든 예약된 문자 (예: 더하기 기호 '+')는 URL로 인코딩되어야 합니다. 매개변수 목록과 가능한 값은 아래에 열거되어 있습니다.

필수 매개변수

  • 대상

    이동 거리와 시간을 계산하는 데 사용할 하나 이상의 위치입니다. 대상 매개변수의 옵션은 출처 매개변수의 옵션과 동일합니다.

  • origins

    이동 거리와 시간을 계산하기 위한 시작점입니다. 파이프 문자 (|)로 구분된 하나 이상의 위치를 장소 ID, 주소 또는 위도/경도 좌표 형식으로 제공할 수 있습니다.

    • 장소 ID: 장소 ID를 제공하는 경우 place_id:를 앞에 붙여야 합니다.
    • 주소: 주소를 전달하면 서비스에서 문자열을 지오코딩하고 위도/경도 좌표로 변환하여 거리를 계산합니다. 이 좌표는 Geocoding API에서 반환된 좌표와 다를 수 있습니다(예: 건물의 중심이 아닌 건물 입구).
      참고: 주소 또는 위도/경도 좌표를 사용하는 것보다 장소 ID를 사용하는 것이 좋습니다. 좌표를 사용하면 항상 해당 좌표에 가장 가까운 도로로 포인트가 스냅됩니다. 이 도로가 속성으로 연결되는 진입로가 아닐 수도 있고, 목적지로 빠르고 안전하게 연결되는 도로가 아닐 수도 있습니다. 주소를 사용하면 건물의 입구가 아닌 건물 중심까지의 거리가 제공됩니다.
    • 좌표: 위도/경도 좌표를 전달하면 가장 가까운 도로에 스냅됩니다. 장소 ID를 전달하는 것이 좋습니다. 좌표를 전달하는 경우 위도와 경도 값 사이에 공백이 없어야 합니다.
    • Plus Code는 글로벌 코드 또는 복합 코드로 형식이 지정되어야 합니다. 여기 표시된 대로 Plus Code의 형식을 지정합니다. 더하기 기호는 %2B로 URL 이스케이프 처리되고 공백은 %20으로 URL 이스케이프 처리됩니다.
      • 글로벌 코드는 4자리 지역 코드와 6자 이상의 로컬 코드입니다 (849VCWC8+R9는 849VCWC8%2BR9로 인코딩됨).
      • 복합 코드는 명시적인 위치가 포함된 6자 이상의 로컬 코드입니다 (CWC8+R9 Mountain View, CA, USA는 CWC8%2BR9%20Mountain%20View%20CA%20USA로 인코딩됨).
    • 인코딩된 다중선 인코딩된 다중선 알고리즘을 사용하여 인코딩된 좌표 집합을 제공할 수도 있습니다. 인코딩된 다중선을 사용하면 URL이 훨씬 짧아지므로 원점 포인트가 많은 경우에 특히 유용합니다.
      • 인코딩된 폴리라인에는 enc:이 접두사로 붙고 콜론 :이 뒤에 와야 합니다. 예를 들면 다음과 같습니다. origins=enc:gfo}EtohhU:
      • 파이프 문자 |로 구분된 인코딩된 폴리라인을 여러 개 포함할 수도 있습니다. 예를 들면 다음과 같습니다. 
        origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:

선택적 매개변수

  • arrival_time

    1970년 1월 1일 자정(UTC) 이후 경과된 시간을 초 단위로 나타낸 대중교통 길찾기의 선호 도착 시간을 지정합니다. departure_time 또는 arrival_time 중 하나를 지정할 수 있지만 둘 다 지정할 수는 없습니다. arrival_time는 정수로 지정해야 합니다.

  • 피하기

    특정한 제한을 준수하여 거리가 계산될 수도 있습니다. 제한사항은 avoid 매개변수와 이 매개변수에 대한 인수를 사용하여 표시되며, 이 인수는 피해야 하는 제한사항을 나타냅니다. 다음 제한사항이 지원됩니다.

    • tolls은 경로 계산 시 유료 도로/다리를 제외해야 함을 나타냅니다.
    • highways은 경로 계산 시 고속도로를 피해야 함을 나타냅니다.
    • ferries은 경로 계산 시 페리를 제외해야 함을 나타냅니다.
    • indoor은 경로 계산 시 도보 및 대중교통 경로에 실내 계단을 피해야 함을 나타냅니다.

    제한사항을 avoid 매개변수에 모두 전달하여 유료도로, 고속도로, 페리의 조합을 피하는 경로를 요청할 수 있습니다. 예를 들면 avoid=tolls|highways|ferries입니다.

    참고: 제한사항을 추가해도 제한된 기능이 포함된 경로가 제외되지는 않습니다. 결과가 더 유리한 경로로 편향됩니다.

  • departure_time

    선호하는 출발 시간을 지정합니다. 시간은 1970년 1월 1일 자정(UTC) 이후 경과된 초를 나타내는 정수로 지정할 수 있습니다. 9999-12-31T23:59:59.999999999Z 이후의 departure_time가 지정되면 API는 departure_time를 9999-12-31T23:59:59.999999999Z로 대체합니다. 또는 현재 값을 지정하여 출발 시간을 현재 시간 (가장 가까운 초까지 정확함)으로 설정할 수 있습니다. 출발 시간은 다음 두 경우에 지정될 수 있습니다.

    • 이동 수단이 대중교통인 요청의 경우 departure_time 또는 arrival_time 중 하나를 선택적으로 지정할 수 있습니다. 두 시간이 모두 지정되지 않은 경우 departure_time의 기본값은 현재 시간입니다 (즉, 출발 시간의 기본값은 현재 시간임).
    • 이동 모드가 운전인 요청의 경우 departure_time를 지정하여 교통 상황을 고려하는 경로와 이동 시간(응답 필드: duration_in_traffic)을 수신할 수 있습니다. departure_time은 현재 시간 또는 미래의 특정 시간으로 설정해야 합니다. 과거 시간으로 설정할 수는 없습니다.
    참고: 출발 시간을 지정하지 않으면 도로망 및 평균 시간과 무관한 교통상황을 기반으로 경로 및 소요 시간이 선택됩니다. 지정된 요청의 결과는 도로망의 변화, 평균 교통상황의 업데이트 및 분산된 서비스 특성으로 인해 시간이 지남에 따라 달라질 수도 있습니다. 거의 동일한 경로 간에도 언제든지 또는 수시로 결과가 다를 수도 있습니다.
    참고: mode=driving이 요청당 최대 100개 요소로 제한되는 경우 departure_time을 지정하는 거리 행렬 요청입니다. 출발지 수에 도착지 수를 곱한 값이 요소 수를 정의합니다.

  • language

    결과를 반환할 언어입니다.

    • 지원되는 언어 목록을 참고하세요. Google에서는 지원되는 언어를 자주 업데이트하므로 이 목록에 모든 언어가 포함되지 않을 수도 있습니다.
    • language가 제공되지 않으면 API는 Accept-Language 헤더에 지정된 기본 언어를 사용하려고 시도합니다.
    • API는 사용자와 현지인 모두가 읽을 수 있는 상세 주소를 제공하기 위해 최선을 다합니다. 이 목표를 달성하기 위해 선호하는 언어를 준수하여 필요한 경우 사용자가 읽을 수 있는 스크립트로 음역된 현지 언어의 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
    • 선호하는 언어로 이름을 사용할 수 없는 경우 API는 가장 일치하는 이름을 사용합니다.
    • 기본 언어는 API가 반환하도록 선택한 결과 집합과 반환되는 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 약어를 다르게 해석합니다. 예를 들어 거리 유형의 약어나 한 언어에서는 유효하지만 다른 언어에서는 유효하지 않은 동의어가 있습니다. 예를 들어 utca와 tér은 헝가리어로 거리의 동의어입니다.

  • 모드

    거리와 경로를 계산할 때 사용할 이동 수단을 지정할 수 있습니다. 기본적으로 DRIVING 모드가 사용됩니다. 기본적으로 길찾기는 운전 길찾기로 계산됩니다. 다음과 같은 이동 수단이 지원됩니다.

    • driving (기본값)은 도로망을 사용하는 일반 운전 경로 또는 거리를 나타냅니다.
    • walking은 보행자 전용 도로와 인도를 사용하여 도보 경로 또는 거리를 요청합니다 (해당하는 경우).
    • bicycling은 자전거 전용 도로 및 선호하는 거리를 사용하여 자전거 경로 또는 거리를 요청합니다 (해당하는 경우).
    • transit은 대중교통 경로를 사용하여 경로 또는 거리를 요청합니다 (해당하는 경우). 모드를 대중교통으로 설정한 경우 선택적으로 departure_time 또는 arrival_time를 지정할 수 있습니다. 시간이 지정되지 않은 경우 departure_time의 기본값은 현재 시간입니다 (즉, 출발 시간의 기본값은 현재 시간임). 선택적으로 transit_mode 또는 transit_routing_preference를 포함할 수도 있습니다.
    참고: 도보 및 자전거 경로에 명확한 보행자 또는 자전거 경로가 포함되지 않을 수도 있으므로 이러한 경로에서는 사용자에게 표시해야 하는 반환된 결과에 경고를 반환합니다.
    참고: 대중교통 정보는 데이터 제공업체에서 제공하는 대중교통 정보의 사용 가능 여부에 따라 최대 7일 전 또는 최대 100일 후까지 확인할 수 있습니다. 대중교통 시간표는 자주 변경되며, 이용 가능한 대중교통 여정은 시간이 지남에 따라 변경될 수 있습니다. 또한 먼 미래의 예측에 대해 일관된 결과를 제공한다는 보장은 없습니다.

  • 지역

    ccTLD ('최상위 도메인') 2자리 값으로 지정되는 지역 코드입니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)이지만 ISO 3166-1 코드는 'gb' (기술적으로 '영국' 법인의 경우)입니다.

  • traffic_model

    교통 상황에서 시간을 계산할 때 사용할 가정을 지정합니다. 이 설정은 응답의 duration_in_traffic 필드에 반환되는 값에 영향을 미칩니다. 이 필드에는 이전 평균을 기반으로 한 예상 이동 시간이 포함됩니다. traffic_model 매개변수는 요청에 departure_time이 포함된 운전 경로에만 지정할 수 있습니다. 이 매개변수에 사용 가능한 값은 다음과 같습니다.

    • best_guess (기본값)는 이전 교통상황과 실시간 교통정보에 대해 알려진 정보를 기준으로 할 때 반환된 duration_in_traffic이 최적의 예상 이동 시간임을 나타냅니다. departure_time이 지금에 가까울수록 실시간 교통정보가 더 중요합니다.
    • pessimistic은 반환된 duration_in_traffic이 대부분의 날에 실제 이동 시간보다 더 길다는 것을 나타내지만 특히 교통상황이 나쁜 날은 이 값을 초과할 수도 있습니다.
    • optimistic은 반환된 duration_in_traffic이 대부분의 날에 실제 이동 시간보다 더 짧다는 것을 나타냅니다. 다만 교통상황이 특별히 좋은 날은 이 값보다 빠를 수도 있습니다.

    best_guess의 기본값은 대부분의 사용 사례에 가장 유용한 예측을 제공합니다. best_guess 예측 모델이 실시간 교통정보를 통합하는 방식 때문에 best_guess 이동 시간 예측이 optimistic보다 짧거나 pessimistic보다 길 수 있습니다.

  • transit_mode

    하나 이상의 선호하는 대중교통 수단을 지정합니다. 이 매개변수는 대중교통 경로에만 지정할 수 있습니다. 이 매개변수는 다음 인수를 지원합니다.

    • bus은 경로 계산 시 버스 이동을 우선적으로 고려해야 함을 나타냅니다.
    • subway은 경로 계산 시 지하철 이동을 우선적으로 고려해야 함을 나타냅니다.
    • train은 경로 계산 시 기차 이동을 우선적으로 고려해야 함을 나타냅니다.
    • tram은 경로 계산 시 트램 및 경전철 이동을 우선적으로 고려해야 함을 나타냅니다.
    • rail은 경로 계산 시 기차, 트램, 경전철 및 지하철 이동을 우선적으로 고려해야 함을 나타냅니다. 이는 transit_mode=train|tram|subway와 동일합니다.

  • transit_routing_preference

    대중교통 경로의 환경설정을 지정합니다. 이 매개변수를 사용하면 API에서 선택한 기본 최적 경로를 수락하는 대신 반환되는 옵션에 편중할 수 있습니다. 이 매개변수는 대중교통 경로에만 지정할 수 있습니다. 매개변수는 다음과 같은 인수를 지원합니다.

    • less_walking은 경로 계산 시 도보 이동을 제한해야 함을 나타냅니다.
    • fewer_transfers은 경로 계산 시 환승 횟수를 제한해야 함을 나타냅니다.

  • 개

    결과를 표시할 때 사용할 단위 시스템을 지정합니다.

    참고: 이 단위 체계 설정은 거리 필드 내에 표시되는 텍스트에만 영향을 미칩니다. 거리 필드에는 항상 미터 단위로 표현되는 값도 포함됩니다.

요청 예시

이 예에서는 위도/경도 좌표를 사용하여 대상 좌표를 지정합니다.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

이 예에서는 플러스 코드를 사용하여 목적지 좌표를 지정합니다.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

다음 예는 인코딩된 폴리라인을 사용하여 동일한 요청을 보여줍니다.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

교통 정보

교통정보는 다음 사항이 모두 적용되는 경우에 사용됩니다 (Distance Matrix 응답에서 duration_in_traffic 필드를 수신하는 데 필요한 조건입니다).

  • 이동 mode 매개변수가 driving이거나 지정되지 않았습니다(driving이 기본 이동 모드).
  • 요청에 유효한 departure_time 매개변수가 포함되어 있습니다. departure_time은 현재 시간 또는 미래의 특정 시간으로 설정할 수 있습니다. 과거 시간으로 설정할 수는 없습니다.

원하는 경우 요청에 traffic_model 매개변수를 포함하여 트래픽 시간을 계산할 때 사용할 가정을 지정할 수 있습니다.

다음 URL은 매사추세츠주 보스턴 또는 매사추세츠주 찰스타운과 매사추세츠주 렉싱턴 및 매사추세츠주 콩코드 간의 운전 거리의 거리 행렬 요청을 시작합니다. 요청에는 출발 시간이 포함되어 거리 행렬 응답에서 duration_in_traffic 필드를 반환하기 위한 모든 요구사항을 충족합니다.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

JSON

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins

위치 수정자

위치 수정자를 사용하여 운전자가 특정 위치에 어떻게 접근해야 하는지를 나타낼 수 있습니다. side_of_road 수정자를 사용하여 사용할 도로 측면을 지정하거나, 이동의 올바른 방향을 나타내는 방향을 지정하면 됩니다.

계산된 경로가 도로의 특정 쪽을 통과해야 한다고 지정

위치를 지정할 때 side_of_road: 접두사를 사용하여 계산된 경로가 경유지가 치우쳐 있는 도로 쪽으로 지나가도록 요청할 수 있습니다. 예를 들어 이 요청은 차량이 경유지가 편향된 도로변에 도착하도록 긴 경로의 거리를 반환합니다.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

인코딩된 다중선과 함께 side_of_road:을 사용하면 조정자가 다중선을 따라 모든 위치에 적용됩니다. 예를 들어 이 요청의 두 대상 모두 다음 매개변수를 사용합니다.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

side_of_road: 수정자는 다음 제한사항과 함께만 사용할 수 있습니다.

  • 이동 mode 매개변수가 driving이거나 지정되지 않았습니다 (driving이 기본 이동 모드).

계산된 경로에 특정 방향이 있어야 한다고 지정

위치를 지정할 때 계산된 경로가 특정 방향으로 해당 위치를 통과하도록 요청할 수 있습니다. 이 헤더는 heading=X: 접두사로 지정됩니다. 여기서 X는 0 (포함)에서 360(제외) 사이의 정수 각도 값입니다. 방향 0은 북쪽을 나타내고 90은 동쪽을 나타내며 시계 방향으로 계속됩니다. 예를 들어 이 요청에서 계산된 경로는 출발지에서 동쪽으로 이동한 후 U턴합니다.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

heading=X: 수정자는 다음 제한사항과 함께만 사용할 수 있습니다.

  • 이동 mode 매개변수가 driving 또는 bicycling이거나 지정되지 않았습니다 (driving이 기본 이동 모드).
  • side_of_road 수정자가 동일한 위치에 지정되지 않았습니다.
  • 위치는 위도/경도 값으로 지정됩니다. 주소, 장소 ID 또는 인코딩된 폴리라인과 함께 heading를 사용할 수 없습니다.

거리 행렬 요청 및 응답

다음은 캐나다 브리티시컬럼비아주 밴쿠버와 미국 워싱턴주 시애틀에서 미국 캘리포니아주 샌프란시스코와 캐나다 브리티시컬럼비아주 빅토리아까지의 거리와 시간을 요청하는 샘플 HTTP 요청입니다.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

이 요청은 2개의 출발지와 2개의 목적지를 곱한 다음 네 가지 요소를 반환합니다.

벤쿠버 - 샌프란시스코 벤쿠버 - 빅토리아
시애틀 - 샌프란시스코 시애틀 - 빅토리아

결과는 행으로 반환되며 각 행에는 각 목적지와 페어링된 하나의 출발지가 포함됩니다.

JSON

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km

DistanceMatrixResponse

필드 필수 유형 설명
required Array<string>

원래 요청에서 API가 반환한 주소 배열입니다. origin_addresses와 마찬가지로 적절한 경우 현지화됩니다. 이 콘텐츠는 있는 그대로 읽어야 합니다. 형식이 지정된 주소를 프로그래매틱 방식으로 파싱하지 마세요.

required Array<string>

원래 요청에서 API가 반환한 주소 배열입니다. 이러한 값은 지오코더에 의해 형식이 지정되고 요청과 함께 전달된 언어 매개변수에 따라 현지화됩니다. 이 콘텐츠는 있는 그대로 읽어야 합니다. 형식이 지정된 주소를 프로그래매틱 방식으로 파싱하지 마세요.

required Array<DistanceMatrixRow>

요소의 배열로, 각 요소에는 status, duration, distance 요소가 포함됩니다.

자세한 내용은 DistanceMatrixRow를 참고하세요.

required DistanceMatrixStatus

요청의 상태를 포함하며 요청이 실패한 이유를 추적하는 데 도움이 되는 디버깅 정보가 포함될 수도 있습니다.

자세한 내용은 DistanceMatrixStatus를 참고하세요.

선택사항 문자열

요청이 처리되는 동안 발생한 오류의 사람이 읽을 수 있는 텍스트가 포함된 문자열입니다.

DistanceMatrixStatus

서비스에서 반환된 상태 코드입니다.

  • OK는 응답에 유효한 결과가 포함되어 있음을 나타냅니다.
  • INVALID_REQUEST는 제공된 요청이 잘못되었음을 나타냅니다.
  • MAX_ELEMENTS_EXCEEDED는 출발지와 목적지 쌍이 쿼리당 한도를 초과함을 나타냅니다.
  • MAX_DIMENSIONS_EXCEEDED는 출발지 또는 목적지 수가 쿼리당 한도를 초과함을 나타냅니다.
  • OVER_DAILY_LIMIT는 다음 중 하나를 나타냅니다.
    • API 키가 누락되었거나 잘못되었습니다.
    • 계정에 결제가 사용 설정되어 있지 않습니다.
    • 자체 적용되는 사용량 한도를 초과했습니다.
    • 제공된 결제 수단이 더 이상 유효하지 않습니다 (예: 신용카드가 만료됨).
  • OVER_QUERY_LIMIT은 서비스가 허용된 기간 내에 애플리케이션으로부터 너무 많은 요청을 수신했다는 것을 나타냅니다.
  • REQUEST_DENIED는 서비스에서 애플리케이션의 거리 행렬 서비스 사용을 거부했음을 나타냅니다.
  • UNKNOWN_ERROR는 서버 오류로 인해 거리 행렬 요청을 처리하지 못했음을 나타냅니다. 다시 시도하면 요청이 성공할 수도 있습니다.

DistanceMatrixRow

필드 필수 유형 설명
required Array<DistanceMatrixElement>

Distance Matrix API가 결과를 반환하면 JSON 행 배열 내에 결과를 배치합니다. 결과가 반환되지 않더라도 (예: 출발지 및/또는 목적지가 존재하지 않는 경우) 빈 배열이 반환됩니다.

행은 요청의 origin 매개변수 값에 따라 정렬됩니다. 각 행은 출발지에 해당하고 해당 행 내의 각 요소는 출발지와 목적지 값의 쌍에 해당합니다.

각 행 배열에는 하나 이상의 요소 항목이 포함되며, 요소 항목에는 단일 출발지-목적지 쌍에 관한 정보가 포함됩니다.

자세한 내용은 DistanceMatrixElement를 참고하세요.

DistanceMatrixElement

필드 필수 유형 설명
required DistanceMatrixElementStatus

요소의 상태입니다.

자세한 내용은 DistanceMatrixElementStatus를 참고하세요.

선택사항 TextValueObject

이 경로의 총거리로, 미터 (값) 및 텍스트로 표시됩니다. 텍스트 값은 원래 요청의 단위 매개변수 또는 출발지 지역에 지정된 단위 체계를 사용합니다.

자세한 내용은 TextValueObject를 참고하세요.

선택사항 TextValueObject

이 경로를 이동하는 데 걸리는 시간으로 초 (값 필드) 및 텍스트로 표시됩니다. 텍스트 표현은 쿼리의 언어 매개변수에 따라 현지화됩니다.

자세한 내용은 TextValueObject를 참고하세요.

선택사항 TextValueObject

현재 및 과거 교통상황을 기반으로 이 경로를 이동하는 데 걸리는 시간입니다. 반환된 값이 낙관적인 값인지, 비관적인 값인지, 최적의 추정치인지 요청하는 데 사용할 수 있는 옵션은 traffic_model 요청 매개변수를 참고하세요. 재생 시간은 초 (값 필드)와 텍스트로 표현됩니다. 텍스트 표현은 쿼리의 언어 매개변수에 따라 현지화됩니다. 트래픽의 기간은 다음 조건이 모두 충족되는 경우에만 반환됩니다.

  • 요청에 departure_time 매개변수가 포함되어 있습니다.
  • 요청된 경로에 대해 교통상황이 제공됩니다.
  • 모드 매개변수가 driving으로 설정됩니다.

자세한 내용은 TextValueObject를 참고하세요.

선택사항 요금

제공된 경우 이 경로의 총 요금 (즉, 총 티켓 비용)이 포함됩니다. 이 속성은 대중교통 요청 및 요금 정보를 사용할 수 있는 대중교통 제공업체의 경우에만 반환됩니다.

자세한 내용은 요금을 참고하세요.

요금

경로의 총 요금입니다.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}
필드 필수 유형 설명
required 문자열

금액이 표시되는 통화를 나타내는 ISO 4217 통화 코드

text

required 문자열

요청한 언어로 형식이 지정된 전체 요금액.
required 숫자

총 요금액(지정된 통화로 표시됨)

DistanceMatrixElementStatus

  • OK는 응답에 유효한 결과가 포함되어 있음을 나타냅니다.
  • NOT_FOUND는 이 출발지 및 목적지 쌍을 지오코딩하지 못했음을 나타냅니다.
  • ZERO_RESULTS는 출발지와 목적지 사이에서 경로를 찾지 못했음을 나타냅니다.
  • MAX_ROUTE_LENGTH_EXCEEDED는 요청된 경로가 너무 길어서 처리할 수 없음을 나타냅니다.

TextValueObject

숫자 값과 형식이 지정된 텍스트 표현이 포함된 객체입니다.

필드 필수 유형 설명

text

required 문자열

문자열 값입니다.
required 숫자

숫자 값입니다.