모든 준비를 마쳤습니다!

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

Google Maps JavaScript API 활성화

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

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

길찾기 서비스

개요

DirectionsService 객체를 사용하여 (다양한 교통수단으로) 찾아가는 길을 계산할 수 있습니다. 이 객체는 길찾기 요청을 수신하고 계산된 결과를 반환하는 Google Maps API 길찾기 서비스와 통신합니다. 길찾기 결과를 직접 처리하거나 DirectionsRenderer 객체를 사용하여 결과를 렌더링할 수 있습니다.

길찾기 요청에서 출발지나 목적지를 지정할 때 쿼리 문자열(예: "Chicago, IL" 또는 "Darwin, NSW, Australia"), LatLng 값 또는 google.maps.Place 객체를 지정할 수 있습니다.

길찾기 서비스는 일련의 경유지를 사용하여 여러 찾아가는 길을 반환할 수 있습니다. 길찾기는 지도에 경로를 그리는 폴리라인 또는 <div> 요소 내에서 일련의 텍스트 설명이 더해진 형식으로 표시됩니다(예: "윌리엄스버그 다리 램프에서 우회전").

시작하기

Google Maps JavaScript API에서 길찾기 서비스를 사용하려면 먼저 Google Maps JavaScript API에 대해 설정한 동일한 프로젝트의 Google API Console에서 Google Maps Directions API를 활성화해야 합니다.

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

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

사용 제한 및 정책

할당량

길찾기 서비스의 사용 제한은 다음과 같습니다.

기본 플랜으로 길찾기 서비스 사용

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

프리미엄 플랜으로 길찾기 서비스 사용

  • 24시간당 100,000개 요청의 공유 일일 무료 할당량, 연간 구매의 Maps API 크레딧에 적용되는 추가적인 요청 .
  • 각 요청당 최대 23개 경유지(출발지 및 목적지 포함)가 허용됩니다.
  • 프로젝트별로 초당 무제한개의 클라이언트측 요청. 서버측 API는 초당 50개의 요청으로 제한됩니다.

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

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

정책

길찾기 서비스는 Google Maps Directions API에 대해 설명된 정책에 따라 사용해야 합니다.

길찾기 요청

Google Maps API는 외부 서버를 호출해야 하므로 길찾기 서비스 액세스는 비동기식입니다. 그러므로 콜백 메서드를 전달하여 요청이 완료되면 실행해야 합니다. 이 콜백 메서드가 결과를 처리해야 합니다. 길찾기 서비스는 하나 이상의 가능한 여정을 별개의 routes[] 배열로 반환할 수 있습니다.

Google Maps JavaScript API에서 길찾기를 사용하려면 DirectionsService 유형 객체를 생성하고 DirectionsService.route()를 호출하여 길찾기 서비스 요청을 시작한 후, 입력어와 콜백 메서드를 포함하는 DirectionsRequest 객체 리터럴에 전달하여 응답을 받는 즉시 실행합니다.

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

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

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

  • origin(필수)은 찾아가는 길을 계산할 시작 위치를 지정합니다. 이 값은 String(예: "Chicago, IL"), LatLng 값 또는 google.maps.Place 객체로 지정될 수 있습니다. google.maps.Place 객체를 사용할 경우, 장소 ID, 쿼리 문자열 또는 LatLng 위치를 지정할 수 있습니다. Google Maps JavaScript API의 지오코딩, 장소 검색, 장소 자동완성 서비스에서 장소 ID를 검색할 수 있습니다. 장소 자동완성에서 장소 ID를 사용하는 예는 장소 자동완성 및 길찾기를 참조하세요.
  • destination(필수)은 찾아가는 길을 계산할 종료 위치를 지정합니다. 이 옵션은 위에 설명된 origin 필드의 옵션과 동일합니다.
  • travelMode(필수)는 찾아가는 길을 계산할 때 사용할 이동 모드를 지정합니다. 유효한 값은 아래 이동 모드에서 지정됩니다.
  • transitOptions(선택 항목)는 travelModeTRANSIT인 요청에만 적용되는 값을 지정합니다. 유효한 값은 아래 대중교통 옵션에 설명되어 있습니다.
  • drivingOptions(선택 항목)는 travelModeDRIVING인 요청에만 적용되는 값을 지정합니다. 유효한 값은 아래 자동차 옵션에 설명되어 있습니다.
  • unitSystem(선택 항목)은 결과를 표시할 때 사용할 단위 체계를 지정합니다. 유효한 값은 아래의 단위 체계에서 지정됩니다.

  • waypoints[](선택 항목)는 DirectionsWaypoint의 배열을 지정합니다. 경유지는 지정된 위치를 지나가도록 경로를 변경합니다. 경유지는 아래의 필드가 포함된 객체 리터럴로 지정됩니다.

    • location은 경유지의 위치를 LatLng, google.maps.Place 객체 또는 지오코딩되는 String으로 지정합니다.
    • stopover는 경유지가 경로 상의 정류장임을 나타내는 부울로, 경로를 두 개로 나누는 효과가 있습니다.

    (경유지에 대한 자세한 내용은, 아래의 경로에 경유지 사용을 참조하세요.)

  • optimizeWaypoints(선택 항목)는 보다 효율적인 순서로 경유지를 재배열하는 방식으로 제공된 waypoints를 사용하는 경로가 최적화될 수 있음을 지정합니다. true인 경우, 길찾기 서비스가 waypoint_order 필드에 재정렬된 waypoints를 반환합니다. (자세한 내용은 아래의 경로에서 경유지 사용을 참조하세요.)
  • provideRouteAlternatives(선택 항목)는 true로 설정된 경우, 길찾기 서비스가 응답에서 하나 이상의 경로를 제공할 수 있음을 지정합니다. 참고로, 대체 경로를 제공하면 서버의 응답 시간이 늘어날 수도 있습니다.
  • avoidHighways(선택 항목)는 true로 설정된 경우, 계산된 경로가 가능하면 주요 고속도로를 피해가야 함을 나타냅니다.
  • avoidTolls(선택 항목)는 true로 설정된 경우, 계산된 경로가 가능하면 유료 도로를 피해가야 함을 나타냅니다.
  • region(선택 항목)은 ccTLD ("최상위 도메인") 두 문자 값으로 지정된 지역 코드를 지정합니다. (자세한 내용은 아래의 지역 편중을 참조하세요.)

