모든 준비를 마쳤습니다!

개발을 시작하려면 개발자 문서로 이동하세요.

Google Maps JavaScript API 활성화

개발을 시작하기 위해 Google Developers Console에서 우선적으로 해야 할 일을 몇 가지 소개하겠습니다.

  1. 프로젝트 생성 또는 선택
  2. Google Maps JavaScript API 및 관련 서비스 활성화
  3. 적합한 키 생성
계속

거리 행렬 서비스

개요

Google의 거리 행렬 서비스는 주어진 이동 모드에서 여러 출발지와 목적지 사이의 이동 거리와 여행 기간을 계산합니다.

이 서비스는 상세 경로 정보를 반환하지 않습니다. 폴리라인과 텍스트 길찾기를 포함한 경로 정보는 길찾기 서비스에 원하는 단일 출발지와 목적지를 전달하여 얻을 수 있습니다.

시작하기

Google Maps JavaScript API에서 거리 행렬 서비스를 사용하려면 먼저 Google Maps JavaScript API에 대해 설정한 동일한 프로젝트의 Google API Console에서 Google Maps Distance Matrix API를 활성화해야 합니다.

활성화된 API 목록을 보려면:

  1. Google API Console로 이동합니다.
  2. Select a project 버튼을 클릭한 다음 Google Maps JavaScript API에 대해 설정한 동일한 프로젝트를 선택하고 Open을 클릭합니다.
  3. Dashboard의 API 목록에서 Google Maps Distance Matrix API를 찾습니다.
  4. 목록에 API가 표시되면 모두 완벽한 상태입니다. API가 표시되지 않으면 활성화합니다.
    1. 페이지 상단에서 ENABLE API를 선택하여 Library 탭을 표시합니다. 또는 왼쪽 메뉴에서 Library를 선택합니다.
    2. Google Maps Distance Matrix API를 검색한 다음, 결과 목록에서 선택합니다.
    3. ENABLE을 선택합니다. 프로세스가 완료되면 Google Maps Distance Matrix APIDashboard의 API 목록에 나타납니다.

사용 제한 및 정책

할당량

거리 행렬 서비스에는 다음과 같은 사용 제한이 적용됩니다.

참고: 거리 행렬 서비스로 전송되는 각 쿼리는 허용된 요소 수로 제한되며, 여기에서 출발지 수에 목적지 수를 곱하면 요소 수가 됩니다.

기본 플랜에서 거리 행렬 서비스 사용

  • 클라이언트측 쿼리와 서버측 쿼리의 합계로 계산된 하루2,500개의 요소가 무료로 제공됩니다. enable billing를 통해 추가 요소 1,000개당 0.50달러가 청구되는 더 많은 일일 할당량에 액세스할 수 있습니다(일일 최대 요소: 100,000개).
  • 요청당 최대 25개 출발지 또는 25개 목적지.
  • 요청당 최대 100개 요소.
  • 초당 최대 100개의 요소가 허용되며, 클라이언트측과 서버측 쿼리의 합계로 계산합니다.

프리미엄 플랜에서 거리 행렬 서비스 사용

  • 24시간당 100,000개 요청의 공유 일일 무료 할당량, 연간 구매의 Maps API 크레딧에 적용되는 추가적인 요청 .
  • 요청당 최대 25개 출발지 또는 25개 목적지.
  • 요청당 최대 625개 요소. 참고: mode=driving이 초당 100개 요소로 제한될 경우 옵션 매개변수 departure_time을 사용하여 요청합니다.
  • 프로젝트별 초당 무제한개의 클라이언트측 요소. 서버측 API는 초당 1,000개의 요소로 제한됩니다.

동일한 프로젝트를 공유하는 사용자 수에 상관없이 사용자 세션당 적용되는 속도 제한입니다.

세션당 속도 제한은 일괄 요청에 대해 클라이언트측 서비스 사용을 차단합니다. 일괄 요청의 경우 Google Maps Distance Matrix API 웹 서비스를 사용하세요.

정책

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

거리 행렬 요청

Google Maps 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.
}

예시 보기(distance-matrix.html)

DistanceMatrixRequest는 다음과 같은 필드를 포함합니다.

  • origins(필수) — 하나 이상의 주소 문자열, google.maps.LatLng 객체 또는 google.maps.Place 객체를 포함하는 배열로, 이 값에서부터 거리와 시간을 계산합니다.
  • destinations(필수) — 하나 이상의 주소 문자열, google.maps.LatLng 객체 또는 google.maps.Place 객체를 포함하는 배열로, 이 값까지의 거리와 시간을 계산합니다.
  • travelMode(선택 항목) — 찾아가는 길을 계산할 때 사용할 이동 모드. 이동 모드의 섹션을 참조하세요.
  • transitOptions(선택 항목) — travelModeTRANSIT인 요청에만 적용되는 옵션. 유효한 값은 아래 대중교통 옵션 섹션에 설명되어 있습니다.
  • drivingOptions(선택 항목)는 travelModeDRIVING인 요청에만 적용되는 값을 지정합니다. 유효한 값은 아래 자동차 옵션 섹션에 설명되어 있습니다.
  • unitSystem(선택 항목) — 거리 표시에 사용할 단위 체계. 허용되는 값:
    • google.maps.UnitSystem.METRIC(기본값)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways(선택 항목) — true이면, 출발지와 목적지 사이의 경로가 가능하면 고속도로를 피하도록 계산됩니다.
  • avoidTolls(선택 항목) — true이면 두 지점 사이를 찾아가는 길이 가능하면 무료 경로를 사용하도록 계산됩니다.

