거리 행렬 서비스

개요

Google의 거리 행렬 서비스는 주어진 이동 수단을 사용하여 여러 출발지와 목적지 사이의 이동 거리와 이동 시간을 계산합니다.

이 서비스는 자세한 경로 정보를 반환하지 않습니다. 다중선 및 텍스트 경로를 비롯한 경로 정보는 원하는 단일 출발지 및 목적지를 경로 서비스에 전달하여 가져올 수 있습니다.

시작하기

Maps JavaScript API에서 거리 행렬 서비스를 사용하려면 먼저 Google Cloud 콘솔에서 Maps JavaScript API를 위해 설정한 것과 동일한 프로젝트에 Distance Matrix API를 사용 설정해야 합니다.

사용 설정된 API의 목록을 보려면 다음 단계를 따르세요.

1. Google Cloud 콘솔로 이동합니다.
2. 프로젝트 선택 버튼을 클릭한 후 Maps JavaScript API를 위해 설정한 것과 동일한 프로젝트를 선택하고 열기를 클릭합니다.
3. 대시보드의 API 목록에서 Distance Matrix API를 찾습니다.
4. 목록에 API가 표시되면 완료된 것입니다. API가 표시되지 않으면 API를 사용 설정하세요.
   1. 페이지 상단에서 API 사용 설정을 선택하여 라이브러리 탭을 표시합니다. 또는 왼쪽 사이드 메뉴에서 라이브러리를 선택합니다.
   2. Distance Matrix API를 검색한 후 결과 목록에서 선택합니다.
   3. 사용 설정을 선택합니다. 과정이 완료되면 Distance Matrix API가 대시보드의 API 목록에 표시됩니다.

가격 정보 및 정책

가격 정보

2018년 7월 16일부터 지도, 경로, 장소에 사용한 만큼만 지불하는 새로운 요금제가 도입되었습니다. JavaScript 거리 행렬 서비스 사용의 새로운 가격 및 사용량 한도에 대해 자세히 알아보려면 Distance Matrix API의 사용량 및 결제를 참고하세요.

참고: 거리 행렬 서비스에 전송되는 각 쿼리는 허용되는 요소의 수에 의해 제한됩니다. 여기서 요소의 수는 출발지의 수에 목적지의 수를 곱한 값으로 정의됩니다.

정책

거리 행렬 서비스는 Distance Matrix API에 대해 설명된 정책에 따라 사용해야 합니다.

거리 행렬 요청

Google 지도 API는 외부 서버를 호출해야 하므로 거리 행렬 서비스 액세스는 비동기식입니다. 따라서 결과를 처리하려면 요청 완료 시 실행할 콜백 메서드를 전달해야 합니다.

google.maps.DistanceMatrixService 생성자 객체를 통해 코드 내의 거리 행렬 서비스에 액세스합니다. DistanceMatrixService.getDistanceMatrix() 메서드는 거리 행렬 서비스 요청을 시작하고 이를 출발지, 목적지, 이동 수단을 포함한 DistanceMatrixRequest 객체 리터럴 및 응답 수신 시 실행할 콜백 메서드에 전달합니다.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

예 보기

DistanceMatrixRequest에는 다음과 같은 필드가 포함됩니다.

• origins(필수) - 거리와 시간을 계산할 때 출발점이 되는 하나 이상의 주소 문자열, google.maps.LatLng 객체 또는 장소 객체가 포함된 배열
• destinations(필수) - 거리와 시간 계산할 때 도착점이 되는 하나 이상의 주소 문자열, google.maps.LatLng 객체 또는 장소 객체가 포함된 배열
• travelMode(선택사항) - 경로를 계산할 때 사용할 이동 수단. 이동 수단에 관한 섹션을 참고하세요.
• transitOptions(선택사항) - travelMode가 TRANSIT인 요청에만 적용되는 옵션입니다. 유효한 값은 대중교통 옵션에 관한 섹션에 설명되어 있습니다.
• drivingOptions(선택사항)는 travelMode가 DRIVING인 요청에만 적용되는 값을 지정합니다. 유효한 값은 운전 옵션에 관한 섹션에 설명되어 있습니다.
• unitSystem(선택사항) - 거리를 표시할 때 사용할 단위 체계입니다. 허용되는 값은 다음과 같습니다.
  • google.maps.UnitSystem.METRIC(기본값)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways(선택사항) - true인 경우 가능하면 고속도로를 제외하여 출발지와 목적지 사이의 경로가 계산됩니다.