다음은 DirectionsRequest 샘플입니다.

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

이동 모드

찾아가는 길을 계산할 때 사용할 이동 모드를 지정해야 합니다. 현재 다음과 같은 이동 모드가 지원됩니다.

  • DRIVING(기본값)은 도로망을 사용하는 표준 자동차 길찾기를 나타냅니다.
  • BICYCLING은 자전거 경로 및 선호하는 거리를 경유하는 자전거 길찾기를 요청합니다.
  • TRANSIT은 대중교통 경로를 경유하는 길찾기를 요청합니다.
  • WALKING은 보행자 경로 및 인도를 경유하는 도보 길찾기를 요청합니다.

특정 국가가 어느 정도의 길찾기를 지원하는지 알아보려면 Google 지도 커버리지 데이터를 참조하세요. 길찾기 유형을 사용할 수 없는 지역에서 길찾기를 요청하면 DirectionsStatus="ZERO_RESULTS"라는 응답이 반환됩니다.

도보 길찾기에 불명확한 보행자 경로가 포함될 수 있으므로, 이러한 길찾기에서는 DirectionsResult에 경고를 반환합니다. 기본 DirectionsRenderer를 사용하지 않는 경우, 이 경고를 표시해야 합니다.

대중교통 옵션

길찾기 요청에서 이용 가능한 옵션은 이동 모드별로 다양합니다. 대중교통 길찾기 요청 시 avoidHighways, avoidTolls, waypoints[]optimizeWaypoints 옵션은 무시됩니다. TransitOptions 객체 리터럴을 통해 대중교통별 경로 옵션을 지정할 수 있습니다.

대중교통 길찾기는 시간에 민감합니다. 길찾기는 미래의 시간에 대해서만 반환됩니다.

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

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

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

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

다음은 대중교통별 샘플 DirectionsRequest입니다.

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

자동차 옵션

DrivingOptions 객체를 통해 자동차 길찾기의 경로 옵션을 지정할 수 있습니다. drivingOptions 필드를 DirectionsRequest에 포함하려면 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 필드에 반환되는 값에 영향을 미치며, 여기에는 과거의 평균 교통량에 따른 예상 시간이 포함됩니다. 기본값은 bestguess입니다. 다음과 같은 값이 허용됩니다.
    • bestguess(기본값)는 과거의 교통 상황과 실시간 교통량을 모두 알고 있을 때, 반환된 duration_in_traffic이 최적의 예상 이동 시간임을 나타냅니다. 실시간 교통량은 departureTime이 현재에 더 가까울수록 더 중요해 집니다.
    • pessimistic은 반환된 duration_in_traffic이 평소의 실제 이동 시간보다 더 긴 것을 나타내지만, 특히 교통 상황이 나쁜 날에는 이 값을 초과할 수도 있습니다.
    • optimistic은 반환된 duration_in_traffic이 평소의 실제 이동 시간보다 더 짧은 것을 나타내지만, 특히 교통 상황이 좋은 날에는 이 값보다 더 빨라질 수도 있습니다.

다음은 자동차 길찾기를 위한 샘플 DirectionsRequest입니다.

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

단위 체계

기본적으로, 길찾기는 출발지 국가 또는 지역의 단위 체계를 사용하여 계산되고 표시됩니다. (참고: 주소가 아닌 위도/경도 좌표로 표현되는 출발지의 기본값은 항상 미터 단위입니다.) 예를 들어, "IL 시카고"에서 "ONT 토론토"까지의 경로는 마일 단위로 결과를 표시하는 반면, 그 반대 경로는 킬로미터 단위로 결과를 표시합니다. 다음 UnitSystem 값 중 하나를 사용하여 요청에서 단위를 명시적으로 설정하는 방식으로 이 단위 체계를 재정의할 수 있습니다.

  • UnitSystem.METRIC은 미터 체계를 사용하도록 지정합니다. 거리는 킬로미터로 표시됩니다.
  • UnitSystem.IMPERIAL은 임페리얼(영국) 체계를 사용하도록 지정합니다. 거리는 마일로 표시됩니다.

참고: 이 단위 체계 설정은 사용자에게 표시되는 텍스트에만 영향을 미칩니다. 길찾기 결과에는 사용자에게 표시되지 않는 거리 도 포함되며, 항상 미터 단위로 표현됩니다.

길찾기의 지역 편중