이동 모드

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

  • BICYCLING은 자전거 경로 및 선호하는 거리를 경유하는 자전거 길찾기를 요청합니다(현재 미국과 캐나다 일부 도시에만 제공됨).
  • DRIVING(기본값)은 도로망을 사용하는 표준 자동차 길찾기를 나타냅니다.
  • TRANSIT은 대중교통 경로를 경유하는 길찾기를 요청합니다. 이 옵션은 요청에 API 키가 포함된 경우에만 지정될 수 있습니다. 이 요청 유형에서 이용 가능한 옵션은 대중교통 옵션의 섹션을 참조하세요.
  • WALKING은 보행자 경로 및 인도(있는 경우)를 경유하는 도보 길찾기를 요청합니다.

대중교통 옵션

대중교통 서비스는 현재 '실험' 단계입니다. 이 단계에서는 API 악용을 막기 위해 속도 제한을 적용합니다. 최종적으로는 API의 공정한 사용에 기초하여 지도 로드 1회당 총 쿼리에 상한을 적용할 것입니다.

거리 행렬에서 이용 가능한 옵션은 이동 모드별로 다양합니다. 대중교통 요청에서 avoidHighwaysavoidTolls 옵션은 무시됩니다. TransitOptions 객체 리터럴을 통해 대중교통별 경로 옵션을 지정할 수 있습니다.

대중교통 요청은 시간에 민감합니다. 계산 값은 미래의 시간에 대해서만 반환됩니다.

TransitOptions 객체 리터럴은 다음 필드를 포함합니다.

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

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

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

자동차 옵션

DrivingOptions 객체를 통해 자동차 노선의 경로 옵션을 지정할 수 있습니다. drivingOptions 필드를 DistanceMatrixRequest에 포함하려면 API를 로드할 때 Google Maps API 프리미엄 플랜 클라이언트 ID를 제공해야 합니다.

DrivingOptions 객체는 다음 필드를 포함합니다.

{
  departureTime: Date,
  trafficModel: TrafficModel
}

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

  • departureTime(drivingOptions 객체 리터럴이 유효하려면 필수)는 원하는 출발 시간을 Date 객체로 지정합니다. 이 값은 현재 시간 또는 미래의 특정 시간으로 설정되어야 합니다. 이 시간은 과거가 될 수 없습니다. (API는 모든 날짜를 UTC로 변환하여 모든 시간대에서 일관적인 처리를 보장합니다.) Google Maps API 프리미엄 플랜 고객의 경우, 요청에 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 필드에 전달된 위치를 포함하는 배열입니다. 이 주소는 지오코더가 지정한 형식으로 반환됩니다.
  • destinationAddressesdestinations 필드에 전달된 위치를 포함하는 배열로, 지오코더가 반환한 형식으로 되어 있습니다.
  • rowsDistanceMatrixResponseRow 객체의 배열로, 각 행은 하나의 출발지에 해당합니다.
  • elementsrows의 하위 요소이고, 행의 출발지와 각 목적지 쌍에 해당합니다. 여기에는 각 출발지/도착지 쌍에 대한 상태, 시간, 거리, 요금 정보(있을 경우)가 포함됩니다.
  • element는 다음 필드를 포함합니다.
    • status: 가능한 상태 코드 목록은 상태 코드를 참조하세요.
    • duration: 이 경로를 이동하는 데 걸리는 시간이며, 초 단위(value 필드)와 text로 표현됩니다. 텍스트 값은 요청에서 지정된 unitSystem에 따라 서식이 지정됩니다(선호 정보가 제공되지 않으면 미터법 기준).
    • duration_in_traffic: 현재 교통 상황을 고려하여 이 경로를 이동하는 데 걸리는 시간이며, 초 단위(value 필드)와 text로 표현됩니다. 텍스트 값은 요청에서 지정된 unitSystem에 따라 서식이 지정됩니다(선호 정보가 제공되지 않으면 미터법 기준). duration_in_traffic은 교통량 데이터를 이용할 수 있고, modedriving으로 설정되고, departureTime이 요청에서 distanceMatrixOptions 필드의 일부로 포함된 Google Maps API 프리미엄 플랜 고객에게만 반환됩니다.
    • 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];
      }
    }
  }
}

다음에 대한 의견 보내기...

Google Maps JavaScript API
Google Maps JavaScript API
도움이 필요하시나요? 지원 페이지를 방문하세요.