구글 맵 API 발급부터 웹페이지 삽입 완벽 가이드 (초보자도 쉽게)

구글 맵 API 발급 및 웹페이지 삽입, 왜 필요할까요?

웹사이트에 지도를 삽입하는 것은 사용자 경험을 크게 향상시키는 효과적인 방법입니다. 예를 들어, 비즈니스 위치를 안내하거나, 이벤트 장소를 표시하거나, 경로 안내 기능을 제공하는 등 다양한 목적으로 활용될 수 있습니다. 이러한 지도 기능을 구현하기 위해 가장 널리 사용되는 서비스 중 하나가 바로 구글 맵 API(Google Maps Platform API)입니다.

구글 맵 API는 강력하고 유연한 기능을 제공하여 개발자가 원하는 방식으로 지도를 커스터마이징하고 웹사이트에 통합할 수 있도록 지원합니다. 하지만 처음 접하는 분들에게는 API 발급 과정부터 웹페이지에 삽입하는 코드 작성까지 다소 복잡하게 느껴질 수 있습니다.

이 글에서는 구글 맵 API 발급 및 웹페이지 삽입 방법을 초보자도 쉽게 따라 할 수 있도록 상세하게 안내해 드립니다. 전문가 수준의 권위있는 정보와 함께, 실제 웹페이지에 적용할 수 있는 예제 코드를 제공하여 여러분의 개발 시간을 단축하고 완성도를 높이는 데 도움을 드릴 것입니다.

왜 구글 맵 API를 사용해야 할까요?

광범위한 데이터와 기능: 전 세계의 도로망, 건물 정보, 위성 사진 등 방대한 데이터를 기반으로 합니다. 또한, 경로 찾기, 장소 검색, 스트리트 뷰 등 다양한 부가 기능을 제공합니다.
높은 사용자 경험: 익숙하고 직관적인 인터페이스를 제공하여 사용자가 정보를 쉽게 찾고 이해하도록 돕습니다.
유연한 커스터마이징: 지도 스타일, 마커, 정보 창 등을 자유롭게 커스터마이징하여 웹사이트 디자인과 브랜드에 맞게 통합할 수 있습니다.
확장성: 무료 사용량 초과 시에도 유료 플랜을 통해 안정적인 서비스 이용이 가능하며, 다양한 플랫폼(웹, 모바일 앱)에서 활용할 수 있습니다.

1단계: 구글 클라우드 프로젝트 생성 및 API 활성화

구글 맵 API를 사용하기 위해서는 먼저 구글 클라우드 플랫폼(Google Cloud Platform, GCP)에서 프로젝트를 생성하고 필요한 API를 활성화해야 합니다.

1.1 구글 클라우드 계정 로그인 및 프로젝트 생성

구글 클라우드 콘솔 접속: 웹 브라우저를 열고 https://console.cloud.google.com/ 로 이동합니다.
구글 계정 로그인: 기존에 구글 계정이 있다면 해당 계정으로 로그인합니다. 계정이 없다면 새로 생성해야 합니다.
프로젝트 생성:
콘솔 상단의 프로젝트 선택 드롭다운 메뉴를 클릭합니다.
‘새 프로젝트’ 버튼을 클릭합니다.
프로젝트 이름을 입력합니다. (예: MyMapProject)
‘생성’ 버튼을 클릭합니다.

1.2 결제 계정 설정 (필수)

구글 맵 API는 무료 사용량 한도를 제공하지만, API 사용을 위해서는 결제 계정 설정이 필수입니다. 무료 사용량 한도 내에서는 비용이 발생하지 않으므로 안심하고 설정하셔도 됩니다.

결제 메뉴 이동: 좌측 상단의 메뉴 버튼(햄버거 아이콘)을 클릭하고 ‘결제’를 선택합니다.
결제 계정 생성 또는 선택:
‘결제 계정 만들기’를 클릭합니다.
국가, 계정 유형, 이름, 주소 등 필요한 정보를 입력합니다.
결제 수단(신용카드 또는 은행 계좌)을 등록합니다.
프로젝트와 결제 계정 연결: 생성된 결제 계정을 방금 만든 프로젝트와 연결합니다.

1.3 Maps JavaScript API 활성화

이제 웹사이트에 지도를 삽입하는 데 필요한 Maps JavaScript API를 활성화해야 합니다.

API 및 서비스 메뉴 이동: 좌측 상단의 메뉴 버튼을 클릭하고 ‘API 및 서비스’ > ‘라이브러리’를 선택합니다.
Maps JavaScript API 검색: 검색창에 “Maps JavaScript API”를 입력하고 검색합니다.
API 활성화: 검색 결과에서 ‘Maps JavaScript API’를 클릭하고 ‘사용 설정’ 버튼을 클릭합니다.

