모든 준비를 마쳤습니다!

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

Google Maps Directions API 활성화

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

  1. 프로젝트 생성 또는 선택
  2. Google Maps Directions API 활성화
  3. 적합한 키 생성
계속

개발자 가이드

Google Maps Directions API는 HTTP 요청을 사용하여 위치 간의 찾아가는 길을 계산하는 서비스입니다.

이 서비스는 또한 클라이언트측 Google Maps JavaScript API의 일부로 제공되거나 서버측에서 Java Client, Python Client, Go Client 및 Node.js Client for Google Maps Services와 함께 사용됩니다. 참고: 서비스 사용 방법에 상관없이 동일한 일일 사용 제한이 적용됩니다. 허용되는 일일 요청 수는 클라이언트측 쿼리와 서버측 쿼리의 합계로 계산합니다.

이 문서는 Google Maps API 중 하나에서 제공하는 지도 내에서 길찾기 데이터를 계산하기를 원하는 웹사이트 및 모바일 개발자를 위한 것입니다. 이 문서에서는 API 사용 방법과 사용 가능한 매개변수에 대한 참조 자료를 소개합니다.

소개

이 동영상은 사람들이 Google Maps Directions API를 사용하여 길을 찾는 방법을 보여줍니다. 이 동영상에서는 사용자가 모바일 앱에서 API를 사용 중인 경우, 서버를 통해 웹 서비스를 프록싱하여 API 키를 보호하는 방법에 대해 설명합니다.

Directions API로 다음 작업을 수행할 수 있습니다.

  • 대중교통, 자동차, 도보, 자전거 등 여러 이동 모드에 대한 찾아가는 길을 검색합니다.
  • 일련의 경유지를 사용하여 여러 찾아가는 길을 반환합니다.
  • 출발지, 목적지 및 경유지를 텍스트 문자열(예: "Chicago, IL" 또는 "Darwin, NT, Australia"), 위도/경도 좌표 또는 장소 ID로 지정합니다.

찾아가는 길 계산은 시간과 리소스가 많이 소모되는 작업입니다. 가능하면 (여기에 설명된 서비스를 사용하여) 알려진 주소를 미리 계산하고, 그 결과를 별도의 임시 캐시에 저장하세요.

참고: 이 서비스는 사용자 입력에 실시간으로 응답하도록 고안되지 않았습니다. (예를 들어, 사용자 인터페이스 요소 내에서) 동적인 찾아가는 길 계산은 Google Maps JavaScript API 길찾기 서비스의 문서를 참조하세요.

Directions API 개발을 시작하기 전에 인증 요구사항(API 키 필요) 및 API 사용 제한을 검토하세요.

길찾기 요청

Google Maps Directions API 요청의 형식은 다음과 같습니다.

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

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

  • json(권장)은 출력을 JSON(JavaScript Object Notation) 형식으로 나타냅니다.
  • xml은 출력을 XML로 나타냅니다.

참고: URL은 유효하도록 적절하게 인코딩해야 하며 모든 웹 서비스에 대해 8192자로 제한됩니다. URL을 구성할 때 이 제한을 알아야 합니다.

HTTPS 또는 HTTP

보안은 중요하므로 특히 사용자 위치와 같은 민감한 사용자 데이터를 요청에 포함하는 애플리케이션의 경우, 가급적 HTTPS를 사용하는 것이 좋습니다. HTTPS 암호화를 사용하면 애플리케이션의 보안이 강화되고 스누핑이나 변조에 대한 저항력도 강화됩니다.

HTTPS를 사용할 수 없는 경우 HTTP를 통해 Google Maps Directions API에 액세스하려면 다음을 사용합니다.

http://maps.googleapis.com/maps/api/directions/outputFormat?parameters

요청 매개변수

일부 매개변수는 필수인 반면 일부 매개변수는 선택 사항입니다. URL 표준 형식과 마찬가지로, 모든 매개변수는 앰퍼샌드(&) 문자를 사용하여 구분합니다. 매개변수 및 가능한 값 목록은 아래와 같습니다.

필수 매개변수

  • origin — 길찾기 계산에 사용할 주소, 텍스트 위도/경도 값 또는 장소 ID입니다.
    • 주소를 전달하는 경우 길찾기 서비스는 해당 문자열을 지오코딩하고 위도/경도 좌표로 변환하여 찾아가는 길을 계산합니다. 이 좌표는 Google Maps Geocoding API에서 반환되는 좌표와 다를 수도 있습니다(예: 건물 중심이 아니라 건물 입구).
      origin=24+Sussex+Drive+Ottawa+ON
    • 좌표를 전달하는 경우 해당 좌표를 변경 없이 사용하여 찾아가는 길을 계산합니다. 위도와 경도 값 사이에 공백이 없도록 하십시오.
      origin=41.43206,-81.38992
    • 장소 ID는 place_id:를 접두사로 붙여야 합니다. 장소 ID는 요청에 API 키 또는 Google Maps API 프리미엄 플랜 클라이언트 ID가 포함된 경우에만 지정될 수 있습니다. Google Maps Geocoding API 및 Google Places API(장소 자동완성 포함)에서 장소 ID를 검색할 수 있습니다. 장소 자동완성에서 장소 ID를 사용하는 예는 장소 자동완성 및 길찾기를 참조하세요. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참조하세요.
      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
  • destination — 찾아가는 길을 계산할 주소, 텍스트 위도/경도 값 또는 장소 ID입니다. destination 매개변수의 옵션은 위에 설명된 origin 매개변수의 옵션과 동일합니다.
  • key — 애플리케이션의 API 키. 이 키는 할당량 관리를 위해 애플리케이션을 식별합니다. 키 가져오기 방법에 대해 알아봅니다.

    참고: Google Maps API 프리미엄 플랜 고객은 Directions 요청에서 API 키를 사용하거나 유효한 클라이언트 ID와 디지털 서명을 사용할 수 있습니다. 자세한 내용은 프리미엄 플랜 고객의 인증 매개변수를 참조하세요.

