개요
Google의 거리 행렬 서비스는 주어진 이동 모드에서 여러 출발지와 목적지 사이의 이동 거리와 여행 기간을 계산합니다.
이 서비스는 상세 경로 정보를 반환하지 않습니다. 폴리라인과 텍스트 길찾기를 포함한 경로 정보는 길찾기 서비스에 원하는 단일 출발지와 목적지를 전달하여 얻을 수 있습니다.
사용 제한 및 요구사항
할당량
거리 행렬 서비스에는 다음과 같은 사용 제한이 적용됩니다.
- 요청당 최대 25개 출발지 또는 25개 목적지
- 요청당 최대 100개 요소(출발지 x 목적지)
요청에는 속도 제한도 적용됩니다. 일정 시간 이내에 너무 많은 요소가 요청되면 OVER_QUERY_LIMIT 응답 코드가 반환됩니다.
Google 지도 표시
거리 행렬 서비스 사용은 Google 지도에 정보를 표시하는 것과 관련이 있어야 합니다(예: 해당 목적지를 요청하여 지도에 표시하기 전에, 특정 운전 시간 내의 출발지-목적지 쌍을 판별하려는 경우). Google 지도를 표시하지 않는 애플리케이션에서는 이 서비스의 사용이 금지되어 있습니다.
거리 행렬 요청
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: google.maps.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(필수) — 하나 이상의 주소 문자열 및/또는1google.maps.LatLng객체를 포함하는 배열로, 이 값에서부터 거리와 시간을 계산합니다.destinations(필수) — 하나 이상의 주소 문자열 및/또는1google.maps.LatLng객체를 포함하는 배열로, 이 값까지의 거리와 시간을 계산합니다.travelMode(선택 항목) — 찾아가는 길을 계산할 때 사용할 이동 모드. 이동 모드의 섹션을 참조하세요.transitOptions(선택 항목) —travelMode가google.maps.TravelMode.TRANSIT인 요청에만 적용되는 옵션. 유효한 값은 아래 대중교통 옵션 섹션에 설명되어 있습니다.drivingOptions(선택 항목)는travelMode가google.maps.TravelMode.DRIVING인 요청에만 적용되는 값을 지정합니다. 유효한 값은 아래 자동차 옵션 섹션에 설명되어 있습니다.unitSystem(선택 항목) — 거리 표시에 사용할 단위 체계. 허용되는 값:google.maps.UnitSystem.METRIC(기본값)google.maps.UnitSystem.IMPERIAL
avoidHighways(선택 항목) —true이면, 출발지와 목적지 사이의 경로가 가능하면 고속도로를 피하도록 계산됩니다.avoidTolls(선택 항목) —true이면 두 지점 사이를 찾아가는 길이 가능하면 무료 경로를 사용하도록 계산됩니다.
이동 모드
시간과 거리를 계산할 때 사용할 이동 모드를 지정할 수 있습니다. 현재 다음과 같은 이동 모드가 지원됩니다.
google.maps.TravelMode.BICYCLING은 자전거 경로 및 선호하는 거리를 경유하는 자전거 길찾기를 요청합니다(현재 미국과 캐나다 일부 도시에만 제공됨).google.maps.TravelMode.DRIVING(기본값)은 도로망을 사용하는 표준 자동차 길찾기를 나타냅니다.google.maps.TravelMode.TRANSIT은 대중교통 경로를 경유하는 길찾기를 요청합니다. 이 옵션은 요청에 API 키가 포함된 경우에만 지정될 수 있습니다. 이 요청 유형에서 이용 가능한 옵션은 대중교통 옵션의 섹션을 참조하세요.google.maps.TravelMode.WALKING은 보행자 경로 및 인도(있는 경우)를 경유하는 도보 길찾기를 요청합니다.
대중교통 옵션
대중교통 서비스는 현재 '실험' 단계입니다. 이 단계에서는 API 악용을 막기 위해 속도 제한을 적용합니다. 최종적으로는 API의 공정한 사용에 기반하여 지도 로드 1회당 총 쿼리에 상한을 적용할 예정입니다.
거리 행렬에서 이용 가능한 옵션은 이동 모드별로 다양합니다. 대중교통 요청에서 avoidHighways 및 avoidTolls 옵션은 무시됩니다. TransitOptions 객체 리터럴을 통해 대중교통별 경로 옵션을 지정할 수 있습니다.
대중교통 요청은 시간에 민감합니다. 계산 값은 미래의 시간에 대해서만 반환됩니다.
TransitOptions 객체 리터럴은 다음 필드를 포함합니다.
{
arrivalTime: Date,
departureTime: Date,
modes: [transitMode1, transitMode2]
routingPreference: TransitRoutePreference
}
다음은 이러한 필드에 대한 설명입니다.
arrivalTime(선택 항목)은 원하는 도착 시간을Date객체로 지정합니다. 도착 시간이 지정되면 출발 시간은 무시됩니다.departureTime(선택 항목)는 원하는 출발 시간을Date객체로 지정합니다.arrivalTime이 지정되면departureTime은 무시됩니다.departureTime또는arrivalTime에 값이 지정되지 않은 경우, now(즉, 현재 시간)가 기본값으로 지정됩니다.modes(선택 항목)는 하나 이상의TransitMode객체 리터럴을 포함하는 배열입니다. 이 필드는 요청에 API 키 또는 클라이언트 ID가 포함된 경우에만 포함할 수 있습니다. 각TransitMode는 선호하는 대중교통 모드를 지정합니다. 다음과 같은 값이 허용됩니다.google.maps.TransitMode.BUS는 계산된 경로가 버스 이동을 선호함을 나타냅니다.google.maps.TransitMode.RAIL은 계산된 경로가 기차, 전차, 경전철 및 지하철 이동을 선호함을 나타냅니다.google.maps.TransitMode.RAIL는 계산된 경로가 지하철 이동을 선호함을 나타냅니다.google.maps.TransitMode.RAIL은 계산된 경로가 기차 이동을 선호함을 나타냅니다.google.maps.TransitMode.RAIL은 계산된 경로가 전차와 경전철 이동을 선호함을 나타냅니다.
routingPreference(선택 항목)는 대중교통 경로에 대한 기본 설정을 지정합니다. 이 옵션을 사용하면, API에 의해 선택되는 기본 최적 경로를 수락하는 대신, 반환되는 옵션을 편중할 수 있습니다. 이 필드는 요청에 API 키가 포함된 경우에만 지정할 수 있습니다. 다음과 같은 값이 허용됩니다.google.maps.TransitRoutePreference.FEWER_TRANSFERS는 계산된 경로가 제한된 환승 횟수를 선호함을 나타냅니다.google.maps.TransitRoutePreference.LESS_WALKING은 계산된 경로가 제한된 도보량을 선호함을 나타냅니다.
자동차 옵션
DrivingOptions 객체를 통해 자동차 노선의 경로 옵션을 지정할 수 있습니다. drivingOptions 필드를 DistanceMatrixRequest에 포함하려면 API를 로드할 때 Google Maps API for Work 클라이언트 ID를 제공해야 합니다.
DrivingOptions 객체는 다음 필드를 포함합니다.
{
departureTime: Date,
trafficModel: TrafficModel
}
다음은 이러한 필드에 대한 설명입니다.
departureTime(drivingOptions객체 리터럴이 유효하려면 필수)는 원하는 출발 시간을Date객체로 지정합니다. 이 값은 현재 시간 또는 미래의 특정 시간으로 설정되어야 합니다. 이 시간은 과거가 될 수 없습니다. (API는 모든 날짜를 UTC로 변환하여 모든 시간대에서 일관적인 처리를 보장합니다.) Google Maps API for Work 고객의 경우, 요청에departureTime을 포함하면 API가 그 시점의 예상 교통 상황을 고려하여 최적 경로를 반환하고, 응답에 교통의 예상 시간(duration_in_traffic)을 포함합니다. 출발 시간을 지정하지 않으면(요청에drivingOptions를 포함하지 않을 경우), 일반적으로 교통 상황을 고려하지 않은 알맞은 경로가 반환됩니다.trafficModel(선택 항목)교통량을 고려한 시간을 계산할 때 사용할 가정을 지정합니다. 이 설정은 응답에서duration_in_traffic필드에 반환되는 값에 영향을 미치며, 여기에는 과거의 평균 교통량에 따른 예상 시간이 포함됩니다. 기본값은best_guess입니다. 다음과 같은 값이 허용됩니다.google.maps.TrafficModel.BEST_GUESS(기본값) 또는 문자열 값best_guess는 과거의 교통 상황과 실시간 교통량을 모두 알고 있을 때, 반환된duration_in_traffic이 최적의 예상 이동 시간임을 나타냅니다. 실시간 교통량은departureTime이 현재에 더 가까울수록 더 중요해 집니다.google.maps.TrafficModel.PESSIMISTIC또는 문자열 값pessimistic은 반환된duration_in_traffic이 평소의 실제 이동 시간보다 더 긴 것을 나타내지만, 특히 교통 상황이 나쁜 날에는 이 값을 초과할 수도 있습니다.google.maps.TrafficModel.OPTIMISTIC또는 문자열 값optimistic은 반환된duration_in_traffic이 평소의 실제 이동 시간보다 더 짧은 것을 나타내지만, 특히 교통 상황이 좋은 날에는 이 값보다 더 빨라질 수도 있습니다.
다음은 출발 시간과 교통량 모델을 포함한 자동차 경로의 DistanceMatrixRequest 샘플입니다.
{
origins: [{lat: 55.93, lng: -3.118}, "Greenwich, England"],
destinations: ["Stockholm, Sweden", {lat: 50.087, lng: 14.421}],
travelMode: google.maps.TravelMode.DRIVING,
drivingOptions: {
departureTime: new Date(Date.now() + N), // for the time N milliseconds from now.
trafficModel: "optimistic"
}
}
거리 행렬 응답
거리 행렬 서비스 호출에 성공하면 DistanceMatrixResponse 객체와 DistanceMatrixStatus 객체가 반환됩니다. 이러한 객체는 요청에서 지정한 콜백 함수로 전달됩니다.
DistanceMatrixResponse 객체는 경로를 계산할 수 있는 각 출발지/도착지 쌍에 대한 거리와 시간 정보를 포함합니다.
{
"origin_addresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
"destination_addresses": [ "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필드의 일부로 포함된 Google Maps API for Work 고객에게만 반환됩니다.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 == google.maps.DistanceMatrixStatus.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];
}
}
}
}
도움이 필요하시나요? 지원 페이지