Directions API (기존)를 통한 경로 검색

유럽 경제 지역 (EEA) 개발자

이 제품은 기존 상태입니다. 2026년 10월부터는 새 Google Cloud 프로젝트에서 Directions API (기존)를 더 이상 사용 설정할 수 없습니다. 기존 프로젝트는 계속해서 완전히 지원됩니다. 새로운 기능과 향상된 성능을 이용하려면 Routes API로 이전하세요.

사용자 입력에 실시간으로 응답하는 경로 계산 (예: 사용자 인터페이스 요소 내)의 경우 Directions API (기존)를 사용하거나 Maps JavaScript API를 사용하는 경우 경로 서비스를 사용할 수 있습니다. 서버 측에서 사용하려면 Google 지도 서비스용 Java 클라이언트, Python 클라이언트, Go 클라이언트, Node.js 클라이언트를 사용하면 됩니다.

Directions API (기존)를 사용하면 다음을 수행할 수 있습니다.

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

API는 경로를 계산할 때 가장 효율적인 경로를 반환합니다. 이동 시간이 최적화되는 주요 요소이지만 가장 효율적인 경로를 결정할 때 거리, 방향 전환 횟수 등 여러 요인이 고려될 수 있습니다.

시작하기 전에

Directions API (기존)를 사용하려면 결제 계정이 있고 Directions API (기존)가 사용 설정된 프로젝트가 필요합니다. 자세한 내용은 Cloud 콘솔에서 설정하기를 참고하세요.

Directions API (기존) 요청 빌드

Directions API (기존) 요청의 형식은 다음과 같습니다.

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

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

  • json (권장)은 JavaScript 객체 표기법 (JSON)의 출력을 나타냅니다.
  • xml: 출력을 XML로 표시

참고: URL은 유효하도록 올바르게 인코딩되어야 하며 모든 웹 서비스에서 16,384자로 제한됩니다. URL을 구성할 때 이 제한에 유의하세요.

URL에서와 마찬가지로 모든 매개변수는 앰퍼샌드(&) 문자를 사용하여 구분합니다. 모든 예약 문자 (예: 더하기 기호 '+')는 URL로 인코딩되어야 합니다. 매개변수와 가능한 값 목록은 아래에 나와 있습니다.

필수 매개변수

  • destination

    경로를 계산하려는 장소 ID, 주소 또는 텍스트 위도/경도 값입니다. destination 매개변수의 옵션은 origin 매개변수의 옵션과 동일합니다.

  • origin

    경로를 계산하려는 장소 ID, 주소 또는 텍스트 위도/경도 값입니다.

    • 장소 ID에는 place_id: 프리픽스를 추가해야 합니다. Geocoding API 및 Places API(Place Autocomplete 포함)에서 장소 ID를 가져올 수 있습니다. Place Autocomplete의 장소 ID를 사용하는 예는 Place Autocomplete 및 경로를 참고하세요. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참고하세요. 

      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

    • 주소를 전달하면 Directions 서비스가 문자열을 지오코딩하고 위도/경도 좌표로 변환하여 경로를 계산합니다. 이 좌표는 Geocoding API에서 반환하는 좌표와 다를 수 있습니다(예: 건물의 중심이 아닌 건물 입구). 

      origin=24+Sussex+Drive+Ottawa+ON

      주소 또는 위도/경도 좌표를 사용하는 것보다 장소 ID를 사용하는 것이 좋습니다. 좌표를 사용하면 항상 해당 좌표에 가장 가까운 도로에 지점이 스냅됩니다. 이 도로는 숙박 시설의 액세스 포인트가 아닐 수도 있고 목적지로 빠르고 안전하게 이어지는 도로가 아닐 수도 있습니다.

    • 좌표를 전달하면 지점이 가장 가까운 도로에 스냅됩니다. 장소 ID를 전달하는 것이 좋습니다. 좌표를 전달하는 경우 위도와 경도 값 사이에 공백이 없어야 합니다. 

      origin=41.43206,-81.38992

    • Plus Code는 글로벌 코드 또는 복합 코드로 형식이 지정되어야 합니다. 여기 표시된 대로 Plus Code의 형식을 지정합니다. 더하기 기호는 %2B로 URL 이스케이프 처리되고 공백은 %20으로 URL 이스케이프 처리됩니다.

      • 글로벌 코드는 4자리 지역 번호와 6자 이상의 로컬 코드입니다 (849VCWC8+R9는 849VCWC8%2BR9입니다).
      • 복합 코드는 명시적인 위치가 포함된 6자 이상의 로컬 코드입니다 (CWC8+R9 Mountain View, CA, USA는 CWC8%2BR9%20Mountain%20View%20CA%20USA입니다).
    참고: 효율성과 정확성을 위해 가능하면 장소 ID를 사용하세요. 이러한 ID는 위도/경도 값 쌍과 같이 고유하게 명시적이며 액세스 포인트 및 교통 변수와 같은 경로를 위한 지오코딩 이점을 제공합니다. 주소와 달리 ID는 서비스에서 장소 세부정보에 대한 검색 또는 중간 요청을 수행할 필요가 없으므로 성능이 더 좋습니다.