팁: 지도 기능 외에 경로 찾기(Directions API), 장소 검색(Places API) 등 추가 기능이 필요하다면 해당 API들도 동일한 방법으로 활성화해야 합니다.

2단계: API 키 발급 및 보안 설정

API 키는 구글 맵 API를 사용하기 위한 인증서와 같습니다. 이 키를 이용해 구글은 누가 API를 사용하고 있는지 식별하며, 사용량을 추적하고, 보안 정책을 적용합니다.

2.1 API 키 생성

사용자 인증 정보 메뉴 이동: 좌측 상단의 메뉴 버튼을 클릭하고 ‘API 및 서비스’ > ‘사용자 인증 정보’를 선택합니다.
‘+ 사용자 인증 정보 만들기’ 클릭: ‘+ 사용자 인증 정보 만들기’ 버튼을 클릭하고 ‘API 키’를 선택합니다.
API 키 복사: 자동으로 API 키가 생성됩니다. 이 키를 복사하여 안전한 곳에 보관합니다. (예: 텍스트 파일, 비밀번호 관리 도구)

2.2 API 키 보안 설정 (매우 중요!)

발급받은 API 키는 반드시 보안 설정을 해야 합니다. API 키가 유출되면 다른 사람이 여러분의 계정으로 API를 사용하며 예상치 못한 비용이 발생하거나, 서비스가 악용될 수 있습니다.

API 키 수정: ‘사용자 인증 정보’ 목록에서 방금 생성한 API 키를 클릭합니다.
애플리케이션 제한 설정:
‘애플리케이션 제한’ 섹션에서 ‘HTTP 리퍼러(웹사이트)’를 선택합니다.
‘제한사항 추가’ 버튼을 클릭합니다.
웹사이트 도메인 입력: 여러분의 웹사이트 도메인을 입력합니다. 예를 들어, *.example.com/* 와 같이 입력하면 example.com 하위의 모든 페이지에서 해당 API 키를 사용할 수 있습니다. 로컬 개발 환경에서는 localhost:8000/* 와 같이 설정할 수 있습니다.
주의: 정확한 도메인 패턴을 입력해야 합니다. 와일드카드(*) 사용법을 숙지하세요.
API 제한 설정:
‘API 제한’ 섹션에서 ‘API 선택’을 클릭합니다.
‘Maps JavaScript API’를 선택합니다. (필요한 다른 API도 함께 선택 가능)
‘확인’을 클릭합니다.

보안 설정 요약:

HTTP 리퍼러: API 키를 사용할 수 있는 웹사이트 도메인을 지정합니다.
API 제한: API 키로 사용할 수 있는 API를 제한합니다.

이 두 가지 설정을 통해 API 키의 오용을 방지하고 보안을 강화할 수 있습니다.

3단계: 웹페이지에 구글 지도 삽입하기

이제 발급받은 API 키를 사용하여 실제 웹페이지에 구글 지도를 삽입하는 방법을 알아보겠습니다.

3.1 기본 지도 삽입 코드

HTML 파일에 다음과 같은 코드를 추가하면 기본적인 구글 지도를 웹페이지에 삽입할 수 있습니다.

<!DOCTYPE html>

<html>

<head>

<title>구글 지도 삽입 예제</title>

<style>

/* 지도가 표시될 영역의 크기를 지정합니다. */

#map {

height: 400px; /* 높이 */

width: 100%;   /* 너비 */

}

</style>

</head>

<body>

<h1>우리 가게 위치</h1>

<!-- 지도가 삽입될 div 요소 -->

<div id="map"></div>

<script>

// 초기 지도 설정

function initMap() {

// 지도의 중심 좌표 (위도, 경도)

const mapCenter = { lat: 37.5665, lng: 126.9780 }; // 예: 서울 시청 좌표

// 지도 객체 생성

const map = new google.maps.Map(document.getElementById("map"), {

zoom: 15, // 확대/축소 레벨 (숫자가 클수록 확대)

center: mapCenter, // 지도 중심

});

// 마커 추가 (선택 사항)

// new google.maps.Marker({

//     position: mapCenter,

//     map: map,

//     title: "서울 시청"

// });

}

</script>

<!-- 구글 맵 API 로드 -->

<!-- YOUR_API_KEY 부분을 발급받은 API 키로 교체해야 합니다. -->

<script async defer

src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">

</script>

</body>

</html>

코드 설명:

