Google Maps API 구글 지도 API 연동

티스토리 뷰

API

Google Maps API 구글 지도 API 연동 - 2. 길찾기

열코 2026. 5. 14. 13:22

2026.05.12 - [API] - Google Maps API 구글 지도 API 연동 - 1. 시작하기

지난 포스팅에서 구글 지도 API의 기본적인 연동 방법과 비용 체계, 그리고 API 키를 안전하게 발급받는 방법을 살펴보았습니다. 이제 본격적으로 '기능'다운 기능을 만들어볼 차례입니다. 지도의 핵심은 단순히 위치를 보여주는 것을 넘어, "A지점에서 B지점까지 어떻게 가는가?"에 대한 해답을 주는 것입니다.

1. 길찾기 기능의 심장: Directions Service vs Directions Renderer

구글 지도 SDK에서 길찾기를 구현할 때 반드시 이해해야 하는 두 개의 핵심 객체가 있습니다.

1.1 DirectionsService (연산의 뇌)

이 객체는 클라이언트의 요청을 받아 구글 서버로 전달하고, 최적의 경로 데이터를 가져오는 역할을 합니다. 위도/경도 좌표뿐만 아니라 "서울역", "남산타워"와 같은 주소 문자열을 직접 이해하며, 교통 상황과 이동 수단을 고려한 복잡한 알고리즘을 수행합니다.

1.2 DirectionsRenderer (시각화의 눈)

DirectionsService가 가져온 데이터는 복잡한 JSON 형태입니다. 이를 사람이 읽기 좋은 형태(지도의 선, 마커, 텍스트 안내)로 변환해 주는 것이 바로 DirectionsRenderer입니다. 이 객체를 사용하면 수백 줄의 좌표 데이터를 일일이 폴리라인(Polyline)으로 그릴 필요 없이 한 줄의 코드로 지도를 채울 수 있습니다.

2. 사전 준비: Directions API 활성화

코드 작성 전, Google Cloud Console에서 한 가지 설정을 더 확인해야 합니다.

Google Cloud 콘솔에 접속합니다.
사용 중인 프로젝트를 선택합니다.
[API 및 서비스] > [라이브러리] 메뉴로 이동합니다.
"Directions API"를 검색하여 [사용 설정] 버튼을 클릭합니다.
- 주의: Maps JavaScript API만 켜져 있으면 지도는 뜨지만 경로 검색 시 에러가 발생합니다.

3. 기본 길찾기 구현 (A to B)

가장 기초적인 서울역에서 남산타워까지의 자동차 경로를 찾는 코드를 작성해 보겠습니다.

3.1 전체 예제 코드 (HTML/JS 통합)