선택적 매개변수

  • 대체

    true로 설정된 경우 경로 서비스에서 응답에 두 개 이상의 대체 경로를 제공할 수도 있음을 나타냅니다. 대체 경로를 제공하면 서버의 응답 시간이 늘어날 수도 있습니다. 중간 경유지가 없는 요청에만 사용할 수 있습니다. 자세한 내용은 경유지 가이드를 참고하세요.

  • arrival_time

    대중교통 경로의 선호 도착 시간을 1970년 1월 1일 자정(UTC) 이후의 시간(초)으로 지정합니다. departure_time 또는 arrival_time 중 하나를 지정할 수 있지만 둘 다 지정할 수는 없습니다. arrival_time는 정수로 지정해야 합니다.

  • 피하기

    계산된 경로가 표시된 지형지물을 피해야 함을 나타냅니다. 이 매개변수는 다음과 같은 인수를 지원합니다.

    • tolls는 경로 계산 시 유료 도로/다리를 제외해야 함을 나타냅니다.
    • highways는 경로 계산 시 고속도로를 제외해야 함을 나타냅니다.
    • ferries는 경로 계산 시 페리를 제외해야 함을 나타냅니다.
    • indoor은 경로 계산 시 도보 및 대중교통 경로에서 실내 계단을 피해야 함을 나타냅니다.

    avoid 매개변수에 여러 제한사항을 전달하여 유료 도로, 고속도로, 페리의 조합을 피하는 경로를 요청할 수 있습니다. 예를 들면 다음과 같습니다. 

    avoid=tolls|highways|ferries.

  • departure_time

    원하는 출발 시간을 지정합니다. 1970년 1월 1일(UTC) 자정 이후의 시간을 초 단위 정수로 지정할 수 있습니다. 9999-12-31T23:59:59.999999999Z 이후의 departure_time를 지정하면 API가 departure_time를 9999-12-31T23:59:59.999999999Z로 대체합니다. 또는 출발 시간을 현재 시간 (가장 가까운 초 단위로 수정)으로 설정하는 now 값을 지정할 수 있습니다. 출발 시간은 다음 두 경우에 지정될 수 있습니다.

    • 이동 수단이 대중교통인 요청의 경우: 원하는 경우 departure_time 또는 arrival_time 중 하나를 지정할 수 있습니다. 시간이 지정되지 않으면 departure_time의 기본값은 현재 시간입니다 (즉, 출발 시간의 기본값은 현재 시간).
    • 이동 수단이 운전인 요청의 경우: departure_time를 지정하여 교통 상황을 고려한 경로 및 이동 시간(응답 필드: duration_in_traffic)을 수신할 수 있습니다. departure_time은 현재 시간 또는 미래의 특정 시간으로 설정해야 합니다. 과거 시간으로 설정할 수는 없습니다.
    참고: 출발 시간을 지정하지 않으면 도로망 및 평균 시간과 무관한 교통상황을 기반으로 경로 및 소요 시간이 선택됩니다. 지정된 요청의 결과는 도로망의 변화, 평균 교통상황의 업데이트 및 분산된 서비스 특성으로 인해 시간이 지남에 따라 달라질 수도 있습니다. 거의 동일한 경로 간에도 언제든지 또는 수시로 결과가 다를 수도 있습니다.
    참고: mode=driving일 때 departure_time를 지정하는 거리 행렬 요청은 요청당 최대 100개의 요소로 제한됩니다. 출발지 수에 목적지 수를 곱한 값이 요소의 수입니다.

  • language

    결과를 반환할 언어입니다. 이는 start_address 및 end_address의 지오코딩된 주소, distance 및 duration 필드의 현지화된 텍스트 (구간 및 단계), html_instructions의 이동 설명에만 적용되며, 현지 언어 및 스크립트로 형식이 지정된 html_instructions의 이름 및 주소에는 적용되지 않습니다.

    • 지원 언어 목록을 참고하세요. Google에서는 지원되는 언어를 자주 업데이트하므로 이 목록에 모든 언어가 포함되지 않을 수도 있습니다.
    • language가 제공되지 않으면 API는 Accept-Language 헤더에 지정된 기본 언어를 사용하려고 시도합니다.
    • API는 사용자와 현지인 모두가 읽을 수 있는 상세 주소를 제공하기 위해 최선을 다합니다. 이 목표를 달성하기 위해 선호하는 언어를 준수하면서 필요한 경우 사용자가 읽을 수 있는 스크립트로 음역된 현지 언어로 상세 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 언어로 반환됩니다.
    • 선호하는 언어로 된 이름이 없는 경우 API는 가장 일치하는 이름을 사용합니다.
    • 기본 언어는 API가 반환하도록 선택하는 결과 집합과 반환되는 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 약어를 다르게 해석합니다. 예를 들어 도로 유형의 약어나 동의어는 한 언어에서는 유효하지만 다른 언어에서는 유효하지 않을 수 있습니다. 예를 들어 utca 및 tér은 헝가리어로 street의 동의어입니다.

  • 모드

    거리 및 경로를 계산할 때 사용할 교통수단을 지정할 수 있습니다. 기본적으로 driving 모드가 사용됩니다. 기본적으로 경로는 운전 경로로 계산됩니다. 다음과 같은 이동 수단이 지원됩니다.

    • driving (기본값)은 도로망을 사용하는 일반 운전 경로 또는 거리를 나타냅니다.
    • walking은 보행자 전용 도로와 인도를 경유하는 도보 경로 또는 거리를 요청합니다 (해당하는 경우).
    • bicycling은 자전거 전용 도로 및 선호하는 거리를 경유하는 자전거 경로 또는 거리를 요청합니다 (해당하는 경우).
    • transit은 대중교통 경로를 사용하는 경로 또는 거리를 요청합니다 (해당하는 경우). 모드를 대중교통으로 설정하면 선택적으로 departure_time 또는 arrival_time를 지정할 수 있습니다. 시간이 지정되지 않으면 departure_time의 기본값은 '지금'입니다 (즉, 출발 시간의 기본값은 현재 시간). 원하는 경우 transit_mode 또는 transit_routing_preference를 포함할 수도 있습니다. 대중교통 경로는 데이터 제공업체에서 제공하는 대중교통 정보의 가용성에 따라 과거 최대 7일 또는 향후 최대 100일까지 사용할 수 있습니다. 대중교통 일정은 자주 변경되며, 이용 가능한 대중교통 이동은 시간이 지남에 따라 변경될 수 있으며, 훨씬 이전에 예측에 대해 일관된 결과를 제공할 수 있다는 보장은 없습니다.
    참고: 도보 및 자전거 경로에 명확한 보행자 전용 도로 또는 자전거 전용 도로가 포함되지 않을 수도 있으므로 이러한 경로에서는 반환된 결과에 경고를 반환하며, 이 경고를 사용자에게 표시해야 합니다.

  • 지역

    ccTLD ('최상위 도메인') 2자리 값으로 지정되는 지역 코드입니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)이지만 ISO 3166-1 코드는 'gb'입니다(엄밀히 말하면 '영국 및 북아일랜드' 항목).

  • traffic_model

    이동 시간을 계산할 때 사용할 가정을 지정합니다. 이 설정은 응답의 duration_in_traffic 필드에 반환되는 값에 영향을 미칩니다. 이 필드에는 이전 평균을 기반으로 한 예상 이동 시간이 포함됩니다. traffic_model 매개변수는 요청에 departure_time가 포함된 운전 경로에만 지정할 수 있습니다. 이 매개변수에 사용 가능한 값은 다음과 같습니다.

    • 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

    선호하는 대중교통 수단을 하나 이상 지정합니다. 이 파라미터는 대중교통 경로에만 지정할 수 있습니다. 이 매개변수는 다음 인수를 지원합니다.

    • bus는 경로 계산 시 버스 이동을 우선적으로 고려해야 함을 나타냅니다.
    • subway는 경로 계산 시 지하철 이동을 우선적으로 고려해야 함을 나타냅니다.
    • train은 경로 계산 시 기차 이동을 우선적으로 고려해야 함을 나타냅니다.
    • tram은 경로 계산 시 트램 및 경전철 이동을 우선적으로 고려해야 함을 나타냅니다.
    • rail은 경로 계산 시 기차, 트램, 경전철 및 지하철 이동을 우선적으로 고려해야 함을 나타냅니다. transit_mode=train|tram|subway와 동일합니다.

  • transit_routing_preference

    대중교통 경로에 대한 환경설정을 지정합니다. 이 매개변수를 사용하면 API에서 선택한 기본 최적 경로를 수락하는 대신 반환되는 옵션에 편중할 수 있습니다. 이 매개변수는 대중교통 경로에만 지정할 수 있습니다. 매개변수는 다음과 같은 인수를 지원합니다.

    • less_walking은 경로 계산 시 도보 이동을 제한해야 함을 나타냅니다.
    • fewer_transfers는 경로 계산 시 환승 횟수를 제한해야 함을 나타냅니다.

  • 개

    결과를 표시할 때 사용할 단위 시스템을 지정합니다.

    경로 결과에는 경로의 특정 '단계'의 거리를 나타내기 위해 사용자에게 표시될 수 있는 거리 필드 내의 텍스트가 포함됩니다. 기본적으로 이 텍스트는 출발지 국가 또는 지역의 단위 체계를 사용합니다.

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

    • metric은 미터법 사용을 지정합니다. 텍스트 거리는 킬로미터와 미터를 사용하여 반환됩니다.
    • imperial은 야드파운드법 (영국) 사용을 지정합니다. 텍스트 거리는 마일과 피트를 사용하여 반환됩니다.
    참고: 이 단위 체계 설정은 거리 필드 내에 표시되는 텍스트에만 영향을 미칩니다. 거리 필드에는 항상 미터 단위로 표현되는 값도 포함됩니다.

  • 중간점

    주의: 경유지가 10개를 초과하거나 (11~25개) 경유지 최적화를 사용하는 요청에는 더 높은 요율로 청구됩니다. Google Maps Platform 제품의 결제에 대해 자세히 알아보세요.

    출발지와 목적지 사이의 경로를 따라 경유지 또는 경유지로 포함할 중간 위치의 배열을 지정합니다. 경유지는 지정된 위치를 지나가도록 경로를 변경합니다. API는 운전, 도보, 자전거 이동 모드의 경유지를 지원하며 대중교통은 지원하지 않습니다. 장소 ID, 주소 또는 위도/경도 좌표 형식으로 파이프 문자 (| 또는 %7C)로 구분된 하나 이상의 위치를 제공할 수 있습니다. 기본적으로 경로 서비스는 경유지를 지정된 순서대로 사용하여 경로를 계산합니다. 경유지 값을 파싱하는 우선순위는 장소 ID, 위도/경도 좌표, 주소 순입니다.

    • 장소 ID를 전달하는 경우 앞에 place_id:를 붙여야 합니다. Geocoding API 및 Places API(Place Autocomplete 포함)에서 장소 ID를 가져올 수 있습니다. Place Autocomplete의 장소 ID를 사용하는 예는 Place Autocomplete 및 경로를 참고하세요. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참고하세요.
      효율성과 정확성을 위해 가능하면 장소 ID를 사용하세요. 이러한 ID는 위도/경도 값 쌍과 같이 고유하게 명시적이며 액세스 포인트 및 교통 변수와 같은 경로를 위한 지오코딩 이점을 제공합니다. 주소와 달리 ID는 서비스에서 검색을 수행하거나 장소 세부정보에 대한 중간 요청을 수행할 필요가 없으므로 성능이 더 좋습니다.
    • 위도/경도 좌표를 전달하면 값이 프런트엔드 서버로 직접 이동하여 지오코딩 없이 경로를 계산합니다. 포인트는 도로에 스냅되며 앱에 필요한 정확성을 제공하지 못할 수 있습니다. 가능한 액세스 포인트나 추가 지오코딩 세부정보와 관계없이 값이 앱에서 경로를 지정하는 데 필요한 지점을 정확하게 지정한다고 확신하는 경우 좌표를 사용합니다. 위도와 경도 값이 공백(%20)이 아닌 쉼표 (%2C)로 구분되어 있는지 확인합니다.
    • 주소를 전달하면 Directions 서비스가 문자열을 지오코딩하고 위도/경도 좌표로 변환하여 경로를 계산합니다. 주소 값이 모호한 경우 유사한 주소와 구분하기 위해 검색을 유도할 수 있습니다. 예를 들어 '1st Street'는 '1st street NE' 또는 '1st St SE'의 전체 값 또는 부분 값일 수 있습니다. 이 결과는 Geocoding API에서 반환하는 결과와 다를 수 있습니다. 장소 ID를 사용하면 잘못 해석될 가능성을 방지할 수 있습니다.
    • 또는 인코딩된 다중선 알고리즘을 사용하여 인코딩된 지점 집합을 제공할 수 있습니다. 인코딩된 세트는 URL이 훨씬 짧기 때문에 많은 수의 경유지에 유용합니다. 모든 웹 서비스의 URL 제한은 16,384자(영문 기준)입니다.
      • 인코딩된 다중선은 앞에 enc:를 붙이고 뒤에 콜론 (:)을 붙여야 합니다. 예: waypoints=enc:gfo}EtohhU:
      • 파이프 문자 (|)로 구분된 여러 개의 인코딩된 다중선을 포함할 수도 있습니다. 예를 들면 다음과 같습니다. waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:
    경유지 및 통과 지점을 사용하여 경로에 영향 주기

    요청의 각 경유지에 대해 경로 응답은 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

    via: 프리픽스는 사용자가 지도에서 경유지를 드래그하는 것에 대한 응답으로 경로를 만들 때 가장 효과적입니다. 이렇게 하면 사용자가 최종 경로가 실시간으로 어떻게 표시되는지 확인할 수 있으며, Directions API에서 액세스할 수 있는 위치에 경유지가 배치되도록 할 수 있습니다.

    주의: 중간 기착을 피하기 위해 via: 접두사를 사용하면 경유지를 엄격하게 해석한 경로가 생성됩니다. 이로 인해 심하게 우회하는 경로가 생성되거나 Directions API에서 해당 지점을 지나는 경로를 만들 수 없는 경우 응답 상태 코드에 ZERO_RESULTS가 반환될 수도 있습니다.
    경유지 최적화

    기본적으로 경로 서비스는 제공된 경유지를 통해 지정된 순서대로 경로를 계산합니다. optimize:true를 경유지 매개변수 내의 첫 번째 인수로 전달하여 경로 서비스에서 더 효율적인 순서로 경유지를 재정렬하여 제공된 경로를 최적화하도록 할 수도 있습니다. 이 최적화는 여행하는 영업사원 문제를 적용한 사례입니다. 이동 시간이 최적화되는 주요 요소이지만 가장 효율적인 경로를 결정할 때 거리, 방향 전환 횟수 등 여러 요인이 고려될 수 있습니다. 경로 서비스에서 경로를 최적화하려면 모든 경유지가 중간 기착지여야 합니다.

    경로 서비스에서 경유지의 순서를 최적화하도록 지정한 경우 경유지의 순서는 경로 객체 내 waypoint_order 필드에 반환됩니다. waypoint_order 필드는 0부터 시작하는 값을 반환합니다.

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

    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

    계산된 경로를 검사하면 계산에서 다음 경유지 순서로 경유지를 사용함을 알 수 있습니다. 

    "waypoint_order": [ 3, 2, 0, 1 ]
    주의: 경유지 최적화를 사용하는 요청에는 더 높은 요율로 청구됩니다. Google Maps Platform 제품의 요금 청구 방식 자세히 알아보기

다음 단계

경로 예시

경로 응답