선택적 매개변수

  • mode (기본값은 driving) — 찾아가는 길을 계산할 때 사용할 이동 모드를 지정합니다. 유효한 값과 기타 요청 세부정보는 이동 모드에서 지정됩니다.
  • waypoints — 일련의 경유지의 지정합니다. 경유지는 지정된 위치를 지나가도록 경로를 변경합니다. 경유지는 위도/경도 좌표, 인코딩된 폴리라인, 장소 ID 또는 지오코딩될 주소로 지정됩니다. 인코딩된 폴리라인은 enc:라는 접두사와 그 뒤에 콜론(:)을 사용해야 합니다. 장소 ID는 place_id:를 접두사로 붙여야 합니다. 장소 ID는 요청에 API 키 또는 Google Maps API 프리미엄 플랜 클라이언트 ID가 포함된 경우에만 지정될 수 있습니다. 경유지는 자동차, 도보 및 자전거 길찾기에만 지원됩니다. 경유지에 대한 자세한 내용은 아래의 경유지 가이드를 참조하세요.
  • alternativestrue로 설정하면, 길찾기 서비스가 둘 이상의 대체 경로를 응답으로 제공할 수 있습니다. 참고로, 대체 경로를 제공하면 서버의 응답 시간이 늘어날 수도 있습니다.
  • avoid — 계산된 경로가 표시된 기능을 피해가야 함을 나타냅니다. 이 매개변수는 다음과 같은 인수를 지원합니다:
    • tolls는 계산된 경로가 유료 도로/다리를 피해가야 함을 나타냅니다.
    • highways는 계산된 경로가 고속도로를 피해가야 함을 나타냅니다.
    • ferries는 계산된 경로가 페리를 피해가야 함을 나타냅니다.
    • indoor는 계산된 경로가 도보 및 대중교통 길찾기에 필요한 옥내 계단을 피해가야 함을 나타냅니다. API 키 또는 Google Maps API 프리미엄 플랜 클라이언트 ID가 포함된 요청만이 기본적으로 옥내 계단을 수신합니다.
    자세한 내용은 아래의 경로 제한을 참조하세요.
  • language — 결과 반환 시 사용되는 언어.
    • 지원되는 언어 목록을 참조하세요. 지원되는 언어는 자주 업데이트되므로 목록이 완전하지 않을 수 있습니다.
    • language를 지정하지 않으면 API는 Accept-Language 헤더에 지정된 기본 언어를 사용하거나 요청을 보낸 도메인의 기본 언어를 사용하려고 시도합니다.
    • API는 사용자와 현지인이 모두 읽을 수 있는 거리 주소를 제공하려고 최선을 다합니다. 이를 위해 API는 기본 언어를 준수하면서 필요한 경우 사용자가 읽을 수 있는 스크립트로 음차한 현지 언어로 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성 요소는 모두 첫 번째 구성 요소에서 선택한 동일한 언어로 반환됩니다.
    • 기본 언어로 이름을 사용할 수 없는 경우 API는 가장 유사한 일치 항목을 사용합니다.
    • 기본 언어는 API가 반환하려고 선택한 결과 집합과 반환 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 유효하거나 유효하지 않을 수 있는 동의어 또는 거리 유형에 대한 약어와 같이 언어에 따라 다르게 약어를 해석합니다. 예를 들어, utcatér는 헝가리어로 거리에 대한 동의어입니다.
  • units — 결과 표시에 사용할 단위 체계를 지정합니다. 유효한 값은 아래의 단위 체계에서 지정됩니다.
  • region — 지역 코드를 지정합니다. 이 코드는 ccTLD("최상위 도메인") 두 문자 값으로 지정됩니다. (자세한 내용은 아래의 지역 편중을 참조하세요.)
  • arrival_time — 대중교통 길찾기의 경우 1970년 1월 1일 자정(UTC) 이후의 원하는 도착 시간을 초 단위로 지정합니다. departure_time 또는 arrival_time을 지정할 수 있지만, 둘 모두를 지정할 수는 없습니다. 참고로, arrival_time은 정수로 지정되어야 합니다.
  • departure_time — 원하는 출발 시간을 지정합니다. 1970년 1월 1일 자정(UTC) 이후의 시간을 초 단위의 정수로 지정할 수 있습니다. 또는, now 값을 지정할 수 있습니다. 이 값은 출발 시간을 현재 시간(가장 가까운 초로 보정)으로 설정합니다. 출발 시간은 다음 두 경우에 지정될 수 있습니다.
    • 이동 모드가 대중교통인 요청의 경우: departure_time 또는 arrival_time 중 하나를 선택적으로 지정할 수 있습니다. 둘 다 지정되지 않은 경우 departure_time은 기본적으로 now입니다. (즉, 출발 시간은 기본적으로 현재 시간이 됩니다.)
    • 이동 모드가 자동차인 요청의 경우: 교통 상황을 고려하여 경로와 이동 시간(응답 필드: duration_in_traffic)을 수신하려면 departure_time을 지정할 수 있습니다. 이 옵션은 올바른 API 키나 올바른 Google Maps API 프리미엄 플랜 클라이언트 ID 및 서명이 포함된 요청에만 사용할 수 있습니다. departure_time은 현재 시간 또는 미래의 특정 시간으로 설정되어야 합니다. 이 시간은 과거가 될 수 없습니다.
  • traffic_model(기본값 best_guess) — 교통량을 고려한 시간을 계산할 때 사용할 가정을 지정합니다. 이 설정은 응답에서 duration_in_traffic 필드에 반환되는 값에 영향을 미치며, 여기에는 과거의 평균 교통량에 따른 예상 시간이 포함됩니다. traffic_model 매개변수는 요청에 departure_time이 포함된 자동차 길찾기의 경우 또는 요청에 API 키 또는 Google Maps API 프리미엄 플랜 클라이언트 ID가 포함된 경우에만 지정될 수 있습니다. 이 매개변수에 사용 가능한 값은 다음과 같습니다.
    • 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 — 선호하는 대중교통 모드를 하나 이상 지정합니다. 이 매개변수는 요청에 API 키 또는 Google Maps API 프리미엄 플랜 클라이언트 ID가 포함된 경우에만 그리고 대중교통 길찾기에 대해서만 지정될 수 있습니다. 매개변수는 다음과 같은 인수를 지원합니다.
    • bus는 계산된 경로가 버스 이동을 선호함을 나타냅니다.
    • subway는 계산된 경로가 지하철 이동을 선호함을 나타냅니다.
    • train은 계산된 경로가 기차 이동을 선호함을 나타냅니다.
    • tram은 계산된 경로가 전차와 경전철 이동을 선호함을 나타냅니다.
    • rail은 계산된 경로가 기차, 전차, 경전철 및 지하철 이동을 선호함을 나타냅니다. 이는 transit_mode=train|tram|subway와 동등합니다.
  • transit_routing_preference — 대중교통 경로에 대한 기본 설정을 지정합니다. 이 매개변수를 사용하면, API에 의해 선택되는 기본 최적 경로를 수락하는 대신, 반환되는 옵션을 편중할 수 있습니다. 이 매개변수는 요청에 API 키 또는 Google Maps API 프리미엄 플랜 클라이언트 ID가 포함된 경우에만 그리고 대중교통 길찾기에 대해서만 지정될 수 있습니다. 매개변수는 다음과 같은 인수를 지원합니다.
    • less_walking은 계산된 경로가 제한된 도보량을 선호함을 나타냅니다.
    • fewer_transfers는 계산된 경로가 제한된 환승 횟수를 선호함을 나타냅니다.