<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <title>Google Maps 길찾기 가이드</title>
    <style>
        body { margin: 0; padding: 20px; font-family: 'Pretendard', sans-serif; }
        #container { display: flex; gap: 20px; height: 600px; }
        #map { flex: 2; border-radius: 12px; box-shadow: 0 4px 15px rgba(0,0,0,0.1); }
        #sidebar { flex: 1; overflow-y: auto; padding: 15px; background: #f8fafc; border-radius: 12px; }
        .controls { margin-bottom: 20px; display: flex; flex-direction: column; gap: 10px; }
        input, select, button { padding: 10px; border: 1px solid #ddd; border-radius: 6px; }
        button { background: #4285F4; color: white; border: none; cursor: pointer; font-weight: bold; }
        button:hover { background: #357abd; }
    </style>
</head>
<body>

    <h2>📍 구글 지도 실전 길찾기</h2>
    
    <div id="container">
        <div id="sidebar">
            <div class="controls">
                <input id="origin" type="text" placeholder="출발지 (예: 서울역)" value="서울역">
                <input id="destination" type="text" placeholder="도착지 (예: 남산타워)" value="남산타워">
                <select id="mode">
                    <option value="DRIVING">운전 (Driving)</option>
                    <option value="WALKING">도보 (Walking)</option>
                    <option value="BICYCLING">자전거 (Bicycling)</option>
                    <option value="TRANSIT">대중교통 (Transit)</option>
                </select>
                <button id="search-btn">경로 찾기</button>
            </div>
            <!-- 경로 안내 텍스트가 표시될 패널 -->
            <div id="directions-panel"></div>
        </div>
        <div id="map"></div>
    </div>

    <!-- API 키 입력 부분 -->
    <script async src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"></script>

    <script>
        let map;
        let directionsService;
        let directionsRenderer;

        function initMap() {
            // 1. 지도 초기화
            map = new google.maps.Map(document.getElementById("map"), {
                zoom: 14,
                center: { lat: 37.5665, lng: 126.9780 }, // 서울 시청
                mapTypeControl: false
            });

            // 2. 서비스 및 렌더러 객체 생성
            directionsService = new google.maps.DirectionsService();
            directionsRenderer = new google.maps.DirectionsRenderer({
                draggable: true, // 사용자가 경로를 드래그해서 변경 가능
                map: map,
                panel: document.getElementById("directions-panel") // 텍스트 안내 표시
            });

            // 3. 버튼 이벤트 연결
            document.getElementById("search-btn").addEventListener("click", () => {
                calculateRoute();
            });
        }

        function calculateRoute() {
            const start = document.getElementById("origin").value;
            const end = document.getElementById("destination").value;
            const selectedMode = document.getElementById("mode").value;

            const request = {
                origin: start,
                destination: end,
                travelMode: google.maps.TravelMode[selectedMode],
                unitSystem: google.maps.UnitSystem.METRIC // 미터법 사용
            };

            directionsService.route(request, (result, status) => {
                if (status === "OK") {
                    // 성공 시 지도에 경로 표시
                    directionsRenderer.setDirections(result);
                    
                    // 결과 데이터 활용 예시 (거리 및 시간)
                    const route = result.routes[0].legs[0];
                    console.log(`거리: ${route.distance.text}, 소요시간: ${route.duration.text}`);
                } else {
                    alert("경로를 찾을 수 없습니다: " + status);
                }
            });
        }
    </script>
</body>
</html>

4. 심화 학습: 필수 파라미터와 옵션 상세 설명

길찾기 기능을 완벽하게 제어하려면 DirectionsRequest 객체의 세부 옵션을 알아야 합니다.

4.1 Travel Modes (이동 수단)

DRIVING (기본값): 도로망을 이용한 표준 차량 경로입니다.
WALKING: 보행자 전용 도로와 인도를 이용합니다. (한국 내에서는 데이터 제약이 있을 수 있음)
BICYCLING: 자전거 경로와 선호 도로를 이용합니다.
TRANSIT: 버스, 지하철 등 대중교통을 이용한 경로입니다.

4.2 Waypoints (경유지 지정)

단순히 A에서 B가 아니라, 중간에 맛집이나 주유소를 들러야 한다면 waypoints 배열을 사용합니다.

const request = {
    origin: "서울역",
    destination: "부산역",
    waypoints: [
        { location: "대전역", stopover: true },
        { location: "대구역", stopover: true }
    ],
    optimizeWaypoints: true, // ★매우 중요: 경유지 순서를 최적의 효율로 재구성함
    travelMode: 'DRIVING'
};

optimizeWaypoints: true 옵션은 이른바 '외판원 문제(Traveling Salesperson Problem)'를 구글 알고리즘이 자동으로 해결해 주는 기능입니다. 배달 앱이나 물류 시스템 구축 시 필수적인 옵션입니다.

4.3 Driving Options (고급 운전 설정)

DRIVING 모드에서는 출발 시간(departureTime)을 설정하여 미래의 예상 교통 상황을 반영할 수 있습니다.

trafficModel: best_guess(가장 가능성 높은 소요 시간), pessimistic(최악의 경우), optimistic(최선의 경우) 중 선택 가능합니다.

5. 한국 시장에서의 특별한 고려 사항 (Localization)

한국에서 구글 지도 API로 길찾기를 구현할 때 초보 개발자들이 가장 당황하는 부분은 "자동차 길찾기가 가끔 안 된다"는 점입니다.

국내 법규 제약: 한국의 지도 데이터 반출 제한 정책으로 인해, 구글 지도의 '자동차 및 도보 길찾기' 데이터는 글로벌 버전과 달리 제약이 있을 수 있습니다.
대중교통 강점: 반면, TRANSIT(대중교통) 데이터는 매우 상세합니다. 한국 내 서비스를 개발하신다면 이동 수단을 TRANSIT으로 기본 설정하거나, 사용자에게 대중교통 위주의 정보를 제공하는 전략이 유효합니다.
언어 설정: 한국 사용자에게는 반드시 language=ko 파라미터를 API 호출 시 포함하여 한글 지명과 안내를 보장해야 합니다.

6. 에러 핸들링 및 문제 해결 (Troubleshooting)

status 결과값에 따른 대응법입니다.

OK: 성공.
NOT_FOUND: 출발지나 도착지 주소가 데이터베이스에 없습니다.
ZERO_RESULTS: 경로를 찾을 수 없습니다. (예: 대륙 간 자동차 여행 요청)
OVER_QUERY_LIMIT: 짧은 시간 내 너무 많은 요청을 보냈습니다. (무료 할당량 체크 필요)
REQUEST_DENIED: API 키 설정이나 리퍼러 제한 오류입니다.

#구글지도API #GoogleMapsPlatform #길찾기API #DirectionsAPI #구글맵연동 #자바스크립트지도 #웹개발 #지도SDK #경로최적화 #Waypoints #공공데이터활용 #초보개발자가이드 #API연동

저작자표시 (새창열림)

'API' 카테고리의 다른 글

Google Maps API 구글 지도 API 연동 - 5. 커스터마이징 (0)	2026.05.14
Google Maps API 구글 지도 API 연동 - 4. 클러스터링 (0)	2026.05.14
Google Maps API 구글 지도 API 연동 - 3. 장소 (0)	2026.05.14
Google Maps API 구글 지도 API 연동 - 1. 시작하기 (0)	2026.05.14
카카오 지도 연동하기 (0)	2026.05.10
카카오 로그인 연동하기 (0)	2026.05.10

공지사항

최근에 올라온 글

최근에 달린 댓글

Total

Today

Yesterday

링크

TAG more

« 2026/05 »
일	월	화	수	목	금	토
					1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31

글 보관함

열코의 프로그래밍 일기

티스토리 뷰