본문 바로가기
유용한툴 및 사이트

구글맵 API 완전정복 | 지도부터 경로·장소까지 실전 활용 가이드

by devcomet 2025. 10. 27.
728x90

Google Maps API tutorial guide showing mobile maps integration with markers, routes and places search features for web and mobile development
구글맵 API 완전정복 ❘ 지도부터 경로·장소까지 실전 활용 가이드

 

구글맵 API는 웹과 모바일 앱에 지도, 경로 탐색, 장소 정보를 통합할 수 있는 강력한 플랫폼으로, 2025년 3월부터 무료 월간 사용량과 자동 볼륨 할인으로 더욱 합리적인 가격 정책을 제공합니다.


구글맵 API란 무엇인가

구글맵 API란 무엇인가 요금제별 내용 정리

 

Google Maps Platform은 개발자가 웹사이트나 앱에 구글의 지도 기술을 통합할 수 있도록 제공하는 종합 솔루션입니다.

단순히 지도를 표시하는 것을 넘어, 사용자 위치 기반 서비스, 경로 탐색, 장소 검색, 주소 자동완성 등 다양한 기능을 구현할 수 있습니다.

구글맵 API는 크게 세 가지 카테고리로 나뉩니다.
Essentials(기본), Pro(전문가), Enterprise(기업)로 구분되어 각 비즈니스 요구사항에 맞는 솔루션을 제공합니다.

2025년 3월 1일부터 Google Maps Platform은 기존의 월 $200 크레딧 방식 대신, SKU별 무료 월간 사용량을 제공하는 새로운 가격 정책을 시행하고 있습니다.

자세한 정책은 Google Maps Platform 가격 정책 페이지에서 확인할 수 있습니다.


Google Maps API 사용법 - 시작하기

Google Maps API 사용법 과정 정리

API 키 생성 과정

구글맵 API를 사용하기 위한 첫 단계는 API 키를 생성하는 것입니다.

먼저 Google Cloud Console에 접속하여 Google 계정으로 로그인합니다.

 

Google 클라우드 플랫폼

로그인 Google 클라우드 플랫폼으로 이동

accounts.google.com

 

새 프로젝트를 생성하거나 기존 프로젝트를 선택한 후, 좌측 메뉴에서 'APIs & Services' > 'Library'로 이동합니다.

검색창에서 사용하려는 API(예: Maps JavaScript API)를 찾아 'Enable' 버튼을 클릭합니다.

다시 'APIs & Services' > 'Credentials'로 이동하여 'Create Credentials'를 클릭하고 'API key'를 선택합니다.

생성된 API 키는 안전하게 보관하며, 반드시 키 제한(API restrictions)을 설정하여 보안을 강화해야 합니다.

실제 프로덕션 환경에서는 IP 주소나 HTTP 리퍼러로 제한하는 것이 권장됩니다.

API 키 생성에 대한 상세 가이드는 Google Maps Platform 시작 가이드를 참고하세요.

Google Maps Platform 시작하기 페이지 스크린샷

 

Google Maps Platform 시작하기  |  Google for Developers

의견 보내기 Google Maps Platform 시작하기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요. 이 페이지에서는 Google Maps Platform의 API 및 SDK를 사용하기 위한 기본 필

developers.google.com

빌링 계정 설정

모든 Google Maps Platform API는 빌링 계정 활성화가 필수입니다.

무료 사용량을 초과하지 않더라도 결제 정보를 등록해야 API를 사용할 수 있습니다.

Google Cloud Console의 'Billing' 메뉴에서 신용카드 정보를 등록할 수 있습니다.

Essentials 카테고리의 경우 SKU당 월 10,000건의 무료 호출이 제공되므로, 소규모 프로젝트는 비용 부담 없이 시작할 수 있습니다.


Google Maps JavaScript API 튜토리얼

기본 지도 표시

웹 페이지에 구글맵을 표시하는 가장 기본적인 방법입니다.

<!DOCTYPE html>
<html>
<head>
    <title>구글맵 기본 예제</title>
    <style>
        #map {
            height: 500px;
            width: 100%;
        }
    </style>
</head>
<body>
    <h1>나의 첫 구글맵</h1>
    <div id="map"></div>

    <script>
        function initMap() {
            const map = new google.maps.Map(document.getElementById("map"), {
                center: { lat: 37.5665, lng: 126.9780 },
                zoom: 12
            });
        }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"></script>
</body>
</html>

위 코드에서 YOUR_API_KEY 부분을 생성한 API 키로 교체하면 됩니다.