예시 길찾기 요청

다음 요청은 온타리오 토론토에서 퀘벡 몬트리올까지의 자동차 길찾기를 반환합니다.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY

modeavoid 매개변수를 변경하면, 주요 고속도로를 피해서 경치가 멋진 자전거 여행을 위한 길찾기를 반환하도록 초기 요청을 수정할 수 있습니다.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&key=YOUR_API_KEY

다음 요청은 뉴욕 브루클린에서 뉴욕 퀸즈까지의 대중교통 길찾기를 검색합니다. 이 요청에서는 departure_time을 지정하지 않으므로, 출발 시간은 기본적으로 현재 시간이 됩니다.

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&key=YOUR_API_KEY

다음 요청은 특정한 출발 시간을 포함합니다.

참고: 이 예에서 출발 시간은 2012년 7월 30일 오전 9시 45분으로 지정됩니다. 오류를 피하려면, 요청을 제출하기 전에 미래의 시간으로 매개변수를 변경해야 합니다.

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&departure_time=1343641500&mode=transit&key=YOUR_API_KEY

다음 요청은 장소 ID를 사용하여 영국 글래스고에서 영국 퍼스까지의 자동차 길찾기를 반환합니다.

https://maps.googleapis.com/maps/api/directions/json?origin=place_id:ChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id:ChIJA01I-8YVhkgRGJb0fW4UX7Y&key=YOUR_API_KEY

이동 모드

찾아가는 길을 계산할 때 사용할 이동 mode를 지정할 수 있습니다. 기본적으로 길찾기는 driving 길찾기로 계산됩니다. 다음과 같은 이동 모드가 지원됩니다.

  • driving(기본값)은 도로망을 사용하는 표준 자동차 길찾기를 나타냅니다.
  • walking은 보행자 경로 및 인도(있는 경우)를 경유하는 도보 길찾기를 요청합니다.
  • bicycling은 자전거 경로 및 선호하는 거리(있는 경우)를 경유하는 자전거 길찾기를 요청합니다.
  • transit은 대중교통 경로(있는 경우)를 경유하는 길찾기를 요청합니다. 모드를 transit으로 설정하면, departure_time 또는 arrival_time을 선택적으로 지정할 수 있습니다. 둘 다 지정되지 않은 경우 departure_time은 기본적으로 now입니다. (즉, 출발 시간은 기본적으로 현재 시간이 됩니다.) 또한 transit_mode 및/또는 transit_routing_preference를 선택적으로 포함할 수 있습니다.

참고: 때로는 도보 및 자전거 길찾기에 불명확한 보행자 또는 자전거 경로가 포함될 수 있으므로, 이러한 길찾기에서는 반환 결과에 warnings를 반환하여 사용자에게 표시해야 합니다.

경유지

Google Maps Directions API를 사용하여 경로를 계산할 때 운전, 도보 또는 자전거 길찾기에 대한 경유지도 지정할 수도 있습니다. 경유지는 대중교통 길찾기에서 사용할 수 없습니다. 경유지를 사용하여 추가적인 위치를 통해 경로를 계산할 수 있으며, 이 경우 반환되는 경로에는 지정된 각 경유지에 중간 기착이 포함됩니다.