<!DOCTYPE html> ~ <body>: 기본적인 HTML 구조입니다.
<style>: #map id를 가진 div 요소의 높이와 너비를 지정합니다. 이 부분이 없으면 지도가 보이지 않습니다.
<div id="map"></div>: 구글 지도가 실제로 표시될 영역입니다.
<script> initMap() { ... } </script>:
initMap 함수는 구글 맵 API가 로드될 때 자동으로 호출될 콜백 함수입니다.
mapCenter: 지도의 중심이 될 위도(lat)와 경도(lng) 좌표를 설정합니다. 예시에서는 서울 시청 좌표를 사용했습니다.
new google.maps.Map(...): 실제 지도 객체를 생성합니다.
document.getElementById("map"): 지도가 삽입될 HTML 요소를 지정합니다.
zoom: 지도의 확대/축소 레벨을 설정합니다. (0: 전체 지구, 21: 건물 수준)
center: 지도의 중심 좌표를 설정합니다.
new google.maps.Marker(...) (주석 처리됨): 지도에 마커(핀)를 추가하는 코드입니다. 필요에 따라 주석을 해제하고 사용할 수 있습니다.
<script async defer src="...">:
이 스크립트 태그가 구글 맵 API를 로드하는 핵심 부분입니다.
key=YOUR_API_KEY: 반드시 여러분이 발급받은 API 키로 YOUR_API_KEY 부분을 교체해야 합니다.
callback=initMap: API 로드가 완료되면 initMap 함수를 실행하도록 지정합니다.
async와 defer 속성은 스크립트 로딩과 실행 순서를 최적화하여 페이지 렌더링 속도를 향상시킵니다.

3.2 특정 위치 및 마커 표시

위 예제 코드에서 mapCenter 좌표를 원하는 장소의 위도/경도로 변경하고, Marker 객체를 사용하여 해당 위치에 마커를 표시할 수 있습니다.

예시: 특정 주소에 마커 표시하기

<!DOCTYPE html>

<html>

<head>

<title>구글 지도 특정 위치 마커</title>

<style>

#map {

height: 400px;

width: 100%;

}

</style>

</head>

<body>

<h1>강남역 근처</h1>

<div id="map"></div>

<script>

function initMap() {

// 강남역 근처 좌표

const gangnamStation = { lat: 37.497950, lng: 127.027572 };

const map = new google.maps.Map(document.getElementById("map"), {

zoom: 17, // 더 확대

center: gangnamStation,

});

// 강남역에 마커 추가

const marker = new google.maps.Marker({

position: gangnamStation,

map: map,

title: "강남역", // 마커에 마우스를 올렸을 때 표시될 텍스트

animation: google.maps.Animation.DROP // 마커가 떨어지는 애니메이션 (선택 사항)

});

}

</script>

<script async defer

src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">

</script>

</body>

</html>

3.3 정보 창(InfoWindow) 추가

마커를 클릭했을 때 상세 정보를 보여주는 정보 창(InfoWindow)을 추가할 수 있습니다.

<!DOCTYPE html>

<html>

<head>

<title>구글 지도 정보 창</title>

<style>

#map {

height: 400px;

width: 100%;

}

</style>

</head>

<body>

<h1>마커 클릭 정보</h1>

<div id="map"></div>

<script>

function initMap() {

const location = { lat: 37.5665, lng: 126.9780 }; // 서울 시청

const map = new google.maps.Map(document.getElementById("map"), {

zoom: 15,

center: location,

});

const marker = new google.maps.Marker({

position: location,

map: map,

title: "서울 시청"

});

// 정보 창(InfoWindow) 생성

const infowindow = new google.maps.InfoWindow({

content: `

<div>

<h2>서울 시청</h2>

<p>서울특별시 중구 세종대로 110</p>

<a href="https://www.seoul.go.kr/" target="_blank">홈페이지 방문</a>

</div>

` // HTML 내용을 문자열로 지정

});

// 마커 클릭 시 정보 창 열기

marker.addListener("click", () => {

infowindow.open(map, marker);

});

}

</script>

<script async defer

src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">

</script>

</body>

</html>

libraries=places 추가: 정보 창에 복잡한 HTML 콘텐츠를 표시하거나 Places 라이브러리의 다른 기능을 사용하려면 API 로드 URL에 &libraries=places를 추가해야 할 수 있습니다.

3.4 지도 스타일 커스터마이징

구글 맵 API는 지도 스타일을 다양하게 커스터마이징할 수 있는 기능을 제공합니다. JSON 형식의 스타일 정의를 사용하여 지도 색상, 가시성 등을 변경할 수 있습니다.

구글 지도 스타일링 마법사: https://mapstyle.withgoogle.com/ 에서 원하는 스타일을 디자인하고 JSON 코드를 얻을 수 있습니다.
JSON 스타일 적용: initMap 함수 내에서 styles 옵션을 사용하여 적용합니다.

// ... initMap 함수 내 ...