center 속성은 지도의 중심 좌표를, zoom 속성은 확대 수준을 설정합니다.

zoom 값은 0(전 세계)부터 21(건물 수준)까지 설정할 수 있습니다.

마커 추가

지도에 특정 위치를 표시하기 위해 마커를 추가할 수 있습니다.

function initMap() {
    const map = new google.maps.Map(document.getElementById("map"), {
        center: { lat: 37.5665, lng: 126.9780 },
        zoom: 12
    });

    const marker = new google.maps.Marker({
        position: { lat: 37.5665, lng: 126.9780 },
        map: map,
        title: "서울 시청"
    });

    const infoWindow = new google.maps.InfoWindow({
        content: "<h3>서울 시청</h3><p>대한민국의 수도</p>"
    });

    marker.addListener("click", () => {
        infoWindow.open(map, marker);
    });
}

마커를 클릭하면 정보 창(InfoWindow)이 표시되어 추가 정보를 제공할 수 있습니다.

커스텀 아이콘을 사용하려면 icon 속성에 이미지 URL을 지정하면 됩니다.

더 많은 예제는 Google Maps JavaScript API 샘플 코드에서 확인할 수 있습니다.

지도 스타일 커스터마이징

Google Maps API는 지도의 색상, 도로, 지형지물 등을 자유롭게 커스터마이징할 수 있습니다.

const styledMapType = new google.maps.StyledMapType([
    {
        elementType: "geometry",
        stylers: [{ color: "#242f3e" }]
    },
    {
        elementType: "labels.text.stroke",
        stylers: [{ color: "#242f3e" }]
    },
    {
        elementType: "labels.text.fill",
        stylers: [{ color: "#746855" }]
    }
], { name: "Dark Mode" });

map.mapTypes.set("styled_map", styledMapType);
map.setMapTypeId("styled_map");

이를 통해 다크 모드 지도나 브랜드 컬러에 맞춘 지도를 구현할 수 있습니다.


Places API 활용하기

장소 검색 기능

Places API는 2억 개 이상의 장소 정보를 제공하는 강력한 도구입니다.

2025년 3월부터 기존 Places API는 Legacy로 전환되었으며, Places API (New)를 사용하는 것이 권장됩니다.

const request = {
    query: '서울 맛집',
    fields: ['name', 'geometry', 'formatted_address', 'rating'],
};

const service = new google.maps.places.PlacesService(map);

service.textSearch(request, (results, status) => {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
        results.forEach((place) => {
            createMarker(place);
        });
    }
});

텍스트 검색, 근처 검색, 장소 상세 정보 조회 등 다양한 기능을 활용할 수 있습니다.

자동완성 기능

주소 입력 시 자동완성 기능을 제공하여 사용자 경험을 향상시킬 수 있습니다.

const input = document.getElementById('address-input');
const autocomplete = new google.maps.places.Autocomplete(input, {
    types: ['address'],
    componentRestrictions: { country: 'kr' }
});

autocomplete.addListener('place_changed', () => {
    const place = autocomplete.getPlace();
    console.log(place.formatted_address);
    console.log(place.geometry.location);
});

componentRestrictions 옵션으로 특정 국가로 검색 결과를 제한할 수 있습니다.

Places API에 대한 자세한 정보는 Places API 공식 문서를 참고하세요.

 

개요  |  Places API  |  Google for Developers

사용자가 입력할 때 비즈니스, 주소 및 관심 장소와 같은 장소를 반환하여 텍스트 기반 지역 검색에 관한 예상 검색어 예상 검색어를 제공합니다.

developers.google.com


경로 탐색 API (Routes API)

Directions API에서 Routes API로 전환

구글 맵 경로탐색 api Directions API에서 Routes API로 전환 내용 정리

 

2025년 3월 1일부터 Directions API와 Distance Matrix API는 Legacy 상태로 전환되었습니다.

신규 프로젝트에서는 이 API들을 활성화할 수 없으며, Routes API를 사용해야 합니다.

Routes API는 기존 두 API의 기능을 통합하고 더 나은 성능과 새로운 기능을 제공합니다.

주요 개선사항으로는 통행료 정보, 2륜 차량 경로, 향상된 ETA 정확도 등이 있습니다.

 

REST vs JavaScript 구현

Routes API는 REST 방식과 JavaScript SDK 방식 모두 지원합니다.

 

REST API 방식 (HTTP POST)

const url = 'https://routes.googleapis.com/directions/v2:computeRoutes';