waypoints 매개변수에 경유지를 지정합니다.

  • 파이프 문자(|)로 구분된 한 개 이상의 위치를 주소, 위도/경도 좌표 또는 장소 ID의 형식으로 제공할 수 있습니다.
    • 주소를 전달하는 경우 길찾기 서비스는 해당 문자열을 지오코딩하고 위도/경도 좌표로 변환하여 찾아가는 길을 계산합니다. 이 좌표는 Google Maps Geocoding API에서 반환되는 좌표와 다를 수도 있습니다(예: 건물 중심이 아니라 건물 입구).
    • 위도/경도 좌표를 전달하는 경우 해당 좌표를 변경 없이 사용하여 찾아가는 길을 계산합니다. 위도와 경도 값 사이에 공백이 없도록 하십시오.
    • 장소 ID를 제공하는 경우 place_id:라는 접두사를 붙여야 합니다. 요청이 API 키 또는 Google Maps API 프리미엄 플랜 클라이언트 ID를 포함하는 경우에는 장소 ID만 지정할 수 있습니다. Google Maps Geocoding API 및 Google Places API(장소 자동완성 포함)에서 장소 ID를 검색할 수 있습니다. 장소 자동완성에서 장소 ID를 사용하는 예는 장소 자동완성 및 길찾기를 참조하세요. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참조하세요.
  • 또는 인코딩된 폴리라인 알고리즘을 사용하여 인코딩된 좌표 집합을 제공할 수 있습니다. 이는 인코딩된 폴리라인을 사용하는 경우 URL이 훨씬 짧으므로 경유지가 많은 경우에 특히 유용합니다.
    • 인코딩된 폴리라인은 enc:라는 접두사와 그 뒤에 콜론(:)을 사용해야 합니다(예: waypoints=enc:gfo}EtohhU:).
    • 또한 파이프 문자(|)로 구분된 복수의 인코딩된 폴리라인을 포함할 수도 있습니다. 예: waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|via:enc:udymA{~bxM:

다음 URL은 매사추세츠 보스톤(Boston, MA)과 매사추세츠 콩코드(Concord, MA) 사이의 경로에서 찰스타운(Charlestown)과 렉싱턴(Lexington)을 순서대로 중간 기착하는 길찾기 요청을 시작합니다.

https://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|Lexington,MA&key=YOUR_API_KEY

요청에 있는 각 경유지의 경우, 길찾기 응답에는 여정의 해당 구간에 대한 세부정보를 제공하는 추가적인 항목이 legs 배열에 포함됩니다.

중간 기착을 추가하지 않고 경유지를 사용하여 경로를 지정하려면, 경유지에 via: 접두사를 붙입니다. via: 접두사가 붙은 경유지는 항목을 legs 배열에 추가하지 않으며, 그 대신 제공된 경유지를 통과하는 경로를 지정합니다.

다음 URL은 정차없이 렉싱턴을 통과하는 경로를 지정하도록 이전 요청을 수정합니다.

https://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|via:Lexington,MA&key=YOUR_API_KEY

via: 접두사는 사용자가 지도에서 경유지를 끌어서 경로를 생성할 때 가장 효과적입니다. 이렇게 하면 사용자가 최종 경로가 실시간으로 어떻게 나타날지 알 수 있으며, Google Maps Directions API에 액세스가 가능한 위치에 경유지가 배치되도록 보장할 수 있습니다.

다음 URL은 위도/경도 좌표를 사용하여 경유지를 요청합니다.

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:-37.81223%2C144.96254%7Cvia:-34.92788%2C138.60008&key=YOUR_API_KEY

다음은 인코딩된 폴리라인을 사용한 동일한 요청입니다.

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:enc:lexeF{~wsZejrPjtye@:&key=YOUR_API_KEY

경유지 최적화

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

경유지의 순서를 최적화하도록 길찾기 서비스에게 지시를 내리면, 그 순서가 routes 객체 내의 waypoint_order 필드에 반환됩니다. waypoint_order 필드는 제로 기준인 값을 반환합니다.

다음 예에서는 경로 최적화를 사용하여 사우스오스트레일리아 애들레이드에서 사우스오스트레일리아의 여러 주요 와인 산지까지의 도로 이동 경로를 계산합니다.

https://maps.googleapis.com/maps/api/directions/json?origin=Adelaide,SA&destination=Adelaide,SA&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA&key=YOUR_API_KEY

계산된 경로를 살펴보면 이 경로가 다음과 같은 경유지 순서를 사용하여 계산됨을 알 수 있습니다:

"waypoint_order": [ 1, 0, 2, 3 ]

제한

특정한 제한을 준수하여 찾아가는 길이 계산될 수도 있습니다. 제한은 avoid 매개변수와 이 매개변수의 인수를 사용하여 표시되며, 인수는 피하려는 제한을 나타냅니다. 다음과 같은 제한이 지원됩니다.

  • avoid=tolls
  • avoid=highways
  • avoid=ferries

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

참고: 제한을 더 추가하더라도 제한된 기능이 포함된 경로가 제외되는 것은 아니며, 더 나은 경로를 찾기 위해 결과를 편중할 뿐입니다.

단위 체계

길찾기 결과에는 distance 필드 내에 text가 포함되며, 이 텍스트가 사용자에게 표시되어 경로의 특정 "스텝"에 대한 거리를 알려줄 수 있습니다. 기본적으로, 이 텍스트는 출발지 국가 또는 지역의 단위 체계를 사용합니다.

예를 들어, "IL 시카고"에서 "ONT 토론토"까지의 경로는 마일 단위로 결과를 표시하는 반면, 그 반대 경로는 킬로미터 단위로 결과를 표시합니다. 요청의 units 매개변수 내에 명시적으로 단위를 설정하고 다음 값 중 하나를 전달하여 이 단위 체계를 재정의할 수 있습니다.

  • metric은 미터 체계를 사용하도록 지정합니다. 텍스트 거리는 킬로미터와 미터를 사용하여 반환됩니다.
  • imperial은 임페리얼(영국) 체계를 사용하도록 지정합니다. 텍스트 거리는 마일과 피트를 사용하여 반환됩니다.

참고: 이 단위 체계 설정은 distance 필드 내에 표시되는 text에만 영향을 미칩니다. distance 필드는 항상 미터로 표현되는 values도 포함합니다.

지역 편중

또한, region 매개변수를 사용하여 특정 지역으로 편중된 결과를 반환하도록 길찾기 서비스를 설정할 수도 있습니다. 이 매개변수는 ccTLD(국가 코드 최상위 도메인) 인수를 통해 지역 편중을 지정합니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하며, 몇몇 눈에 띄는 예외가 있습니다. 예를 들어, 영국의 ccTLD는 "uk"(.co.uk)인 반면 ISO 3166-1 코드는 "gb"입니다(기술적으로 Great Britain과 Northern Ireland 연방국" 엔터티).

주요 Google 지도 애플리케이션이 자동차 길찾기를 시작한 모든 도메인을 활용할 수 있습니다.

예를 들어, "톨레도"에서 "마드리드"까지의 길찾기 요청에서 "톨레도"는 스페인 도시로 해석되기 때문에 regiones로 설정된 경우에 결과를 반환합니다.

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&key=YOUR_API_KEY

{
  "status": "OK",
  "routes": [ {
    "summary": "AP-41",
    "legs": [ {
        ...
    } ],
    "copyrights": "Map data ©2010 Europa Technologies, Tele Atlas",
    "warnings": [ ],
    "waypoint_order": [ ]
  } ]
}

region 매개변수가 없이 전송된 "톨레도"에서 "마드리드"까지의 길찾기 요청은 "톨레도"가 오하이오의 도시로 해석되기 때문에 어떤 결과도 반환하지 않습니다.

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY

{
  "status": "ZERO_RESULTS",
  "routes": [ ]
}

길찾기 응답

길찾기 응답은 URL 요청 경로내 output 플래그에서 표시한 형식으로 반환됩니다.

샘플 응답

아래는 샘플 HTTP 요청으로, MO 조플린과 OK 오클라호마시티의 두 경유지를 통과하는 IL 시카고에서 CA 로스앤젤레스까지의 경로를 계산합니다.

https://maps.googleapis.com/maps/api/directions/json?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&key=YOUR_API_KEY

위의 예시는 JSON 출력을 요청합니다. 또한 XML 출력을 요청할 수도 있습니다. 아래의 탭을 클릭하여 샘플 JSON 및 XML 응답을 살펴보세요.

길찾기 결과는 상당히 장황할 수 있으므로, 명확성을 위해 응답 내의 반복되는 요소는 생략되었습니다.

JSON
{
  "status": "OK",
  "geocoded_waypoints" : [
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ7cv00DwsDogRAMDACa2m4K8",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ69Pk6jdlyIcRDqM1KDY3Fpg",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJgdL4flSKrYcRnTpP0XQSojM",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJE9on3F3HwoAR9AhGJW_fL-I",
        "types" : [ "locality", "political" ]
     }
  ],
  "routes": [ {
    "summary": "I-40 W",
    "legs": [ {
      "steps": [ {
        "travel_mode": "DRIVING",
        "start_location": {
          "lat": 41.8507300,
          "lng": -87.6512600
        },
        "end_location": {
          "lat": 41.8525800,
          "lng": -87.6514100
        },
        "polyline": {
          "points": "a~l~Fjk~uOwHJy@P"
        },
        "duration": {
          "value": 19,
          "text": "1 min"
        },
        "html_instructions": "Head \u003cb\u003enorth\u003c/b\u003e on \u003cb\u003eS Morgan St\u003c/b\u003e toward \u003cb\u003eW Cermak Rd\u003c/b\u003e",
        "distance": {
          "value": 207,
          "text": "0.1 mi"
        }
      },
      ...
      ... additional steps of this leg
    ...
    ... additional legs of this route
      "duration": {
        "value": 74384,
        "text": "20 hours 40 mins"
      },
      "distance": {
        "value": 2137146,
        "text": "1,328 mi"
      },
      "start_location": {
        "lat": 35.4675602,
        "lng": -97.5164276
      },
      "end_location": {
        "lat": 34.0522342,
        "lng": -118.2436849
      },
      "start_address": "Oklahoma City, OK, USA",
      "end_address": "Los Angeles, CA, USA"
    } ],
    "copyrights": "Map data ©2010 Google, Sanborn",
    "overview_polyline": {
      "points": "a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\\~mbDzeVh_Wr|Efc\\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC"
    },
    "warnings": [ ],
    "waypoint_order": [ 0, 1 ],
    "bounds": {
      "southwest": {
        "lat": 34.0523600,
        "lng": -118.2435600
      },
      "northeast": {
        "lat": 41.8781100,
        "lng": -87.6297900
      }
    }
  } ]
}

일반적으로 길찾기 조회 시에 routes 배열의 단 한 항목만 반환되지만, alternatives=true를 전달하는 경우에는 길찾기 서비스가 여러 경로를 반환할 수도 있습니다.

참고로, 결과에서 값을 추출하려는 경우에는 이 결과를 종합적으로 구문 분석해야 합니다. JSON 구문 분석은 비교적 쉽습니다. 권장되는 디자인 패턴을 확인하려면 JSON 구문 분석을 참조하세요.

XML
<DirectionsResponse>
 <status>OK</status>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ7cv00DwsDogRAMDACa2m4K8</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ69Pk6jdlyIcRDqM1KDY3Fpg</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgdL4flSKrYcRnTpP0XQSojM</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJE9on3F3HwoAR9AhGJW_fL-I</place_id>
 </geocoded_waypoint>
 <route>
  <summary>I-40 W</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8507300</lat>
     <lng>-87.6512600</lng>
    </start_location>
    <end_location>
     <lat>41.8525800</lat>
     <lng>-87.6514100</lng>
    </end_location>
    <polyline>
     <points>a~l~Fjk~uOwHJy@P</points>
    </polyline>
    <duration>
     <value>19</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Head <b>north</b> on <b>S Morgan St</b> toward <b>W Cermak Rd</b></html_instructions>
    <distance>
     <value>207</value>
     <text>0.1 mi</text>
    </distance>
   </step>
   ...
   ... additional steps of this leg
  ...
  ... additional legs of this route
   <duration>
    <value>74384</value>
    <text>20 hours 40 mins</text>
   </duration>
   <distance>
    <value>2137146</value>
    <text>1,328 mi</text>
   </distance>
   <start_location>
    <lat>35.4675602</lat>
    <lng>-97.5164276</lng>
   </start_location>
   <end_location>
    <lat>34.0522342</lat>
    <lng>-118.2436849</lng>
   </end_location>
   <start_address>Oklahoma City, OK, USA</start_address>
   <end_address>Los Angeles, CA, USA</end_address>
  <copyrights>Map data ©2010 Google, Sanborn</copyrights>
  <overview_polyline>
   <points>a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\~mbDzeVh_Wr|Efc\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC</points>
  </overview_polyline>
  <waypoint_index>0</waypoint_index>
  <waypoint_index>1</waypoint_index>
  <bounds>
   <southwest>
    <lat>34.0523600</lat>
    <lng>-118.2435600</lng>
   </southwest>
   <northeast>
    <lat>41.8781100</lat>
    <lng>-87.6297900</lng>
   </northeast>
  </bounds>
 </route>
</DirectionsResponse>

참고로, XML 응답은 단일 <DirectionsResponse> 요소와 다음과 같은 최상위 요소로 구성됩니다.

  • <status>는 요청의 메타데이터를 포함합니다. 아래의 상태 코드를 참조하세요.
  • 경유지당 하나의 <geocoded_waypoint>, 출발지 및 목적지, 이러한 정보의 지오코딩 결과에 대한 세부정보. 비어 있는 <geocoded_waypoint/> 요소가 있을 수 있습니다. 아래의 지오코딩된 경유지를 참조하세요.
  • 0개 이상의 <route> 요소. 각 요소에는 출발지 및 목적지 사이의 단일 라우팅 정보 집합이 포함됩니다.

어떤 이유로 서비스에 xml이 꼭 필요한 경우가 아니라면 json을 기본 출력 플래그로 사용하는 것이 좋습니다. XML 트리를 처리할 때는 올바른 노드와 요소를 참조하도록 주의해야 합니다. 출력 처리에 권장되는 디자인 패턴을 확인하려면 XPath로 XML 구문 분석을 참조하세요.

이 문서의 나머지 부분에서는 JSON 구문을 사용합니다. 대부분의 경우, 문서에서 개념 또는 필드 이름을 설명하기 위한 경우 출력 형식은 중요치 않습니다. 그러나, 다음과 같은 미세한 차이에 유의하세요.

  • XML 결과는 루트 <DirectionsResponse> 요소에 래핑됩니다.
  • JSON은 여러 개의 요소가 있는 항목을 복수의 배열(예: stepslegs)로 나타내는 반면, XML은 여러 개의 단일 요소(예: <step><leg>)를 사용하여 나타냅니다.
  • JSON은 경유지 순서를 waypoint_order 필드를 통해 나타내는 반면, XML은 개별 <waypoint_index> 요소를 사용하여 나타냅니다.
  • JSON에서는 빈 요소가 빈 배열로 나타나지만, XML에서는 이러한 요소가 없습니다. 결과를 생성하지 않는 응답은 JSON에서 빈 routes 배열을 반환하지만, XML에서는 <route> 요소가 없습니다.

길찾기 응답 요소

길찾기 응답은 다음과 같은 루트 요소를 포함합니다.

  • "status"는 요청의 메타데이터를 포함합니다. 아래의 상태 코드를 참조하세요.
  • geocoded_waypoints는 출발지, 목적지 및 경유지의 지오코딩에 대한 세부정보가 있는 배열을 포함합니다. 아래의 지오코딩된 경유지를 참조하세요.
  • routes는 출발지에서 목적지까지의 경로 배열을 포함합니다. 아래의 경로를 참조하세요. 경로는 중첩된 구간스텝으로 구성됩니다.
  • available_travel_modes는 사용 가능한 이동 모드의 배열을 포함합니다. 요청이 이동 mode를 지정하고 결과를 얻지 못할 때 이 필드가 반환됩니다. 해당 배열에는 지정된 경유지 집합의 국가에서 사용 가능한 이동 모드가 포함됩니다. 이 필드는 하나 이상의 경유지가 via: 경유지인 경우 반환되지 않습니다. 자세한 내용은 아래를 참조하세요.

상태 코드

길찾기 응답 객체의 status 필드는 요청의 상태를 포함하며, 길찾기 서비스가 실패한 원인을 추적하는 데 도움이 되는 디버깅 정보를 포함할 수 있습니다. status 필드는 다음 값을 포함할 수 있습니다.

  • OK는 응답이 올바른 result를 포함함을 나타냅니다.
  • NOT_FOUND는 요청의 출발지, 목적지 또는 경유지에 지정된 위치 중 최소 한 개 이상을 지오코딩할 수 없음을 나타냅니다.
  • ZERO_RESULTS는 출발지와 목적지 사이에 경로를 찾을 수 없음을 나타냅니다.
  • MAX_WAYPOINTS_EXCEEDED는 너무 많은 waypoints가 요청에서 제공되었음을 나타냅니다. Google Maps Directions API를 웹 서비스로 사용하거나 Google Maps JavaScript API에서 길찾기 서비스를 사용하는 애플리케이션의 경우 허용되는 최대 waypoints 수는 23개이며 출발지와 목적지가 별도로 있습니다. Google Maps API 프리미엄 플랜 고객은 최대 23개의 경유지와 별도의 출발지와 목적지를 포함하는 요청을 제출할 수 있습니다.
  • INVALID_REQUEST는 제공된 요청이 잘못되었음을 나타냅니다. 이 상태의 일반적인 원인으로는 잘못된 매개변수나 매개변수 값이 포함됩니다.
  • OVER_QUERY_LIMIT는 허용된 시간 기간 내에 서비스가 애플리케이션에서 너무 많은 요청을 수신했음을 나타냅니다.
  • REQUEST_DENIED는 서비스가 애플리케이션의 길찾기 서비스 사용을 거부했음을 나타냅니다.
  • UNKNOWN_ERROR는 서버 오류로 인해 길찾기 요청을 처리할 수 없음을 나타냅니다. 다시 시도하면 요청이 성공할 수도 있습니다.

오류 메시지

상태 코드가 OK 이외인 경우, 길찾기 응답 객체 내에 추가적인 error_message 필드가 있을 수 있습니다. 이 필드에는 지정된 상태 코드가 제시된 이유에 대한 상세정보가 포함됩니다.

참고: 이 필드는 항상 존재하는 것은 아니며 내용이 변경될 수 있습니다.

지오코딩된 경유지

모든 경유지, 출발지 및 목적지의 지오코딩에 대한 상세정보를 (JSON) geocoded_waypoints 배열에서 찾을 수 있습니다. 이 정보를 사용하면 서비스가 예상치 못한 경로를 반환하거나 경로를 반환하지 않은 이유를 추론할 수 있습니다.

geocoded_waypoints 배열의 요소들은 제로 기준 위치별로 출발지, 지정된 순서의 경유지 및 목적지에 해당합니다. 각 요소는 해당 경유지의 지오코딩 작업에 대한 다음과 같은 상세정보를 포함합니다.

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

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

  • place_id는 다른 Google API에 사용할 수 있는 고유 식별자입니다. 예를 들어, Google Place Autocomplete 응답에서 place_id를 사용하여 지역 사업체의 찾아가는 길을 계산할 수 있습니다. 장소 ID 개요를 참조하세요.
  • types는 찾아가는 길 계산에 사용되는 지오코딩 결과의 주소 유형을 나타냅니다. 다음과 같은 유형이 반환됩니다:
    • street_address는 정확한 거리 주소를 나타냅니다.
    • route는 이름이 지정된 도로(예: "US 101")를 나타냅니다.
    • intersection은 일반적으로 두 주요 도로가 만나는 주요 교차로를 나타냅니다.
    • political은 정치적 엔터티를 나타냅니다. 일반적으로 이 유형은 일부 정부 행정 구역의 폴리곤을 나타냅니다.
    • country는 전국적인 정치적 엔터티를 나타내며, 일반적으로 Geocoder에서 반환되는 최고 순위의 유형입니다.
    • administrative_area_level_1은 국가 레벨 아래의 1순위 정부 엔터티를 나타냅니다. 미국 내에서, 이러한 행정 레벨은 주입니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다. 대부분의 경우 administrative_area_level_1 짧은 이름은 ISO 3166-2 구획이나 기타 널리 보급된 목록들과 거의 일치하지만, 저희 지오코딩 결과는 다양한 신호와 위치 데이터를 기반으로 하기 때문에 이러한 일치가 보장되지는 않습니다.
    • administrative_area_level_2는 국가 레벨 아래의 2순위 정부 엔터티를 나타냅니다. 미국 내에서, 이러한 행정 레벨은 카운티입니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
    • administrative_area_level_3은 국가 레벨 아래의 3순위 정부 엔터티를 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
    • administrative_area_level_4는 국가 레벨 아래의 4순위 정부 엔터티를 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
    • administrative_area_level_5는 국가 레벨 아래의 5순위 정부 엔터티를 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
    • colloquial_area는 엔터티에 대해 보편적으로 사용되는 대체 이름을 나타냅니다.
    • locality는 시 또는 타운의 병합된 정치적 엔터티를 나타냅니다.
    • ward는 특정한 유형의 일본 지방을 나타내며, 일본 주소 내의 여러 지방 요소를 쉽게 구분해 줍니다.
    • sublocality는 지방 아래의 1순위 정부 엔터티를 나타냅니다. 일부 위치의 경우 다음과 같은 추가적인 유형 중 하나를 수신할 수도 있습니다: sublocality_level_1 ~ sublocality_level_5. 각 하위 지방 레벨은 하나의 정부 엔터티입니다. 숫자가 클수록 더 작은 지역을 나타냅니다.
    • neighborhood는 이름이 지정된 근방을 나타냅니다.
    • premise는 이름이 지정된 위치를 나타내며, 일반적으로 한 건물 또는 공통 이름을 가진 건물 집합을 나타냅니다.
    • subpremise는 이름이 지정된 위치 아래의 1순위 엔터티를 나타내며, 일반적으로 공통 이름을 가진 건물 집합 내의 단일 건물을 나타냅니다.
    • postal_code는 국가 내의 우편물을 처리하는 데 사용되는 우편 번호를 나타냅니다.
    • natural_feature는 유명한 자연 지형을 나타냅니다.
    • airport는 공항을 나타냅니다.
    • park는 이름이 지정된 공원을 나타냅니다.
    • point_of_interest는 이름이 지정된 관심 지점을 나타냅니다. 일반적으로, 이러한 "POI"는 다른 범주에는 잘 맞지 않는 그 지역만의 유명한 엔터티들입니다(예: "엠파이어스테이트 빌딩" 또는 "자유의 여신상").

    유형 목록이 비어 있는 것은, 가령 프랑스의 리외디(Lieu-Dit)와 같이 특정 주소 요소에 대한 알려진 유형이 없음을 나타냅니다.

서비스가 결과를 반환하지 않는 경우, 텍스트 위도/경도 값으로 지정된 경유지에 대해서는 이러한 상세정보가 존재하지 않습니다. 왜냐하면 이러한 경유지는 경로가 발견된 후에 경유지의 대표 주소를 가져오기 위해 역지오코딩만 수행되기 때문입니다. 빈 JSON 객체는 geocoded_waypoints 배열에서 해당하는 자리를 차지합니다.

경로

Google Maps Directions API가 결과를 반환할 때, (JSON) routes 배열 내에 결과를 넣습니다. 서비스에서 결과를 반환하지 않는 경우에도(예: 출발지 및/또는 목적지가 존재하지 않는 경우) 여전히 빈 routes 배열을 반환합니다. (XML 응답은 0개 이상의 <route> 요소로 구성됩니다.)

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

routes 필드 내의 각 경로는 다음 필드를 포함할 수 있습니다.

  • summary는 경로에 대한 짧은 텍스트 설명를 포함하며, 해당 경로를 다른 경로와 명확히 구분하고 명명하기에 적합합니다.
  • legs[]는 지정된 경로에 있는 두 위치 사이의 경로 구간에 대한 정보가 포함된 배열을 포함합니다. 지정된 각 경유지 또는 목적지에 대해 별도의 구간이 존재합니다. (경유지가 없는 경로는 legs 배열 내에 단 하나의 구간만 포함합니다.) 각 구간은 일련의 steps로 구성됩니다. (아래의 길찾기 구간을 참조하세요.)
  • waypoint_order(또는 XML의 <waypoint_index>)는 계산된 경로의 경유지 순서를 나타내는 배열을 포함합니다. waypoints 매개변수 내의 optimize:true로 요청이 전달된 경우, 이 경유지의 순서를 재정렬할 수도 있습니다.
  • overview_polyline은 경로의 인코딩된 폴리라인 표현이 들어있는 단일 points 객체를 포함합니다. 이 폴리라인은 최종 길찾기의 대략적인(다듬어진) 경로입니다.
  • boundsoverview_polyline의 뷰포트 경계 상자를 포함합니다.
  • copyrights는 이 경로에 표시되어야 하는 저작권 텍스트를 포함합니다. 본인이 직접 이 정보를 처리하고 표시해야 합니다.
  • warnings[]는 이러한 찾아가는 길을 표시할 때 표시되어야 하는 경고 배열을 포함합니다. 본인이 직접 이러한 경고를 처리하고 표시해야 합니다.
  • fare: 있을 경우, 이 경로상의 전체 요금(즉, 전체 티켓 비용)을 포함합니다. 이 속성은 대중교통 요청 및 모든 대중교통 구간에 대해 요금 정보를 사용할 수 있는 경로에 대해서만 반환됩니다. 이 정보에는 다음과 같은 항목이 포함됩니다.
    • currency: 금액이 표시되는 통화를 나타내는 ISO 4217 통화 코드.
    • value: 위에 지정된 통화의 전체 요금액.
    • text: 요청한 언어로 형식이 지정된 전체 요금액.

다음은 경로 내의 요금 정보에 대한 예시입니다.

"routes" : [
   {
      "bounds" : {
         "northeast" : {
            "lat" : 37.8079996,
            "lng" : -122.4074334
         },
         "southwest" : {
            "lat" : 37.7881005,
            "lng" : -122.4203553
         }
      },
      "copyrights" : "Map data ©2015 Google",
      "fare" : {
         "currency" : "USD",
         "value" : 6
         "text" : "$6.00"
      },
      ...
   }]

구간

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

legs 필드 내의 각 구간은 다음 필드를 포함할 수 있습니다.

  • steps[]는 여정 구간의 각 개별 스텝에 대한 정보를 표시하는 스텝 배열을 포함합니다. (아래의 길찾기 스텝을 참조하세요.)
  • distance는 이 구간에 포함되는 전체 거리를 다음과 같은 요소가 있는 필드로 나타냅니다.

    • value는 미터 단위의 거리를 나타냅니다
    • text는 사람이 읽을 수 있도록 표시된 거리를 포함하며, 출발지에서 사용되는 단위(또는 요청의 units 매개변수 내에 재정의된 단위)로 표시됩니다. (예를 들어, 마일과 피트는 미국 내의 출발지에 사용됩니다.) 참고로, 어떤 단위 체계가 텍스트로 표시되는지에 상관없이 distance.value 필드는 항상 미터로 표현되는 값을 포함합니다.

    거리를 알 수 없는 경우에는 이러한 필드가 없을 수도 있습니다.

  • duration은 이 구간의 전체 기간을 다음과 같은 요소가 있는 필드로 나타냅니다.

    • value는 기간을 초 단위로 나타냅니다.
    • text는 사람이 읽을 수 있도록 표시된 기간을 포함합니다.

    기간을 알 수 없는 경우에는 이러한 필드가 없을 수도 있습니다.

  • duration_in_traffic은 이 구간의 전체 기간을 나타냅니다. 이 값은 현재와 과거의 교통 상황을 기준으로 교통량을 고려한 예상 시간입니다. 반환되는 값이 optimistic, pessimistic 또는 best-guess 예상 값이 되도록 요청하는 데 사용할 수 있는 옵션에 대해서는 traffic_model 요청 매개변수를 참조하세요. 교통량을 고려한 기간은 다음 사항이 모두 참인 경우에만 반환됩니다.

    • 요청이 올바른 API 키나 올바른 Google Maps API 프리미엄 플랜 클라이언트 ID 및 서명을 포함합니다.
    • 요청이 중간 기착 경유지를 포함하지 않습니다. 요청이 경유지를 포함하는 경우 중간 기착을 피하도록 경유지에 via:라는 접두사를 붙여야 합니다.
    • 요청이 자동차 길찾기 전용으로 사용됩니다. 즉, mode 매개변수가 driving으로 설정됩니다.
    • 요청이 departure_time 매개변수를 포함합니다.
    • 요청한 경로에 대해 교통 상황이 제공됩니다.

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

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

스텝

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

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

steps 필드 내의 각 스텝은 다음 필드를 포함할 수 있습니다.

  • html_instructions는 이 스텝에 대한 형식이 지정된 지시를 포함하며, 이 지시는 HTML 텍스트 문자열로 표현됩니다.
  • distance는 이 스텝에서 다음 스텝까지의 거리를 포함합니다. (위의 길찾기 구간에서 이 필드에 대한 설명을 참조하세요.) 거리를 알 수 없는 경우에는 이 필드가 정의되지 않을 수도 있습니다.
  • duration은 다음 스텝까지 해당 스텝을 수행하는 데 필요한 일반적인 시간을 포함합니다. (위의 길찾기 구간의 설명을 참조하세요.) 기간을 알 수 없는 경우에는 이 필드가 정의되지 않을 수도 있습니다.
  • start_location은 이 스텝의 시작 지점의 위치를 단일 latlng 필드 집합으로 포함합니다.
  • end_location은 이 스텝의 마지막 지점의 위치를 단일 latlng 필드 집합으로 포함합니다.
  • polyline은 스텝의 인코딩된 폴리라인 표현이 들어있는 단일 points 객체를 포함합니다. 이 폴리라인은 스텝의 대략적인(다듬어진) 경로입니다.
  • steps는 대중교통 길찾기에서 도보 또는 운전 스텝에 대한 상세한 길찾기를 포함합니다. 하위 스텝은 travel_mode가 "transit"로 설정된 경우에만 사용할 수 있습니다. 내부 steps 배열은 steps와 동일한 유형입니다.
  • transit_details는 대중교통 특정 정보를 포함합니다. 이 필드는 travel_mode가 "transit"로 설정된 경우에만 반환됩니다. 아래의 대중교통 상세정보를 참조하세요.

대중교통 상세정보

대중교통 길찾기는 다른 이동 모드와는 무관한 추가적인 정보를 반환합니다. 이러한 추가적인 속성은 transit_details 객체를 통해 노출되며, steps[] 배열의 한 요소 필드로 반환됩니다. TransitDetails 객체에서 대중교통 정류장, 대중교통 노선 및 대중교통 기관에 대한 추가적인 정보에 액세스할 수 있습니다.

transit_details 객체는 다음 필드를 포함할 수 있습니다.

  • arrival_stopdeparture_stop은 여행 출발 및 도착 시의 정류장/역에 대한 정보를 포함합니다. 정류장 상세정보는 다음을 포함할 수 있습니다.
    • name은 대중교통 정류장/역의 이름입니다. 예: "유니온 스퀘어".
    • location은 대중교통 정류장/역의 위치이며, latlng 필드로 표현됩니다.
  • arrival_timedeparture_time은 이 여정 구간에 대한 출발 또는 도착 시간을 포함하며, 다음과 같은 세 가지 속성으로 지정됩니다.
    • text는 문자열로 지정되는 시간입니다. 이 시간은 대중교통 정류장의 시간대로 표시됩니다.
    • value는 1970년 1월 1일 자정(UTC) 이후의 Unix 시간 또는 초 단위로 지정되는 시간입니다.
    • time_zone은 이 역의 시간대를 포함합니다. 이 값은 IANA 시간대 데이터베이스에 정의된 시간대의 이름입니다. 예: "America/New_York"
  • headsign은 이 노선에서 이동할 방향을 지정하며, 차량 위나 출발 정류장 위에 표시됩니다. 이는 대개 종착역입니다.
  • headway는 현재 동일 정류장에서 각 출발 사이의 예상 시간을 초 단위로 지정합니다. 예를 들어, headway 값이 600이면, 버스를 놓친 경우 10분의 대기 시간을 예상할 수 있습니다.
  • num_stops는 이 스텝에 있는 정류장 수를 포함하며, 도착 정류장은 카운트하지만 출발 정류장은 카운트하지 않습니다. 예를 들어, 길찾기가 정류장 A에서 출발하여 정류장 B, C를 지나 정류장 D에 도착하는 경우, num_stops는 3을 반환합니다.
  • line은 이 스텝에 사용되는 대중교통 노선에 대한 정보를 포함하며, 다음과 같은 속성을 포함할 수 있습니다.
    • name은 이 대중교통 노선의 전체 이름을 포함합니다. 예: "7 Avenue Express".
    • short_name은 이 대중교통 노선의 짧은 이름을 포함합니다. 일반적으로 이 이름은 "M7" 또는 "355" 등과 같은 노선 번호입니다.
    • color는 이 대중교통 노선의 표시판에 일반적으로 사용되는 색상을 포함합니다. 색상은 #FF0033과 같은 16진수 문자열로 지정됩니다.
    • agenciesTransitAgency 객체의 배열을 포함하며, 각 객체는 다음과 같은 속성을 비롯하여 해당 노선의 운영업체 정보를 제공합니다.
      • name은 대중교통 기관의 이름을 포함합니다.
      • url은 대중교통 기관의 URL을 포함합니다.
      • phone은 대중교통 기관의 전화번호를 포함합니다.

      여행 결과를 서비스하는 대중교통 기관의 이름과 URL을 표시해야 합니다.

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

차량 유형

vehicle.type 속성은 다음 중 임의의 값을 반환할 수 있습니다:

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

사용 가능한 이동 모드

응답 필드 available_travel_modes는 사용 가능한 이동 모드의 배열을 포함합니다. 요청이 이동 mode를 지정하고 결과를 얻지 못할 때 이 필드가 반환됩니다. 해당 배열에는 결과가 있는 지정된 경유지 집합의 국가에서 사용 가능한 이동 모드가 포함됩니다. 해당 필드는 경유지가 via: 경유지인 경우 반환되지 않습니다.

예를 들어, 다음 요청을 시도해 보십시오.

https://maps.googleapis.com/maps/api/directions/json?&mode=transit&origin=frontera+el+hierro&destination=la+restinga+el+hierro&departure_time=1399995076&key=YOUR_API_KEY

이 요청은 다음 응답을 생성합니다.

{
   "available_travel_modes" : [ "DRIVING", "BICYCLING", "WALKING" ],
   "geocoded_waypoints" : [
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJwZNMti1fawwRO2aVVVX2yKg",
         "types" : [ "locality", "political" ]
      },
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJ3aPgQGtXawwRLYeiBMUi7bM",
         "types" : [ "locality", "political" ]
      }
   ],
   "routes" : [],
   "status" : "ZERO_RESULTS"
}

sensor 매개변수

이전의 Google Maps API는 애플리케이션이 사용자의 위치 파악을 위해 센서를 사용했는지 여부를 나타내기 위해 sensor 매개변수를 포함하도록 요구했습니다. 이 매개변수는 더 이상 필요하지 않습니다.

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

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