카카오맵 API를 사용하려면 가장 먼저 API 키를 발급받아야 해요. 아무리 좋은 지도 API라도 키 없이는 사용할 수 없거든요. 처음 발급 과정이 낯설게 느껴질 수 있지만, 카카오 디벨로퍼스의 인터페이스는 비교적 직관적으로 설계되어 있어서 순서대로 따라가면 어렵지 않게 키를 발급받을 수 있어요.
이번 글에서는 카카오맵 API 키 발급 과정을 스크린샷 없이도 이해할 수 있도록 각 단계를 상세하게 설명해 드릴게요. 카카오 계정 준비부터 키 발급 후 설정까지 빠짐없이 담았으니 천천히 따라해 보세요.
사전 준비사항 확인
카카오 계정 준비
카카오맵 API 키 발급을 위해서는 카카오 계정이 필요해요. 카카오톡을 사용하고 있다면 이미 카카오 계정이 있는 거예요. 카카오 계정이 없다면 카카오 홈페이지에서 무료로 가입할 수 있어요. 계정 가입은 이메일 또는 휴대폰 번호로 할 수 있으며, 본인 인증 과정이 포함될 수 있어요. 카카오 디벨로퍼스는 별도 가입 없이 기존 카카오 계정으로 로그인하면 사용할 수 있어요.
사용 목적 파악하기
키 발급 전에 카카오맵 API를 어떤 목적으로 사용할지 먼저 파악하는 것이 좋아요. 웹 서비스에 지도를 삽입할 것인지, 안드로이드 앱인지, iOS 앱인지에 따라 사용하는 키의 종류가 달라질 수 있어요. 웹 서비스라면 JavaScript 키를, REST API 방식으로 서버에서 장소 검색 등을 처리할 것이라면 REST API 키를 사용해요. 앱 개발이라면 Native 앱 키를 사용하게 돼요. 목적에 맞는 키를 선택해야 나중에 혼란이 없어요.
서비스 도메인 미리 파악하기
웹 서비스에서 카카오맵 API를 사용한다면, 키 발급 후 플랫폼 등록 단계에서 서비스 도메인을 입력해야 해요. 미리 사용할 도메인을 파악해 두면 발급 과정이 더 원활해요. 아직 도메인이 없는 개발 초기 단계라면 로컬 개발 환경인 http://localhost를 등록하면 돼요. 나중에 운영 환경으로 전환할 때 실제 도메인을 추가 등록하면 되니 걱정하지 않아도 돼요.
카카오 디벨로퍼스 접속 및 로그인
디벨로퍼스 사이트 접속
카카오 디벨로퍼스는 developers.kakao.com에서 접근할 수 있어요. 브라우저에서 이 URL을 입력하거나 검색창에 “카카오 디벨로퍼스”를 검색하면 쉽게 찾을 수 있어요. 메인 페이지에는 카카오의 다양한 API 서비스가 소개되어 있어요. 상단 메뉴에서 ‘내 애플리케이션’을 클릭하거나, 로그인 버튼을 찾아 카카오 계정으로 로그인해요.
카카오 계정으로 로그인
로그인 페이지에서 이메일과 비밀번호를 입력하거나, 카카오톡 QR 코드 인증으로 로그인할 수 있어요. 카카오 계정으로 처음 디벨로퍼스에 로그인하면 개발자 약관 동의 화면이 나와요. 서비스 이용 약관과 개인정보 처리방침 등에 동의하면 개발자 계정으로 전환돼요. 이 약관 동의는 최초 1회만 진행하면 되며, 이후에는 바로 대시보드로 이동해요.
대시보드 화면 이해
로그인 후 보이는 대시보드에서는 등록한 애플리케이션 목록을 확인하고 새 앱을 등록할 수 있어요. 처음 가입했다면 등록된 앱이 없는 빈 화면이 보일 거예요. 대시보드 상단에 있는 ‘내 애플리케이션’ 탭과 ‘문서’ 탭을 통해 앱 관리 및 API 문서 확인이 가능해요. 카카오 디벨로퍼스의 공식 문서는 한국어로 매우 잘 정리되어 있으니, 궁금한 사항이 생기면 문서 탭을 적극 활용하세요.
애플리케이션 등록하기
새 애플리케이션 추가
‘내 애플리케이션’ 메뉴에서 ‘애플리케이션 추가하기’ 버튼을 클릭해요. 이 버튼은 보통 상단 우측 또는 목록 영역에서 확인할 수 있어요. 클릭하면 애플리케이션 기본 정보를 입력하는 화면이 나타나요. 앱 아이콘, 앱 이름, 회사 이름을 입력하면 되는데, 앱 이름은 나중에 수정할 수 있으니 테스트 목적이라면 간단한 이름으로 입력해도 돼요.
앱 정보 입력 및 저장
앱 이름은 서비스 이름이나 프로젝트 이름을 입력하면 적당해요. 회사 이름은 개인 개발자라면 자신의 이름이나 닉네임을 입력해도 문제없어요. 앱 아이콘은 선택 사항이므로 일단 건너뛰고 나중에 추가할 수 있어요. 정보를 입력하고 ‘저장’을 클릭하면 앱이 생성되며, 앱 키가 자동으로 발급돼요. 새로 생성된 앱 페이지로 이동하면서 발급된 키를 바로 확인할 수 있어요.
앱 키 종류별 설명
앱이 생성되면 네 종류의 키가 발급돼요.
- Native 앱 키: Android, iOS 앱 개발에 사용해요.
- REST API 키: 서버 사이드에서 카카오 API를 호출할 때 사용해요.
- JavaScript 키: 웹 브라우저에서 카카오 API를 사용할 때 쓰는 키예요. 카카오맵 웹 삽입 시 이 키를 사용해요.
- Admin 키: 관리자 권한의 API 호출에 사용하며, 절대 외부에 노출해서는 안 되는 키예요.
카카오맵 API를 웹에서 사용한다면 JavaScript 키를 복사하여 보관해 두세요.
플랫폼 도메인 등록
웹 플랫폼 등록의 필요성
카카오맵 JavaScript API를 사용하려면 반드시 사용할 도메인을 플랫폼으로 등록해야 해요. 등록되지 않은 도메인에서 API를 호출하면 인증 오류가 발생하여 지도가 로드되지 않아요. 이 설정은 보안을 위한 것으로, 허가된 도메인에서만 API 키가 작동하도록 제한하는 역할을 해요. 내 키를 타인이 무단으로 사용하는 것을 막을 수 있는 중요한 보안 기능이에요.
도메인 등록 방법
앱 설정 페이지에서 ‘플랫폼’ 메뉴를 클릭해요. 웹 플랫폼 섹션에서 ‘플랫폼 등록’ 버튼을 클릭하면 도메인 입력 필드가 나타나요. 여기에 서비스를 운영할 도메인 주소를 입력해요. 도메인 입력 시에는 프로토콜(http:// 또는 https://)을 포함하여 정확하게 입력해야 해요. 여러 개의 도메인을 등록할 때는 줄바꿈으로 구분하여 입력할 수 있어요. 저장 버튼을 클릭하면 도메인 등록이 완료돼요.
로컬 개발 환경 도메인 등록
로컬에서 개발하고 테스트할 때는 http://localhost를 등록해야 해요. 포트 번호를 사용한다면 http://localhost:3000처럼 포트까지 포함하여 등록해요. 자주 사용하는 포트 번호(3000, 8080, 5000 등)를 미리 여러 개 등록해 두면 편리해요. 운영 환경에서는 https://를 사용하는 경우가 많으니, 로컬용 http://localhost와 운영용 https://도메인을 함께 등록해 두는 것이 좋아요.
키 발급 후 첫 테스트
간단한 테스트 코드 작성
키 발급과 도메인 등록이 완료됐다면 간단한 HTML 파일을 만들어 테스트해 볼 수 있어요. head 태그에 카카오맵 SDK를 불러오는 스크립트를 추가하고, body에 지도를 표시할 div를 만들어요. SDK URL에는 발급받은 JavaScript 키를 입력해야 해요. 지도 초기화 코드를 작성하고 브라우저에서 열어보면, 등록한 도메인에서 정상적으로 지도가 로드되는지 확인할 수 있어요.
오류 발생 시 확인 사항
테스트 중 오류가 발생한다면 몇 가지 사항을 확인해 보세요. 먼저 SDK URL에 JavaScript 키를 정확하게 입력했는지 확인해요. 다음으로 현재 접속 중인 도메인이 플랫폼에 등록되어 있는지 확인해요. file://로 HTML 파일을 직접 열었다면 도메인 인증이 안 되니, 로컬 서버를 실행하고 http://localhost로 접근해야 해요. 브라우저 개발자 도구의 콘솔 탭에서 오류 메시지를 확인하면 문제를 파악하는 데 도움이 돼요.
API 키 보안 관리
발급받은 키 중 JavaScript 키는 웹 클라이언트에서 사용되기 때문에 소스 코드에 포함되어 외부에 노출돼요. 이는 불가피한 부분이지만, 도메인 등록을 통해 허가된 도메인에서만 사용되도록 제한하는 것이 최선이에요. 반면 REST API 키와 Admin 키는 절대 프론트엔드 코드에 포함시키면 안 되고, 서버 환경 변수나 서버 코드에서만 사용해야 해요. 깃허브 등 공개 저장소에 키를 올리지 않도록 .env 파일과 .gitignore를 활용하는 습관을 들이세요.
추가 설정과 활용 팁
일별 사용량 모니터링
카카오 디벨로퍼스 대시보드에서 API 사용량을 확인할 수 있어요. 일별 호출 횟수와 남은 무료 쿼터를 확인하여 사용량을 관리하는 것이 중요해요. 무료 제공량을 초과하면 API 호출이 제한될 수 있으므로, 사용량이 늘어나는 시점에 요금제 전환 또는 최적화를 검토해야 해요. 대시보드에서 특정 기간의 사용 현황을 조회하는 기능을 활용하면 트래픽 패턴을 파악하는 데 도움이 돼요.
여러 앱 분리 관리
여러 프로젝트를 진행한다면 프로젝트별로 별도 앱을 생성하여 키를 분리 관리하는 것이 좋아요. 하나의 키를 여러 프로젝트에 공유하면 사용량 파악이 어렵고, 한 프로젝트에 문제가 생겼을 때 다른 프로젝트에도 영향을 미칠 수 있어요. 프로젝트별로 앱을 분리하면 각 서비스의 API 사용량을 독립적으로 관리할 수 있어 효율적이에요.
팀 협업 시 키 공유 방법
팀으로 개발할 때 API 키 공유는 주의가 필요한 부분이에요. 키를 소스 코드에 직접 넣어 깃허브에 올리면 키가 외부에 노출되는 위험이 있어요. 팀원들에게 키를 공유할 때는 .env 파일이나 팀 내 비밀 관리 시스템을 활용하고, .gitignore에 .env를 추가하여 코드 저장소에 올라가지 않도록 하는 것이 기본 보안 수칙이에요. 또한 공개 저장소라면 디벨로퍼스에서 도메인 제한을 철저히 설정하여 무단 사용을 방지하세요.
마무리
카카오맵 API 키 발급은 카카오 계정 준비, 디벨로퍼스 로그인, 앱 생성, 도메인 등록의 네 단계만 거치면 완료돼요. 한 번 발급받은 키는 소속 프로젝트가 존재하는 한 계속 사용할 수 있으며, 새 프로젝트마다 새 앱을 만들어 별도 키를 관리하는 것을 권장해요.
키 발급 후에는 공식 문서의 예제 코드를 참고하여 첫 번째 지도를 화면에 띄워보세요. 지도가 성공적으로 로드되는 순간의 성취감이 개발의 묘미예요. 카카오맵 API를 활용한 멋진 서비스를 만들어 보시길 응원해요.