const map = new google.maps.Map(document.getElementById("map"), {

zoom: 15,

center: mapCenter,

styles: [

{

"featureType": "landscape.man_made",

"elementType": "geometry",

"stylers": [

{

"color": "#f2f2f2"

}

]

},

{

"featureType": "road.highway",

"elementType": "geometry.fill",

"stylers": [

{

"color": "#ffffff"

}

]

},

// ... 더 많은 스타일 정의 ...

]

});

// ...

4단계: 흔한 실수와 해결 방법

구글 맵 API 사용 시 초보자들이 자주 겪는 문제와 해결 방법을 정리했습니다.

4.1 API 키 오류 (InvalidKeyMapError)

증상: 지도 대신 “InvalidKeyMapError” 오류 메시지가 표시됩니다.
원인:
API 키가 잘못 입력되었거나 복사/붙여넣기 오류가 발생했습니다.
API 키에 대한 보안 설정(HTTP 리퍼러, API 제한)이 제대로 되어 있지 않습니다.
결제 계정이 설정되지 않았거나, 무료 사용량 한도를 초과했습니다. (초과 시에는 오류 메시지가 다를 수 있습니다.)
해결 방법:
API 키를 다시 한번 정확하게 복사하여 붙여넣습니다.
구글 클라우드 콘솔에서 API 키의 보안 설정을 확인하고, 웹사이트 도메인(또는 localhost)이 올바르게 등록되었는지 확인합니다.
Maps JavaScript API가 활성화되어 있는지 확인합니다.
결제 계정이 정상적으로 설정되어 있는지 확인합니다.

4.2 지도 영역이 비어 있거나 보이지 않음

증상: div#map 영역이 비어 있거나, 지도가 전혀 표시되지 않습니다.
원인:
#map div 요소의 CSS height 또는 width 속성이 설정되지 않았거나 0으로 설정되었습니다.
initMap 함수가 제대로 호출되지 않았습니다.
API 키 로딩 스크립트(script async defer src=...)가 HTML 문서의 잘못된 위치에 있거나, callback 함수 이름이 잘못되었습니다.
해결 방법:
#map div에 height와 width 스타일이 제대로 적용되었는지 확인합니다. height: 400px; width: 100%; 와 같이 구체적인 값을 지정하는 것이 좋습니다.
callback=initMap 부분이 정확한지, initMap 함수가 전역 스코프에 정의되었는지 확인합니다.
API 로딩 스크립트가 <body> 태그의 마지막 부분에 위치하는 것이 일반적입니다.

4.3 JavaScript 오류 발생

증상: 브라우저 개발자 도구(F12)의 콘솔 창에 JavaScript 오류 메시지가 표시됩니다.
원인:
API 키에 대한 보안 설정(특히 HTTP 리퍼러)이 제대로 되어 있지 않아 API 호출이 차단되었습니다.
다른 JavaScript 코드와의 충돌이 발생했습니다.
해결 방법:
개발자 도구의 콘솔 메시지를 주의 깊게 읽고 오류의 원인을 파악합니다.
API 키 보안 설정을 다시 한번 확인합니다.
다른 스크립트와의 충돌이 의심되면, 구글 맵 API 스크립트만 로드한 상태에서 테스트해봅니다.

5단계: 추가 팁 및 고급 활용

5.1 지오코딩 (주소를 좌표로 변환)

사용자가 입력한 주소를 위도/경도 좌표로 변환하거나, 반대로 좌표를 주소로 변환하는 기능은 매우 유용합니다. 이를 위해 Geocoding API를 사용합니다.

// Geocoding API 사용 예시 (initMap 함수 내 또는 별도 함수로 구현)

const geocoder = new google.maps.Geocoder();

function geocodeAddress(address) {

geocoder.geocode({ 'address': address }, (results, status) => {

if (status === 'OK') {

const location = results[0].geometry.location;

console.log("좌표:", location.lat(), location.lng());

// 이 좌표를 사용하여 지도 중심 이동, 마커 추가 등 수행

map.setCenter(location);

new google.maps.Marker({

position: location,

map: map,

title: address

});

} else {

alert('Geocoding 실패: ' + status);

}

});

}

// 사용 예시:

// geocodeAddress('서울 시청');

참고: Geocoding API 사용 시에도 API 키가 필요하며, 사용량에 따라 비용이 발생할 수 있습니다. API 로드 시 libraries=places 외에 추가적인 라이브러리 로드가 필요할 수 있으니, 공식 문서를 참고하세요.

5.2 Places 라이브러리 활용

Places 라이브러리를 사용하면 주변 장소 검색, 장소 정보(이름, 주소, 평점 등) 가져오기, 자동 완성 기능 등을 구현할 수 있습니다.

API 로드 시 &libraries=places 추가:

“`html

Post Views: 9