• avoidTolls(선택사항) - true인 경우 가능하면 무료 도로를 사용하는 지점 간의 경로가 계산됩니다.

이동 수단

시간과 거리를 계산할 때 사용할 이동 수단을 지정할 수 있습니다. 현재 다음과 같은 이동 수단이 지원됩니다.

• BICYCLING은 자전거 전용 도로 및 선호하는 거리를 경유하는 자전거 경로를 요청합니다(현재 미국과 캐나다 일부 도시에서만 사용할 수 있음).
• DRIVING(기본값)은 도로망을 사용하는 일반 운전 경로를 나타냅니다.
• TRANSIT은 대중교통 경로를 경유하는 경로를 요청합니다. 이 옵션은 요청에 API 키가 포함된 경우에만 지정할 수 있습니다. 이 유형의 요청에 사용할 수 있는 옵션은 대중교통 옵션 섹션을 참고하세요.
• WALKING은 보행자 전용 도로와 인도를 경유하는 도보 경로를 요청합니다(해당하는 경우).

대중교통 옵션

대중교통 서비스는 현재 '실험' 중입니다. 이 단계에서는 API 남용을 막기 위해 속도 제한이 적용됩니다. 나중에는 타당한 API 사용량을 기반으로 지도 로드당 총 쿼리 수에 한도가 적용될 예정입니다.

거리 행렬 요청에 사용할 수 있는 옵션은 이동 수단에 따라 다릅니다. 대중교통 요청에서 avoidHighways 및 avoidTolls 옵션은 무시됩니다. 대중교통에 고유한 경로 옵션은 TransitOptions 객체 리터럴을 통해 지정할 수 있습니다.

대중교통 요청은 시간에 민감합니다. 미래의 시간에 해당하는 계산 결과만 반환됩니다.

TransitOptions 객체 리터럴에는 다음 필드가 포함됩니다.

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

다음은 이러한 필드에 대한 설명입니다.

• arrivalTime(선택사항)은 원하는 도착 시간을 Date 객체로 지정합니다. 도착 시간이 지정되면 출발 시간은 무시됩니다.
• departureTime(선택사항)은 원하는 출발 시간을 Date 객체로 지정합니다. arrivalTime이 지정되면 departureTime은 무시됩니다. departureTime 및 arrivalTime에 값이 지정되지 않으면 '지금'(현재 시간)이 기본값이 됩니다.
• modes(선택사항)는 하나 이상의 TransitMode 객체 리터럴이 포함된 배열입니다. 이 필드는 요청에 API 키가 포함된 경우에만 포함할 수 있습니다. 각 TransitMode는 선호하는 대중교통 수단을 지정합니다. 다음과 같은 값이 허용됩니다.
  • BUS는 경로 계산 시 버스 이동을 우선적으로 고려해야 함을 나타냅니다.
  • RAIL은 경로 계산 시 기차, 트램, 경전철 및 지하철 이동을 우선적으로 고려해야 함을 나타냅니다.
  • SUBWAY는 경로 계산 시 지하철 이동을 우선적으로 고려해야 함을 나타냅니다.
  • TRAIN은 경로 계산 시 기차 이동을 우선적으로 고려해야 함을 나타냅니다.
  • TRAM은 경로 계산 시 트램 이동을 우선적으로 고려해야 함을 나타냅니다.
• routingPreference(선택사항)는 대중교통 경로의 환경설정을 지정합니다. 이 옵션을 사용하면 API에서 선택한 기본 최적 경로를 수락하는 대신 반환되는 옵션에 편중할 수 있습니다. 이 필드는 요청에 API 키가 포함된 경우에만 지정할 수 있습니다. 다음과 같은 값이 허용됩니다.
  • FEWER_TRANSFERS는 경로 계산 시 환승 횟수를 제한해야 함을 나타냅니다.
  • LESS_WALKING은 경로 계산 시 도보 이동을 제한해야 함을 나타냅니다.