Google Maps API 길찾기 서비스는 JavaScript 부트스트랩을 로드한 도메인(지역 또는 국가)에 영향을 받은 주소 결과를 반환합니다. (대부분 사용자가 https://maps.google.com/을 로드하므로, 도메인은 암시적으로 미국으로 설정됩니다.) 다른 지원 도메인에서 부트스트랩을 로드하면, 해당 도메인에 영향을 받은 결과를 얻게 됩니다. 예를 들어, "샌프란시스코"를 검색할 때 http://maps.google.es/(스페인)을 로드하는 애플리케이션과 https://maps.google.com/(미국)을 로드하는 애플리케이션은 다른 결과를 반환할 수 있습니다.

또한, region 매개변수를 사용하여 특정 지역으로 편중된 결과를 반환하도록 길찾기 서비스를 설정할 수도 있습니다. 이 매개변수는 IANA 언어 region 하위 태그로 지정된 지역 코드를 취합니다. 대부분의 경우, 이 태그는 "uk" 또는 "co.uk"와 같이 ccTLD("최상위 도메인") 두 문자 값으로 바로 매핑됩니다. 대부분의 경우, region 태그도 ISO-3166-1 코드를 지원하며, 때로는 ccTLD 값과 다를 수 있습니다(예: "Great Britain"의 경우 "GB").

특정 국가가 어느 정도의 길찾기를 지원하는지 알아보려면 Google 지도 커버리지 데이터를 참조하세요.

길찾기 렌더링

route() 메서드로 DirectionsService에 대한 길찾기 요청을 시작하려면 서비스 요청이 완료되는 즉시 실행되는 콜백을 전달해야 합니다. 이 콜백은 응답에서 DirectionsResultDirectionsStatus 코드를 반환합니다.

길찾기 쿼리 상태

DirectionsStatus는 다음 값을 반환할 수 있습니다.

  • OK는 응답이 올바른 DirectionsResult를 포함함을 나타냅니다.
  • NOT_FOUND는 요청의 출발지, 목적지 또는 경유지에 지정된 위치 중 최소 한 개 이상을 지오코딩할 수 없음을 나타냅니다.
  • ZERO_RESULTS는 출발지와 목적지 사이에 경로를 찾을 수 없음을 나타냅니다.
  • MAX_WAYPOINTS_EXCEEDEDDirectionsRequest에서 너무 많은 DirectionsWaypoint 필드가 제공되었음을 나타냅니다. 경유지 제한에 대해서는 아래 섹션을 참조하세요.
  • INVALID_REQUEST는 제공된 DirectionsRequest가 잘못되었음을 나타냅니다. 오류 코드가 발생하는 가장 흔한 원인은 요청에 출발지나 목적지가 누락되어 있거나, 대중교통 요청에 경유지가 포함된 경우입니다.
  • OVER_QUERY_LIMIT는 허용된 시간 내에 웹페이지가 너무 많은 요청을 전송했음을 나타냅니다.
  • REQUEST_DENIED는 이 웹페이지가 길찾기 서비스를 사용할 수 없음을 나타냅니다.
  • UNKNOWN_ERROR는 서버 오류로 인해 길찾기 요청을 처리할 수 없음을 나타냅니다. 다시 시도하면 요청이 성공할 수도 있습니다.

결과를 처리하기 전에 이 값을 검사하여 길찾기 쿼리가 유효한 결과를 반환했는지 확인해야 합니다.

DirectionsResult 표시

DirectionsResult에는 길찾기 쿼리 결과가 포함됩니다. 이 결과를 직접 처리하거나 DirectionsRenderer 객체에 전달하여 지도에 결과 표시를 자동으로 처리할 수 있습니다.

DirectionsRenderer를 사용하여 DirectionsResult를 표시하려면 다음을 수행하면 됩니다.

  1. DirectionsRenderer 객체를 생성합니다.
  2. 렌더러에서 setMap()을 호출하여 전달된 지도에 바인딩합니다.
  3. 렌더러에서 setDirections()을 호출하여 위에서 언급한 대로 DirectionsResult에 전달합니다. 렌더러는 MVCObject이므로, 속성의 변경 사항을 자동으로 감지하고 관련 길찾기가 변경되면 지도를 업데이트합니다.

다음 예시는 66번 도로에서 두 지점 간에 찾아가는 길을 계산합니다. 출발지와 목적지는 드롭다운 목록에서 "start""end" 값으로 설정됩니다. DirectionsRenderer는 표시된 위치 간의 폴리라인 표시를 처리하고, 출발지와 목적지, 경유지에 마커를 배치합니다(해당되는 경우).

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsDisplay.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsDisplay.setDirections(result);
    }
  });
}

HTML 본문:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

예시 보기(directions-simple.html)

다음 예시는 캘리포니아 주 샌프란시스코에서 헤이트 애시베리와 오션 비치 사이의 길찾기를 다양한 이동 모드로 보여줍니다.

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;
var haight = new google.maps.LatLng(37.7699298, -122.4469157);
var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsDisplay.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that Javascript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsDisplay.setDirections(response);
    }
  });
}

HTML 본문:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

예시 보기(directions-travel-modes.html)

DirectionsRenderer는 폴리라인과 관련 마커 표시를 처리할 뿐만 아니라, 길찾기를 일련의 단계로 구성된 텍스트로 표시하는 작업도 처리할 수 있습니다. 그렇게 하려면 DirectionsRenderer에서 setPanel()을 호출하고 이 정보를 표시할 <div>에 전달하면 됩니다. 그러면 적절한 저작권 정보는 물론, 결과와 관련된 경고도 표시할 수 있습니다.

텍스트 길찾기는 브라우저가 선호하는 언어 설정이나 language 매개변수를 사용하여 API JavaScript를 로드할 때 지정된 언어로 제공됩니다. (자세한 내용은 현지화를 참조하세요.) 대중교통 길찾기의 경우, 대중교통 정류장에 해당 시간대의 시간이 표시됩니다.

다음 예시는 위의 예시와 같지만, 길찾기를 표시하는 <div> 패널이 포함되어 있습니다.

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsDisplay.setMap(map);
  directionsDisplay.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsDisplay.setDirections(response);
    }
  });
}

HTML 본문:

<div id="map" style="float:left;width:70%; height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height 100%"></div>

예시 보기(directions-panel.html)

DirectionsResult 객체

DirectionsService에 길찾기 요청을 보내면 상태 코드와 결과(DirectionsResult 객체)로 구성된 응답을 수신합니다. DirectionsResult는 다음 필드가 포함된 객체 리터럴입니다.

  • geocoded_waypoints[]는 출발지, 목적지, 경유지의 지오코딩에 대한 세부정보가 있는 DirectionsGeocodedWaypoint 객체 배열을 포함합니다.
  • routes[]DirectionsRoute 객체의 배열을 포함합니다. 각 경로는 DirectionsRequest에서 제공된 출발지에서 목적지로 가는 길을 나타냅니다. 일반적으로 각 요청에 대해 하나의 경로만 반환됩니다. 그러나 요청의 provideRouteAlternatives 필드가 true로 설정된 경우, 여러 경로가 반환될 수 있습니다.

길찾기 지오코딩된 경유지

DirectionsGeocodedWaypoint는 출발지, 목적지 및 경유지의 지오코딩에 대한 세부정보가 있는 배열을 포함합니다.

