구글 지도 Routes API 대중교통 경로 사용 가이드: Transit Routes

웹·모바일 앱에서 버스, 지하철, 기차 등 대중교통 수단을 이용한 경로 안내를 제공하려면 travelMode: "TRANSIT"을 사용해야 합니다. 일반 드라이브나 도보 경로와는 요청·응답 방식이 조금 다르므로, 이 가이드에서 단계별 방법과 주의사항을 살펴보겠습니다.

 

1. 대중교통 경로 vs 다른 경로 차이

구분	기타 이동수단	대중교통 이동수단
중간 웨이포인트 지원	가능	불가능
교통 회피 옵션 (톨·고속도로·페리)	지원	미지원
트래픽 반영	지원	미지원
routingPreference	TRAFFIC_AWARE 등 다양하게 지정 가능	TransitPreferences만 지정 가능
응답 필드	steps, polyline 등	transitDetails, stepsOverview 등 대중교통 메타데이터 포함

 

2. 요청 전제 조건

• travelMode를 반드시 "TRANSIT"으로 설정
• 중간 웨이포인트(intermediateWaypoints) 지정 불가
• 트래픽, 톨회피 등 routeModifiers 옵션 미지원
• routingPreference에는 transitPreferences만 지정 가능 (예: LESS_WALKING, FEWER_TRANSFERS) 
  
  

3. 대중교통 경로 요청 단계

1. 출발지(origin)와 도착지(destination) 설정
2. travelMode: "TRANSIT" 지정
3. 필드 마스크(X-Goog-FieldMask)로 필요한 응답 필드 지정
4. 선택: 대중교통 선호도 설정 (transitPreferences)
   
   

4. 추천 응답 필드 요청

요청 정보	필드 마스크 예시
모든 대중교통 세부정보	routes.legs.steps.transitDetails
걸음 요약	routes.legs.stepsOverview
각 단계 시작/종료 위치	routes.legs.steps.startLocation, routes.legs.steps.endLocation
요금 정보	routes.travelAdvisory.transitFare

 

5. curl 요청 예시

curl -X POST 'https://routes.googleapis.com/directions/v2:computeRoutes' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: YOUR_API_KEY' \
  -H 'X-Goog-FieldMask: routes.legs.steps.transitDetails,routes.travelAdvisory.transitFare' \
  --data-raw '{
    "origin": {
      "location": { "latLng": { "latitude": 37.5665, "longitude": 126.9780 } }
    },
    "destination": {
      "location": { "latLng": { "latitude": 37.5512, "longitude": 126.9882 } }
    },
    "travelMode": "TRANSIT",
    "transitPreferences": {
      "allowedTravelModes": ["BUS","SUBWAY"],
      "routingPreference": "LESS_WALKING"
    }
  }'

6. 응답 예시

{
  "routes": [
    {
      "legs": [
        {
          "steps": [
            {
              "travelMode": "WALK",
              "distanceMeters": 200,
              "duration": "180s",
              "polyline": { "encodedPolyline": "abcd…" }
            },
            {
              "travelMode": "TRANSIT",
              "distanceMeters": 5000,
              "duration": "1200s",
              "transitDetails": {
                "line": {
                  "vehicle": { "type": "SUBWAY" },
                  "shortName": "2호선"
                },
                "departureStop": { "name": "시청역" },
                "arrivalStop": { "name": "을지로입구역" }
              },
              "polyline": { "encodedPolyline": "wxyz…" }
            },
            {
              "travelMode": "WALK",
              "distanceMeters": 300,
              "duration": "240s",
              "polyline": { "encodedPolyline": "mnop…" }
            }
          ]
        }
      ],
      "travelAdvisory": {
        "transitFare": { "currency": "KRW", "value": 1350 }
      }
    }
  ]
}

7. 주의사항 및 팁

• 대중교통 경로는 중간 웨이포인트를 지원하지 않으므로, 여러 정거장을 경유하려면 개별 요청을 연속으로 호출하세요.
• transitPreferences.allowedTravelModes로 원하는 대중교통 유형만 필터링할 수 있습니다.
• 요금 정보(transitFare)는 API가 해당 정보를 제공할 수 있는 경우에만 반환됩니다.
  
  

Google 지도 Routes API의 대중교통 경로 기능을 활용하면, 복잡한 환승 정보와 도보 구간을 포함한 상세 내비게이션을 제공할 수 있습니다.