운전 옵션

drivingOptions 객체를 사용하면 예상되는 교통상황을 고려하여 최적 경로를 계산하기 위한 출발 시간을 지정할 수 있습니다. 이전 교통상황과 실시간 교통정보를 기반으로 비관적, 낙관적 또는 최적의 예상 이동 시간을 계산하도록 지정할 수도 있습니다.

drivingOptions 객체에는 다음 필드가 포함됩니다.

{
  departureTime: Date,
  trafficModel: TrafficModel
}

다음은 이러한 필드에 대한 설명입니다.

• departureTime(drivingOptions 객체 리터럴이 유효하기 위해 필요함)은 원하는 출발 시간을 Date 객체로 지정합니다. 이 값은 현재 시간 또는 미래의 특정 시간으로 설정해야 합니다. 과거 시간으로 설정할 수는 없습니다. (API는 모든 시간대에서 일관되게 처리할 수 있도록 모든 날짜를 UTC로 변환합니다.) 요청에 departureTime을 포함하면 API에서 그 시점에 예상되는 교통상황을 고려하여 최적 경로를 반환하고 예상 이동 시간(duration_in_traffic)을 응답에 포함합니다. 출발 시간을 지정하지 않으면(즉, 요청에 drivingOptions가 포함되지 않으면) 교통상황을 고려하지 않은 대체로 양호한 경로가 반환됩니다.
• trafficModel(선택사항)은 이동 시간을 계산할 때 사용할 가정을 지정합니다. 이 설정은 응답의 duration_in_traffic 필드에 반환되는 값에 영향을 미칩니다. 이 필드에는 이전 평균을 기반으로 한 예상 이동 시간이 포함됩니다. 기본값은 best_guess입니다. 다음과 같은 값이 허용됩니다.
  • bestguess(기본값)는 알려진 이전 교통상황과 실시간 교통정보를 고려할 때 반환된 duration_in_traffic이 최적의 예상 이동 시간임을 나타냅니다. departureTime이 지금에 가까울수록 실시간 교통정보가 더 중요합니다.
  • pessimistic은 대부분의 날에는 반환된 duration_in_traffic이 실제 이동 시간보다 더 길다는 것을 나타내지만 특히 교통상황이 나쁜 날은 이 값을 초과할 수도 있습니다.
  • optimistic은 대부분의 날에는 반환된 duration_in_traffic이 실제 이동 시간보다 더 짧다는 것을 나타내지만 특히 교통상황이 좋은 이 값보다 빠를 수도 있습니다.

다음은 출발 시간과 교통정보 모델이 포함된 운전 경로에 대한 DistanceMatrixRequest 샘플입니다.

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

거리 행렬 응답

거리 행렬 서비스가 성공적으로 호출되면 DistanceMatrixResponse 객체 및 DistanceMatrixStatus 객체가 반환됩니다. 이러한 객체는 요청에서 지정한 콜백 함수에 전달됩니다.

DistanceMatrixResponse 객체에는 경로를 계산할 수 있는 각 출발지/목적지 쌍에 대한 거리 및 소요 시간 정보가 포함됩니다.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

거리 행렬 결과

다음은 응답에서 지원되는 필드에 대한 설명입니다.