DirectionsGeocodedWaypoint는 다음 필드가 포함된 객체 리터럴입니다.

  • geocoder_status는 지오코딩 작업의 상태 코드 결과를 나타냅니다. 이 필드는 다음 값을 포함할 수 있습니다.
    • "OK"는 오류가 발생하지 않았음을 나타냅니다. 주소가 성공적으로 구문 분석되고 하나 이상의 지오코드가 반환되었습니다.
    • "ZERO_RESULTS"는 지오코드가 성공했지만 반환된 결과가 없음을 나타냅니다. 이는 존재하지 않는 address가 지오코더에 전달된 경우 발생할 수 있습니다.
  • partial_match는 지오코더가 원래 요청에 대해 정확한 일치를 반환하지 않았으며, 요청된 주소의 일부분만 일치함을 나타냅니다. 원래 요청을 검사하여 맞춤법 오류 및/또는 불완전한 주소를 찾아낼 수 있습니다.

    부분 일치가 가장 자주 발생하는 경우는, 요청으로 전달되는 지역 내에 거리 주소가 존재하지 않는 경우입니다. 또한, 동일한 지역에서 한 요청에 대해 2개 이상의 위치가 일치하는 경우에도 부분 일치가 반환될 수 있습니다. 예를 들어, "21 Henr St, Bristol, UK"는 Henry Street 및 Henrietta Street 모두에 대해 부분 일치를 반환합니다. 참고로, 맞춤법이 틀린 주소 요소가 요청에 포함된 경우에는 지오코딩 서비스에서 대체 주소를 제안할 수도 있습니다. 이러한 방식으로 실행된 제안도 부분 일치로 표시될 수 있습니다.

  • place_id는 다른 Google API에 사용할 수 있는 장소의 고유 식별자입니다. 예를 들어, Google Places API와 함께 place_id를 사용하여 전화번호, 개점 시간, 사용자 리뷰 등의 지역 사업체 상세정보를 알아낼 수 있습니다. 장소 ID 개요를 참조하세요.
  • types[]는 반환된 결과의 유형을 나타내는 배열입니다. 이 배열에는 결과로 반환되는 기능의 유형을 식별하는 0개 이상의 태그 집합이 포함됩니다. 예를 들어, "시카고"의 지오코드는 "시카고"가 도시임을 나타내는 "locality"를 반환하고, 또한 시카고가 정치적 엔터티임을 나타내는 "political"을 반환합니다.

길찾기 경로

이전의 DirectionsTrip 객체는 DirectionsRoute로 이름이 변경되었습니다. 이제 경로는 상위 여정의 한 부분이 아니라 여정을 출발할 때부터 끝날 때까지 전 과정을 나타냅니다.

DirectionsRoute 배열의 각 요소는 지정된 출발지 및 목적지의 단일 결과를 포함합니다. 이 경로는 경유지가 지정되었는지 여부에 따라 하나 이상의 구간(DirectionsLeg 유형)으로 구성될 수 있습니다. 또한, 경로에는 라우팅 정보뿐만 아니라 사용자에게 표시되어야 하는 저작권 및 경고 정보가 포함됩니다.

DirectionsRoute는 다음 필드가 포함된 객체 리터럴입니다.

  • legs[]DirectionsLeg 객체의 배열을 포함합니다. 각 객체에는 지정된 경로에 있는 두 위치 사이의 구간에 대한 정보가 포함됩니다. 지정된 각 경유지 또는 목적지에 대해 별도의 구간이 존재합니다. (경유지가 없는 경로는 DirectionsLeg 배열 내에 단 하나의 구간만 포함합니다.) 각 구간은 일련의 DirectionStep으로 구성됩니다.
  • waypoint_order는 계산된 경로의 경유지 순서를 나타내는 배열을 포함합니다. 이 배열은 DirectionsRequestoptimizeWaypoints: true를 전달하면 변경되는 순서를 포함할 수 있습니다.
  • overview_path는 길찾기 결과의 대략적인(다듬어진) 경로를 나타내는 LatLng 배열을 포함합니다.
  • overview_polyline은 경로의 인코딩된 폴리라인 표현이 들어있는 단일 points 객체를 포함합니다. 이 폴리라인은 최종 길찾기의 대략적인(다듬어진) 경로입니다.
  • bounds는 주어진 경로를 따라 폴리라인의 경계를 나타내는 LatLngBounds를 포함합니다.
  • copyrights는 이 경로에 표시되어야 하는 저작권 텍스트를 포함합니다.
  • warnings[]는 이러한 찾아가는 길을 표시할 때 표시되어야 하는 경고 배열을 포함합니다. 제공된 DirectionsRenderer 객체를 사용하지 않을 경우, 본인이 직접 이 경고를 처리하고 표시해야 합니다.
  • fare는 이 경로상의 전체 요금(즉, 전체 티켓 비용)을 포함합니다. 이 속성은 대중교통 요청 및 모든 대중교통 구간에 대해 요금 정보를 사용할 수 있는 경로에 대해서만 반환됩니다. 이 정보에는 다음과 같은 항목이 포함됩니다.
    • currency: 금액이 표시되는 통화를 나타내는 ISO 4217 통화 코드.
    • value: 위에 지정된 통화의 전체 요금액.

길찾기 구간

이전의 DirectionsRoute 객체는 DirectionsLeg로 이름이 변경되었습니다.

DirectionsLeg는 계산된 경로에서 출발지부터 목적지까지 단일 여정 구간을 정의합니다. 포함된 경유지가 없는 경로의 경우에는 경로가 단일 "구간"으로 구성되지만, 하나 이상의 경유지가 정의된 경로의 경우에는 경로가 하나 이상의 구간으로 구성되며, 각 구간은 특정한 여정 구간에 해당합니다.