const requestBody = {
    origin: {
        location: {
            latLng: {
                latitude: 37.5665,
                longitude: 126.9780
            }
        }
    },
    destination: {
        location: {
            latLng: {
                latitude: 37.4979,
                longitude: 127.0276
            }
        }
    },
    travelMode: 'DRIVE',
    routingPreference: 'TRAFFIC_AWARE'
};

fetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-Goog-Api-Key': 'YOUR_API_KEY',
        'X-Goog-FieldMask': 'routes.duration,routes.distanceMeters,routes.polyline'
    },
    body: JSON.stringify(requestBody)
})
.then(response => response.json())
.then(data => console.log(data));

 

JavaScript SDK 방식

const directionsService = new google.maps.DirectionsService();
const directionsRenderer = new google.maps.DirectionsRenderer();

directionsRenderer.setMap(map);

const request = {
    origin: { lat: 37.5665, lng: 126.9780 },
    destination: { lat: 37.4979, lng: 127.0276 },
    travelMode: google.maps.TravelMode.DRIVING
};

directionsService.route(request, (result, status) => {
    if (status === 'OK') {
        directionsRenderer.setDirections(result);
    }
});

REST API는 서버 사이드 처리에 적합하고, JavaScript SDK는 클라이언트 사이드 웹 앱에 적합합니다.

자세한 마이그레이션 가이드는 Routes API 마이그레이션 문서를 확인하세요.


Android/iOS 지도 SDK

모바일 플랫폼별 SDK

Google Maps Platform은 Android와 iOS 각 플랫폼에 최적화된 네이티브 SDK를 제공합니다.

 

Android SDK 설정

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
    implementation 'com.google.android.gms:play-services-location:21.0.1'
}

 

AndroidManifest.xml에 API 키를 추가합니다.

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_API_KEY"/>

 

iOS SDK 설정

Podfile에 다음을 추가합니다.

pod 'GoogleMaps'
pod 'GooglePlaces'

 

AppDelegate에서 SDK를 초기화합니다.

import GoogleMaps

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        GMSServices.provideAPIKey("YOUR_API_KEY")
        return true
    }
}

모바일 SDK는 네이티브 성능과 플랫폼 최적화를 제공하여 더 나은 사용자 경험을 제공합니다.

각 플랫폼별 상세 문서는 Android Maps SDKiOS Maps SDK에서 확인할 수 있습니다.


구글맵 API 가격 정책

2025년 새로운 가격 체계

구글맵 API 가격 정책 2025년 바뀐 정책 정리

 

2025년 3월 1일부터 시행된 새로운 가격 정책의 핵심 변경사항을 살펴보겠습니다.

 

기존 방식 (2025년 2월까지)

  • 월 $200 크레딧 제공
  • 크레딧 소진 후 자동 과금

새로운 방식 (2025년 3월부터)

  • SKU별 무료 월간 사용량 제공
  • Essentials: 10,000건/월
  • Pro: 5,000건/월
  • Enterprise: 1,000건/월

이 변경으로 특정 API를 집중적으로 사용하는 경우 비용이 절감될 수 있습니다.

예를 들어 Dynamic Maps를 10,000건, Dynamic Street View를 5,000건 사용하면 이전에는 $100가 청구되었지만,

새 정책에서는 무료입니다.

사용량 제한 및 쿼터 관리

API 사용량을 효과적으로 관리하는 것이 비용 최적화의 핵심입니다.

 

일일 쿼터 설정

Google Cloud Console에서 APIs & Services > Quotas로 이동하여 일일 요청 제한을 설정할 수 있습니다.

이를 통해 예상치 못한 비용 발생을 방지할 수 있습니다.

 

비용 최적화 전략

  1. 필드 마스크 사용: 필요한 데이터만 요청하여 비용 절감
  2. 캐싱 활용: 자주 요청되는 데이터는 캐싱하여 API 호출 감소
  3. 배치 처리: 여러 요청을 하나로 통합
  4. API 키 제한: 무단 사용 방지를 위한 제한 설정
구분 Dynamic Maps Geocoding Places Search
가격 $7/1,000건 $5/1,000건 $17-32/1,000건
무료 제공 10,000건/월 10,000건/월 10,000건/월
카테고리 Essentials Essentials Pro

자세한 가격 정보는 Google Maps Platform 가격표를 참고하세요.

자동 볼륨 할인

2025년 3월부터 자동 볼륨 할인이 500만 건 이상까지 확대되었습니다.

월 1천만 건 이상 사용하는 경우 추가 할인을 받을 수 있으며, Google Maps Platform 파트너를 통해 더 유리한 조건을 협상할 수 있습니다.