• originAddresses는 거리 행렬 요청의 origins 필드에 전달된 위치가 포함된 배열입니다. 주소는 지오코더가 지정한 형식으로 반환됩니다.
• destinationAddresses는 지오코더가 반환한 형식으로 destinations 필드에 전달된 위치가 포함된 배열입니다.
• rows는 DistanceMatrixResponseRow 객체의 배열로 각 행이 출발지에 해당합니다.
• elements는 rows의 하위 요소로 행의 출발지와 각 목적지의 쌍에 해당합니다. 여기에는 각 출발지/도착지 쌍에 대한 상태, 소요 시간, 거리, 요금 정보(해당하는 경우)가 포함됩니다.
• 각 element에는 다음과 같은 필드가 포함됩니다.
  • status: 가능한 상태 코드의 목록은 상태 코드를 참고하세요.
  • duration: 이 경로를 이동하는 데 걸리는 시간으로 초(value 필드) 및 text로 표시됩니다. 텍스트 값은 요청에 지정된 unitSystem에 따라(또는 환경설정이 제공되지 않은 경우 미터 단위로) 형식이 지정됩니다.
  • duration_in_traffic: 현재 교통상황을 고려하여 이 경로를 이동하는 데 걸리는 시간으로 초(value 필드) 및 text로 표시됩니다. 텍스트 값은 요청에 지정된 unitSystem에 따라(또는 환경설정이 제공되지 않은 경우 미터 단위로) 형식이 지정됩니다. 이 duration_in_traffic는 교통정보 데이터를 사용할 수 있는 경우에만 반환되며 mode가 driving로 설정됨 departureTime는 distanceMatrixOptions 필드가 포함됩니다.
  • distance: 이 경로의 총거리로 초(value) 및 text로 표시됩니다. 텍스트 값은 요청에 지정된 unitSystem에 따라(또는 환경설정이 제공되지 않은 경우 미터 단위로) 형식이 지정됩니다.
  • fare: 이 경로상의 총요금(즉 총 티켓 비용)이 포함됩니다. 이 속성은 대중교통 요청 및 요금 정보를 사용할 수 있는 대중교통 제공업체의 경우에만 반환됩니다. 이 정보에는 다음과 같은 항목이 포함됩니다.
    • currency: 금액이 표시되는 통화를 나타내는 ISO 4217 통화 코드
    • value: 총 요금액(위에 지정된 통화로 표시됨)

상태 코드

거리 행렬 응답에는 응답 전체의 상태 코드와 각 요소의 상태가 포함됩니다.

응답 상태 코드

DistanceMatrixResponse에 적용되는 상태 코드는 DistanceMatrixStatus 객체에 전달되며 다음 항목을 포함합니다.

• OK - 요청이 유효합니다. 출발지와 목적지 사이에서 경로를 찾지 못한 경우에도 이 상태가 반환될 수 있습니다. 요소 수준 상태 정보에 대해서는 요소 상태 코드를 참고하세요.
• INVALID_REQUEST - 제공된 요청이 유효하지 않습니다. 보통 요청된 필드가 누락되어 발생합니다. 위의 지원되는 필드 목록을 참고하세요.
• MAX_ELEMENTS_EXCEEDED - 출발지와 목적지 쌍이 쿼리당 한도를 초과합니다.
• MAX_DIMENSIONS_EXCEEDED - 요청에 25개 이상의 출발지 또는 25개 이상의 목적지가 포함되어 있습니다.
• OVER_QUERY_LIMIT - 애플리케이션에서 허용된 기간 내에 너무 많은 요소를 요청했습니다. 적당한 시간이 지난 후에 다시 시도하면 요청이 성공합니다.
• REQUEST_DENIED - 서비스에서 웹페이지의 거리 행렬 서비스 사용을 거부했습니다.
• UNKNOWN_ERROR - 서버 오류로 인해 거리 행렬 요청을 처리하지 못했습니다. 다시 시도하면 요청이 성공할 수도 있습니다.

요소 상태 코드

다음 상태 코드가 특정 DistanceMatrixElement 객체에 적용됩니다.

• NOT_FOUND - 이 출발지 및 목적지 쌍을 지오코딩하지 못했습니다.
• OK - 응답에 유효한 결과가 포함되어 있습니다.
• ZERO_RESULTS - 출발지와 목적지 사이에서 경로를 찾지 못했습니다.

결과 파싱

DistanceMatrixResponse 객체에는 요청에 전달된 출발지당 한 개의 row가 포함됩니다. 각 행에는 각 해당 출발지와 제공된 목적지 쌍에 대한 element 필드가 포함됩니다.

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}