DirectionsLeg는 다음 필드가 포함된 객체 리터럴입니다.

  • steps[]는 여정 구간의 각 개별 스텝에 대한 정보를 표시하는 DirectionsStep 배열을 포함합니다.
  • distance는 이 구간에 포함되는 전체 거리를 다음과 같은 형식의 Distance 객체로 나타냅니다.

    • value는 미터 단위의 거리를 나타냅니다
    • text는 거리로 표시된 문자열을 포함하며, 출발지에서 사용되는 단위가 기본으로 표시됩니다. (예를 들어, 마일은 미국 내의 출발지에 사용됩니다.) 원래 쿼리에서 UnitSystem을 구체적으로 설정하면 이 단위 체계를 재정의할 수 있습니다. 참고로, 어떤 단위 체계를 사용하든 상관없이 distance.value 필드는 항상 미터 단위로 표현되는 값을 포함합니다.

    거리를 알 수 없는 경우에는 이 필드가 정의되지 않을 수도 있습니다.

  • duration은 이 구간의 전체 기간을 다음과 같은 형식의 Duration 객체로 나타냅니다.

    • value는 기간을 초 단위로 나타냅니다.
    • text는 기간을 표현하는 문자열을 포함합니다.

    기간을 알 수 없는 경우에는 이 필드가 정의되지 않을 수도 있습니다.

  • duration_in_traffic은 현재의 교통량을 고려하여 이 구간의 전체 기간을 나타냅니다. duration_in_traffic은 다음 사항이 모두 참인 경우에만 반환됩니다.

    • 올바른 Google Maps API 프리미엄 플랜 클라이언트 ID가 요청에 포함되어 있습니다.
    • 요청이 중간 기착 경유지를 포함하지 않습니다. 즉, stopovertrue인 경유지는 포함하지 않습니다.
    • 요청이 자동차 길찾기 전용으로 사용되며, modedriving으로 설정되었습니다.
    • departureTimedrivingOptions 필드의 일부분으로 요청에 포함되어 있습니다.
    • 요청한 경로에 대해 교통 상황이 제공됩니다.

    duration_in_traffic은 다음 필드를 포함합니다.

    • value는 기간을 초 단위로 나타냅니다.
    • text는 사람이 읽을 수 있도록 표시된 기간을 포함합니다.
  • arrival_time은 이 구간의 예상 도착 시간을 포함합니다. 이 속성은 대중교통 길찾기에 대해서만 반환됩니다. 결과는 다음의 세 가지 속성과 함께 Time 객체로 반환됩니다.
    • value는 JavaScript Date 객체로 지정되는 시간입니다.
    • text는 문자열로 지정되는 시간입니다. 이 시간은 대중교통 정류장의 시간대로 표시됩니다.
    • time_zone은 이 역의 시간대를 포함합니다. 이 값은 IANA 시간대 데이터베이스에 정의된 시간대의 이름입니다. 예: "America/New_York"
  • departure_timeTime 객체로 지정된 이 구간의 예상 출발 시간을 포함합니다. departure_time은 대중교통 길찾기에만 사용할 수 있습니다.
  • start_location은 이 구간의 출발지에 대한 LatLng를 포함합니다. 길찾기 웹 서비스는 시작 지점과 종료 지점에서 가장 가까운 이동 옵션(대개는 도로)을 사용하여 위치 간의 찾아가는 길을 계산하기 때문에, start_location과 이 구간의 출발지가 다를 수도 있습니다(예: 출발지 근처에 도로가 없음).
  • end_location은 이 구간의 목적지에 대한 LatLng를 포함합니다. DirectionsService는 시작 지점과 종료 지점에서 가장 가까운 이동 옵션(대개는 도로)을 사용하여 위치 간의 찾아가는 길을 계산하기 때문에, end_location과 이 구간의 목적지가 다를 수도 있습니다(예: 목적지 근처에 도로가 없음).
  • start_address는 이 구간 시작 지점의 사람이 읽을 수 있는 주소(일반적으로 거리 주소)를 포함합니다.
  • end_address는 이 구간 종료 지점의 사람이 읽을 수 있는 주소(일반적으로 거리 주소)를 포함합니다.

길찾기 스텝

DirectionsStep은 길찾기 경로의 가장 작은 단위이며, 여정에서 특정 단일 지시를 나타내는 단일 스텝을 포함합니다. 예: "서쪽 네 번째 거리에서 좌회전" 스텝은 지시를 나타낼 뿐만 아니라 이 스텝이 다음 스텝과 어떻게 관련되는지에 대한 거리 및 기간 정보도 포함합니다. 예를 들어, "I-80 서쪽에서 합류"로 지정된 스텝은 "37마일" 및 "40분"을 포함할 수 있으며, 이는 그 다음 스텝이 이 스텝에서 37마일/40분 떨어져 있음을 나타냅니다.

길찾기 서비스를 사용하여 대중교통 길찾기를 검색할 경우, 스텝 배열은 transit 객체의 형식으로 추가적인 대중교통 특정 정보를 포함합니다. 길찾기에 여러 이동 모드가 포함된 경우, 도보 또는 자동차 스텝에 대한 상세한 길찾기가 내부 steps[] 배열에 제공됩니다. 예를 들어, 도보 스텝에는 시작 및 끝 위치의 찾아가는 길이 포함됩니다: "인스 애비뉴 및 피치 거리까지 도보". 이 스텝에는 내부 steps[] 배열의 해당 경로에 대한 상세한 도보 길찾기가 포함됩니다. 예: "북서쪽으로 향함", "아렐리우스 워커로 좌회전" 및 "인스 애비뉴로 좌회전".

DirectionsStep는 다음 필드가 포함된 객체 리터럴입니다.

  • instructions는 텍스트 문자열에 이 스텝에 대한 지시를 포함합니다.
  • distance는 이 스텝에서 다음 스텝까지의 거리를 Distance 객체로 포함합니다. (위의 DirectionsLeg의 설명을 참조하세요.) 거리를 알 수 없는 경우에는 이 필드가 정의되지 않을 수도 있습니다.
  • duration은 다음 스텝까지 해당 스텝을 수행하는 데 필요한 추정 시간을 Duration 객체로 포함합니다. (위의 DirectionsLeg의 설명을 참조하세요.) 기간을 알 수 없는 경우에는 이 필드가 정의되지 않을 수도 있습니다.
  • start_location은 이 스텝의 시작 지점의 위치를 지오코딩된 LatLng으로 포함합니다.
  • end_location은 이 스텝의 종료 지점에 대한 LatLng를 포함합니다.
  • polyline은 스텝의 인코딩된 폴리라인 표현이 들어있는 단일 points 객체를 포함합니다. 이 폴리라인은 스텝의 대략적인(다듬어진) 경로입니다.
  • steps[]DirectionsStep 객체 리터럴로, 대중교통 길찾기에서 도보 또는 운전 스텝에 대한 상세한 길찾기를 포함합니다. 하위 스텝은 대중교통 길찾기에만 사용할 수 있습니다.
  • travel_mode는 이 스텝에서 사용되는 TravelMode를 포함합니다. 대중교통 길찾기는 도보와 대중교통 길찾기가 혼합되어 포함될 수 있습니다.
  • path는 이 스텝의 코스를 설명하는 LatLngs 배열을 포함합니다.
  • transit는 도착 및 출발 시간, 대중교통 노선 이름 등의 대중교통 특정 정보를 포함합니다.

대중교통 특정 정보

대중교통 길찾기는 다른 이동 모드와는 무관한 추가적인 정보를 반환합니다. 이러한 추가적인 속성은 TransitDetails 객체를 통해 노출되며, DirectionsStep 속성으로 반환됩니다. 아래 설명된 것처럼, TransitDetails 객체에서 TransitStop, TransitLine, TransitAgencyVehicleType 객체에 대한 추가 정보에 액세스할 수 있습니다.