실전 활용 사례

배달 앱 구현

음식 배달이나 택배 서비스에 필수적인 기능들을 구현할 수 있습니다.

 

실시간 위치 추적

let marker;

function updateDeliveryLocation(lat, lng) {
    const position = new google.maps.LatLng(lat, lng);

    if (!marker) {
        marker = new google.maps.Marker({
            position: position,
            map: map,
            icon: '/delivery-icon.png'
        });
    } else {
        marker.setPosition(position);
    }

    map.panTo(position);
}

// WebSocket이나 실시간 DB로 위치 업데이트 수신
socket.on('location-update', (data) => {
    updateDeliveryLocation(data.lat, data.lng);
});

 

경로 최적화

Routes API를 사용하여 여러 배달지를 효율적으로 방문하는 경로를 계산할 수 있습니다.

const request = {
    origin: { lat: 37.5665, lng: 126.9780 },
    destination: { lat: 37.4979, lng: 127.0276 },
    waypoints: [
        { location: { lat: 37.5172, lng: 127.0473 } },
        { location: { lat: 37.5326, lng: 127.0246 } }
    ],
    optimizeWaypoints: true,
    travelMode: 'DRIVING'
};

매장 찾기 기능

사용자 근처의 매장을 찾고 경로를 안내하는 기능입니다.

const userLocation = { lat: 37.5665, lng: 126.9780 };

const request = {
    location: userLocation,
    radius: 5000,
    type: ['store'],
    keyword: '편의점'
};

const service = new google.maps.places.PlacesService(map);

service.nearbySearch(request, (results, status) => {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
        results.forEach((place) => {
            const distance = google.maps.geometry.spherical.computeDistanceBetween(
                new google.maps.LatLng(userLocation),
                place.geometry.location
            );

            console.log(`${place.name}: ${(distance/1000).toFixed(2)}km`);
        });
    }
});

Geometry 라이브러리를 사용하여 거리를 계산하고 가까운 순서로 정렬할 수 있습니다.

부동산 지도 서비스

부동산 매물을 지도에 표시하고 클러스터링하여 보여주는 기능입니다.

import { MarkerClusterer } from "@googlemaps/markerclusterer";

const properties = [
    { lat: 37.5665, lng: 126.9780, price: '5억', type: '아파트' },
    { lat: 37.5172, lng: 127.0473, price: '3억', type: '빌라' },
    // ... 더 많은 매물
];

const markers = properties.map((property) => {
    const marker = new google.maps.Marker({
        position: { lat: property.lat, lng: property.lng },
        label: property.price,
        title: property.type
    });

    marker.addListener('click', () => {
        showPropertyDetails(property);
    });

    return marker;
});

const markerCluster = new MarkerClusterer({ map, markers });

마커 클러스터링으로 많은 매물을 효율적으로 표시할 수 있습니다.


보안 및 최적화

보안 및 최적화 적용시 기대값 수치 정리

API 키 보안

API 키는 민감한 정보이므로 철저한 보안 관리가 필요합니다.

 

 

프론트엔드 보안

  • HTTP 리퍼러 제한 설정
  • 특정 도메인에서만 사용 가능하도록 제한
  • 클라이언트 사이드 코드에서 키 노출 불가피

백엔드 보안

  • IP 주소 제한 설정
  • 환경 변수로 키 관리
  • 서버 사이드에서만 API 호출
// 환경 변수 사용 (Node.js)
const apiKey = process.env.GOOGLE_MAPS_API_KEY;

// 클라이언트에 키 노출하지 않고 프록시로 API 호출
app.get('/api/geocode', async (req, res) => {
    const address = req.query.address;
    const url = `https://maps.googleapis.com/maps/api/geocode/json?address=${address}&key=${apiKey}`;

    const response = await fetch(url);
    const data = await response.json();

    res.json(data);
});

성능 최적화

지도 로딩 최적화

// 지도 초기화를 지연시켜 페이지 로딩 속도 개선
function loadGoogleMapsScript() {
    const script = document.createElement('script');
    script.src = `https://maps.googleapis.com/maps/api/js?key=${apiKey}&callback=initMap&libraries=places`;
    script.async = true;
    script.defer = true;
    document.head.appendChild(script);
}

// 사용자가 지도 섹션에 도달했을 때만 로드
const observer = new IntersectionObserver((entries) => {
    if (entries[0].isIntersecting) {
        loadGoogleMapsScript();
        observer.disconnect();
    }
});

observer.observe(document.getElementById('map-section'));

 

마커 최적화