대중교통 상세정보

TransitDetails 객체는 다음 속성을 노출합니다.

  • arrival_stop은 다음 속성으로 도착 정거장/정류장을 나타내는 TransitStop 객체를 포함합니다.
    • name은 대중교통 정류장/역의 이름입니다. 예: "유니온 스퀘어".
    • location은 대중교통 정류장/역의 위치이며, LatLng로 표현됩니다.
  • departure_stop은 출발 정거장/정류장을 나타내는 TransitStop 객체를 포함합니다.
  • arrival_time은 도착 시간을 포함하며, 세 가지 속성이 있는 Time 객체로 지정됩니다.
    • value는 JavaScript Date 객체로 지정되는 시간입니다.
    • text는 문자열로 지정되는 시간입니다. 이 시간은 대중교통 정류장의 시간대로 표시됩니다.
    • time_zone은 이 역의 시간대를 포함합니다. 이 값은 IANA 시간대 데이터베이스에 정의된 시간대의 이름입니다. 예: "America/New_York"
  • departure_time은 출발 시간을 포함하며, Time 객체로 지정됩니다.
  • headsign은 이 노선에서 이동할 방향을 지정하며, 차량 위나 출발 정류장 위에 표시됩니다. 이는 대개 종착역입니다.
  • headway는 해당되는 경우, 현재 동일 정류장에서 각 출발 사이의 예상 시간을 초 단위로 지정합니다. 예를 들어, headway 값이 600이면, 버스를 놓친 경우 10분의 대기 시간을 예상할 수 있습니다.
  • line은 이 스텝에서 사용된 대중교통 노선 정보가 있는 TransitLine 객체 리터럴을 포함합니다. TransitLineTransitLine 참조 문서에 설명된 다른 속성과 더불어, 노선 이름과 운영자를 제공합니다.
  • num_stops는 이 스텝의 정류장 수를 포함합니다. 도착 정류장이 포함되지만, 출발 정류장은 포함되지 않습니다. 예를 들어, 길찾기가 정류장 A에서 출발하여 정류장 B, C를 지나 정류장 D에 도착하는 경우, num_stops는 3을 반환합니다.

대중교통 노선

TransitLine 객체는 다음 속성을 노출합니다.

  • name은 이 대중교통 노선의 전체 이름을 포함합니다. 예: "7 Avenue Express" 또는 "14th St Crosstown".
  • short_name은 이 대중교통 노선의 짧은 이름을 포함합니다. 일반적으로 이 이름은 "2" 또는 "M14" 등과 같은 노선 번호입니다.
  • agenciesTransitAgency 유형의 배열을 포함합니다. 각 TransitAgency 객체는 다음 속성을 포함하여 이 노선 사업자에 관한 정보를 제공합니다.
    • name은 대중교통 기관의 이름을 포함합니다.
    • url은 대중교통 기관의 URL을 포함합니다.
    • phone은 대중교통 기관의 전화번호를 포함합니다.

    DirectionsRenderer 객체를 사용하는 대신 직접 대중교통 길찾기를 렌더링하는 경우, 여행 결과를 서비스하는 대중교통 기관의 이름과 URL을 표시해야 합니다.

  • url은 대중교통 기관에서 제공하는 이 대중교통 노선의 URL을 포함합니다.
  • icon은 이 노선과 관련된 아이콘의 URL을 포함합니다. 대부분 도시는 차량 유형별로 달라지는 기본 아이콘을 사용합니다. 뉴욕 지하철 시스템 등의 일부 대중교통 노선은 그 노선에만 적용되는 아이콘이 있습니다.
  • color는 이 대중교통 표시판에 일반적으로 사용되는 색상을 포함합니다. 색상은 #FF0033과 같은 16진수 문자열로 지정됩니다.
  • text_color는 이 노선의 표시판에 일반적으로 사용되는 텍스트의 색상을 포함합니다. 색상은 16진수 문자열로 지정됩니다.
  • vehicle은 다음 속성이 있는 Vehicle 객체를 포함합니다.
    • name은 이 노선의 차량 이름을 포함합니다. 예: "지하철"
    • type은 이 노선에 사용되는 차량의 유형을 포함합니다. 지원되는 값의 전체 목록은 차량 유형 문서를 참조하세요.
    • icon은 이 차량 유형과 관련된 아이콘의 URL을 포함합니다.
    • local_icon은 지역 교통 표시판에 따라 이 차량 유형과 관련된 아이콘의 URL을 포함합니다.

차량 유형

VehicleType 객체는 다음 속성을 노출합니다.

정의
VehicleType.RAIL 철도.
VehicleType.METRO_RAIL 경전철 대중교통.
VehicleType.SUBWAY 지하 경전철.
VehicleType.TRAM 지상 경전철.
VehicleType.MONORAIL 모노레일.
VehicleType.HEAVY_RAIL 일반 열차.
VehicleType.COMMUTER_TRAIN 통근 열차.
VehicleType.HIGH_SPEED_TRAIN 고속 전철.
VehicleType.BUS 버스.
VehicleType.INTERCITY_BUS 시외 버스.
VehicleType.TROLLEYBUS 트롤리 버스.
VehicleType.SHARE_TAXI 합승 택시는 일종의 버스이며, 경로상의 어느 곳에서나 승객이 승하차할 수 있습니다.
VehicleType.FERRY 페리.
VehicleType.CABLE_CAR 일반적으로 지상에서 케이블로 운영되는 차량입니다. 공중 케이블카는 VehicleType.GONDOLA_LIFT 유형일 수 있습니다.
VehicleType.GONDOLA_LIFT 공중 케이블카.
VehicleType.FUNICULAR 케이블로 당겨서 가파른 경사를 오르는 차량입니다. 푸니쿨라는 일반적으로 두 차량으로 구성되며, 각 차량이 다른 차량의 평형추 역할을 합니다.
VehicleType.OTHER 기타 모든 차량은 이 유형을 반환합니다.

DirectionsResults 검사

DirectionsResults 구성 요소 — DirectionsRoute, DirectionsLeg, DirectionsStepTransitDetails — 길찾기 응답을 구문 분석할 때 검사하고 사용할 수 있습니다.