수천 개의 마커를 표시할 때는 클러스터링과 가상화 기법을 사용해야 합니다.

// 뷰포트 내의 마커만 표시
map.addListener('bounds_changed', () => {
    const bounds = map.getBounds();

    markers.forEach(marker => {
        if (bounds.contains(marker.getPosition())) {
            marker.setMap(map);
        } else {
            marker.setMap(null);
        }
    });
});

문제 해결 가이드

흔한 에러와 해결방법

1. API 키 관련 오류

Google Maps JavaScript API error: InvalidKeyMapError

 

해결방법

  • API 키가 올바른지 확인
  • Maps JavaScript API가 활성화되어 있는지 확인
  • API 키 제한 설정 확인

2. 빌링 오류

Google Maps JavaScript API error: BillingNotEnabledMapError

 

해결방법

  • Google Cloud Console에서 빌링 계정 활성화
  • 결제 정보 등록 확인

3. 할당량 초과

OVER_QUERY_LIMIT

 

해결방법

  • Google Cloud Console에서 쿼터 증가 요청
  • API 호출 빈도 제한 구현
  • 캐싱으로 중복 호출 감소

디버깅 팁

브라우저 개발자 도구의 Console 탭을 활용하여 API 오류를 확인할 수 있습니다.

Network 탭에서 API 요청과 응답을 모니터링하여 문제를 진단할 수 있습니다.

자세한 오류 목록은 Google Maps API 오류 메시지 문서를 참고하세요.

 


마치며

구글맵 API 포인트 요약 정리

 

구글맵 API는 위치 기반 서비스를 구축하는 데 필수적인 도구입니다.

2025년 새로운 가격 정책과 Routes API 도입으로 더욱 강력하고 합리적인 플랫폼으로 발전했습니다.

이 가이드에서 다룬 내용을 바탕으로 지도 표시, 마커 추가, 경로 탐색, 장소 검색 등 다양한 기능을 자신 있게 구현할 수 있을 것입니다.

API 키 생성부터 보안, 최적화까지 실전에서 필요한 모든 내용을 단계별로 다루었으므로, 이제 여러분의 프로젝트에 Google Maps Platform을 성공적으로 통합할 수 있습니다.

추가 학습을 원한다면 Google Maps Platform 공식 문서예제 코드 모음을 적극 활용하시기 바랍니다.


같이 보면 좋은 글

 

AI 전망| 2025년부터 변화하는 인공지능 산업의 미래와 개발자를 위한 전략

2025년 AI 산업은 에이전트 AI와 생성형 AI를 중심으로 급성장하며 글로벌 시장 규모 4000억 달러 시대를 열고, 개발자에게 새로운 역량과 전략적 접근이 필수가 되는 전환점을 맞이하고 있습니다.20

notavoid.tistory.com

 

무료로 쓸 수 있는 API 모음집 - 날씨, 번역, 이미지 생성, 뉴스 등 정리

소개2025년 현재, API(Application Programming Interface)는 현대 소프트웨어 개발의 필수 요소가 되었습니다.스타트업부터 대기업까지, 모든 개발팀이 빠른 개발과 비용 절감을 위해 무료 API를 적극 활용

notavoid.tistory.com

 

API vs 라이브러리 vs 프레임워크 | 차이는 무엇인가? 누가 흐름을 쥐느냐가 관건

API, 라이브러리, 프레임워크의 핵심 차이는 '제어의 역전(Inversion of Control)'에 있으며, 라이브러리는 개발자가 호출하지만 프레임워크는 개발자의 코드를 호출하며, API는 이들의 공개된 인터페이

notavoid.tistory.com

 

구글 G Suite 완전 정복 | Google Workspace로 팀 생산성 올리고 협업 혁신하는 방법

Google Workspace는 Gmail, Drive, Docs, Meet 등 클라우드 기반 협업 도구를 통합한 기업용 생산성 솔루션으로, 팀 협업 효율을 극대화하고 보안성을 강화하는 올인원 플랫폼입니다. 현대 기업 환경에서 원

notavoid.tistory.com

 

Google AI Studio 사용법 & 실전팁 | Gemini API로 멀티모달 AI 앱 구축하기

Google AI Studio는 Gemini API를 활용한 멀티모달 AI 애플리케이션 개발을 위한 무료 웹 기반 플랫폼으로, 프롬프트 실험부터 API 키 발급, 코드 내보내기까지 프로토타입 제작의 전 과정을 지원하는 개

notavoid.tistory.com

728x90
반응형
home 기피말고깊이 tnals1569@gmail.com