중요: DirectionsRenderer 객체를 사용하는 대신 직접 대중교통 길찾기를 렌더링하는 경우, 여행 결과를 서비스하는 대중교통 기관의 이름과 URL을 표시해야 합니다.

다음 예시는 뉴욕시의 특정 관광지에 대한 도보 길찾기를 보여줍니다. 경로의 DirectionsStep을 검사하여 각 스텝에 마커를 추가하고, 해당 스텝의 지시문과 함께 InfoWindow에 정보를 첨부합니다.

도보로 찾아가는 길을 계산하고 있으므로, 별도 <div> 패널에 사용자에게 경고를 표시합니다.

var map;
var directionsDisplay;
var directionsService;
var stepDisplay;
var markerArray = [];

function initialize() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsDisplay = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsDisplay.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

HTML 본문:

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

예시 보기(directions-complex.html)

경로에 경유지 사용

DirectionsRequest에서 언급하였듯이 길찾기 서비스로 도보, 자전거, 자동차로 찾아가는 경로를 계산할 때 경유지(DirectionsWaypoint 유형)를 지정할 수도 있습니다. 경유지는 대중교통 길찾기에서 사용할 수 없습니다. 경유지를 사용하면 추가적인 위치를 통해 경로를 계산할 수 있으며, 이 경우 반환되는 경로는 주어진 경유지를 통과합니다.

waypoint는 다음과 같은 필드로 구성됩니다.

  • location(필수)은 경유지 주소를 지정합니다.
  • stopover(선택 항목)는 이 경유지가 경로의 실제 정류장인지(true), 표시된 위치를 지나가는 선호 경로인지(false) 여부를 나타냅니다. 기본적으로 stopover는 true입니다.

기본적으로 길찾기 서비스는 제공된 경유지를 통해 지정된 순서대로 경로를 계산합니다. 선택적으로 DirectionsRequestoptimizeWaypoints: true를 전달하면, 길찾기 서비스가 더 효율적인 순서로 경유지를 재배열하여 제공된 경로를 최적화할 수 있습니다. (이 최적화는 Travelling Salesman Problem 알고리즘을 적용한 것입니다.) 이동 시간은 최적화되는 주요 요소이지만 가장 효율적인 경로를 결정할 때 거리, 방향 전환 횟수 등과 같은 다른 요소도 고려해야 합니다. 길찾기 서비스가 경로를 최적화하기 위해 모든 경유지는 정거장이어야 합니다.

길찾기 서비스에게 경유지의 순서를 최적화하도록 지시하면, 그 순서가 DirectionsResult 객체 내의 waypoint_order 필드에 반환됩니다.

다음 예시는 다양한 시작 지점, 종료 지점 및 경유지를 사용하여 미국을 횡단하는 경로를 계산합니다. (여러 경유지를 선택하려면 목록에서 항목을 선택할 때 Ctrl 키를 누른 상태로 클릭합니다.) 여기에서는 routes.start_addressroutes.end_address를 검사하여 각 경로의 시작 지점과 종료 지점에 대한 텍스트를 제공합니다.

function initMap() {
  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer;
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 6,
    center: {lat: 41.85, lng: -87.65}
  });
  directionsDisplay.setMap(map);

  document.getElementById('submit').addEventListener('click', function() {
    calculateAndDisplayRoute(directionsService, directionsDisplay);
  });
}

function calculateAndDisplayRoute(directionsService, directionsDisplay) {
  var waypts = [];
  var checkboxArray = document.getElementById('waypoints');
  for (var i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true
      });
    }
  }

  directionsService.route({
    origin: document.getElementById('start').value,
    destination: document.getElementById('end').value,
    waypoints: waypts,
    optimizeWaypoints: true,
    travelMode: 'DRIVING'
  }, function(response, status) {
    if (status === 'OK') {
      directionsDisplay.setDirections(response);
      var route = response.routes[0];
      var summaryPanel = document.getElementById('directions-panel');
      summaryPanel.innerHTML = '';
      // For each route, display summary information.
      for (var i = 0; i < route.legs.length; i++) {
        var routeSegment = i + 1;
        summaryPanel.innerHTML += '<b>Route Segment: ' + routeSegment +
            '</b><br>';
        summaryPanel.innerHTML += route.legs[i].start_address + ' to ';
        summaryPanel.innerHTML += route.legs[i].end_address + '<br>';
        summaryPanel.innerHTML += route.legs[i].distance.text + '<br><br>';
      }
    } else {
      window.alert('Directions request failed due to ' + status);
    }
  });
}
<div id="map"></div>
<div id="right-panel">
<div>
<b>Start:</b>
<select id="start">
  <option value="Halifax, NS">Halifax, NS</option>
  <option value="Boston, MA">Boston, MA</option>
  <option value="New York, NY">New York, NY</option>
  <option value="Miami, FL">Miami, FL</option>
</select>
<br>
<b>Waypoints:</b> <br>
<i>(Ctrl+Click or Cmd+Click for multiple selection)</i> <br>
<select multiple id="waypoints">
  <option value="montreal, quebec">Montreal, QBC</option>
  <option value="toronto, ont">Toronto, ONT</option>
  <option value="chicago, il">Chicago</option>
  <option value="winnipeg, mb">Winnipeg</option>
  <option value="fargo, nd">Fargo</option>
  <option value="calgary, ab">Calgary</option>
  <option value="spokane, wa">Spokane</option>
</select>
<br>
<b>End:</b>
<select id="end">
  <option value="Vancouver, BC">Vancouver, BC</option>
  <option value="Seattle, WA">Seattle, WA</option>
  <option value="San Francisco, CA">San Francisco, CA</option>
  <option value="Los Angeles, CA">Los Angeles, CA</option>
</select>
<br>
  <input type="submit" id="submit">
</div>
<div id="directions-panel"></div>
</div>
#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  height: 100%;
  float: left;
  width: 70%;
  height: 100%;
}
#right-panel {
  margin: 20px;
  border-width: 2px;
  width: 20%;
  height: 400px;
  float: left;
  text-align: left;
  padding-top: 0;
}
#directions-panel {
  margin-top: 10px;
  background-color: #FFEE77;
  padding: 10px;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer;
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 6,
    center: {lat: 41.85, lng: -87.65}
  });
  directionsDisplay.setMap(map);

  document.getElementById('submit').addEventListener('click', function() {
    calculateAndDisplayRoute(directionsService, directionsDisplay);
  });
}

function calculateAndDisplayRoute(directionsService, directionsDisplay) {
  var waypts = [];
  var checkboxArray = document.getElementById('waypoints');
  for (var i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true
      });
    }
  }

  directionsService.route({
    origin: document.getElementById('start').value,
    destination: document.getElementById('end').value,
    waypoints: waypts,
    optimizeWaypoints: true,
    travelMode: 'DRIVING'
  }, function(response, status) {
    if (status === 'OK') {
      directionsDisplay.setDirections(response);
      var route = response.routes[0];
      var summaryPanel = document.getElementById('directions-panel');
      summaryPanel.innerHTML = '';
      // For each route, display summary information.
      for (var i = 0; i < route.legs.length; i++) {
        var routeSegment = i + 1;
        summaryPanel.innerHTML += '<b>Route Segment: ' + routeSegment +
            '</b><br>';
        summaryPanel.innerHTML += route.legs[i].start_address + ' to ';
        summaryPanel.innerHTML += route.legs[i].end_address + '<br>';
        summaryPanel.innerHTML += route.legs[i].distance.text + '<br><br>';
      }
    } else {
      window.alert('Directions request failed due to ' + status);
    }
  });
}

예시 보기(directions-waypoints.html).

경유지의 한도 및 제한 사항

다음과 같은 사용 한도 및 제한 사항이 적용됩니다.

  • Google Maps JavaScript API에서 길찾기 서비스를 사용할 때 허용되는 최대 경유지 수는 23 + 출발지 및 목적지입니다. 한도는 Google Maps Directions API 웹 서비스의 경우와 동일합니다.
  • Google Maps Directions API 웹 서비스의 경우 고객에게 허용되는 경유지 수는 23 + 출발지 및 목적지입니다.
  • Google Maps API 프리미엄 플랜 고객에게 허용되는 경유지 수는 23 + 출발지 및 목적지입니다.
  • 경유지는 대중교통 길찾기에서 지원되지 않습니다.

드래그 가능한 길찾기

드래그가 가능한 경우, 사용자가 DirectionsRenderer를 사용하여 표시된 자전거, 도보 또는 자동차 길찾기를 동적으로 수정할 수 있습니다. 지도에서 나타난 경로를 클릭하고 드래그하는 방식으로 경로를 선택하고 변경할 수 있습니다. 렌더러의 디스플레이가 드래그 가능한 길찾기를 허용하는지 여부를 나타내려면 draggable 속성을 true로 설정합니다. 대중교통 길찾기는 드래그할 수 없습니다.

길찾기를 드래그할 수 있는 경우, 사용자가 렌더링된 결과의 경로(또는 경유지)에서 임의 지점을 선택하고 나타난 구성 요소를 새로운 위치로 옮길 수 있습니다. DirectionsRenderer는 수정된 경로를 보여주기 위해 동적으로 업데이트됩니다. 누름을 해제하면 임시 경유지가 지도에 추가됩니다(작은 흰색 마커로 표시). 경로 세그먼트를 선택하여 이동하면 해당 경로 구간이 변경되고, 경유지 마커(시작 지점 및 종료 지점 포함)를 선택하여 이동하면 해당 경유지를 지나는 경로 구간이 변경됩니다.

드래그 가능한 길찾기는 클라이언트측에서 수정되고 렌더링되기 때문에, 사용자가 표시된 길찾기를 변경할 경우 알림을 받기 위해 DirectionsRenderer에서 directions_changed 이벤트를 모니터링하고 처리하기를 원할 수도 있습니다.

다음 코드는 호주 서해안의 퍼스에서 동해안의 시드니까지의 이동 경로를 나타냅니다. 이 코드는 directions_changed 이벤트를 모니터링하고 모든 여정 구간의 전체 거리를 업데이트합니다.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -24.345, lng: 134.46}  // Australia.
  });

  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer({
    draggable: true,
    map: map,
    panel: document.getElementById('right-panel')
  });

  directionsDisplay.addListener('directions_changed', function() {
    computeTotalDistance(directionsDisplay.getDirections());
  });

  displayRoute('Perth, WA', 'Sydney, NSW', directionsService,
      directionsDisplay);
}

function displayRoute(origin, destination, service, display) {
  service.route({
    origin: origin,
    destination: destination,
    waypoints: [{location: 'Adelaide, SA'}, {location: 'Broken Hill, NSW'}],
    travelMode: 'DRIVING',
    avoidTolls: true
  }, function(response, status) {
    if (status === 'OK') {
      display.setDirections(response);
    } else {
      alert('Could not display directions due to: ' + status);
    }
  });
}

function computeTotalDistance(result) {
  var total = 0;
  var myroute = result.routes[0];
  for (var i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }
  total = total / 1000;
  document.getElementById('total').innerHTML = total + ' km';
}
<div id="map"></div>
<div id="right-panel">
  <p>Total Distance: <span id="total"></span></p>
</div>
#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  height: 100%;
  float: left;
  width: 63%;
  height: 100%;
}
#right-panel {
  float: right;
  width: 34%;
  height: 100%;
}
.panel {
  height: 100%;
  overflow: auto;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -24.345, lng: 134.46}  // Australia.
  });

  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer({
    draggable: true,
    map: map,
    panel: document.getElementById('right-panel')
  });

  directionsDisplay.addListener('directions_changed', function() {
    computeTotalDistance(directionsDisplay.getDirections());
  });

  displayRoute('Perth, WA', 'Sydney, NSW', directionsService,
      directionsDisplay);
}

function displayRoute(origin, destination, service, display) {
  service.route({
    origin: origin,
    destination: destination,
    waypoints: [{location: 'Adelaide, SA'}, {location: 'Broken Hill, NSW'}],
    travelMode: 'DRIVING',
    avoidTolls: true
  }, function(response, status) {
    if (status === 'OK') {
      display.setDirections(response);
    } else {
      alert('Could not display directions due to: ' + status);
    }
  });
}

function computeTotalDistance(result) {
  var total = 0;
  var myroute = result.routes[0];
  for (var i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }
  total = total / 1000;
  document.getElementById('total').innerHTML = total + ' km';
}

예시 보기(directions-draggable.html).

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

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