앱에 지도를 추가하는 방법: 임베드, 인터랙티브 지도, 매장 찾기

앱에 지도를 추가하려면 먼저 정적 임베드(핀 하나가 있는 위치, 예를 들어 "매장 찾기")가 필요한지, 아니면 인터랙티브 지도(데이터에서 가져온 많은 핀, 필터, 클러스터링, "내 근처")가 필요한지 정하세요. 위치가 하나뿐이라면 임베드된 지도가 가장 빠르고, Google의 Maps Embed API를 쓰면 무료예요. 인터랙티브 지도라면 자바스크립트 지도 라이브러리를 쓰세요. Google Maps JavaScript API, Mapbox GL JS, 또는 타일 제공업체와 함께 쓰는 오픈소스 Leaflet 중에서 고를 수 있어요. 각 장소의 위도와 경도를 데이터베이스에 저장하고, 지도 API 키는 여러분의 도메인으로 제한하세요. 아래의 벤더 세부 정보는 2026년 9월 기준 각 제공업체의 문서에서 가져왔어요.

어떤 지도가 필요한가요?

대부분의 작은 사업장 사이트는 첫 번째 행만 필요해요. 디렉터리, 마켓플레이스, 목록 사이트는 세 번째와 네 번째가 필요해요.

선택지

Google Maps Platform

Google의 시작 가이드에 따르면 결제가 활성화된 Cloud 프로젝트를 만들고, 원하는 API를 활성화해야 해요. 종량제 요금은 Dynamic Maps를 포함한 Essentials SKU에 월 10,000건의 무료 이벤트 한도를 주고, 그 이상은 Dynamic Maps가 1,000건당 $7.00(첫 번째 볼륨 구간 기준)이라고 나와 있어요. Maps Embed SKU는 무제한 무료로 표시되어 있어요. Google은 월간 구독 요금제도 판매해요. 최신 요금은 Google Maps Platform 가격에서 확인하세요.

Mapbox

Mapbox 가격 페이지에는 웹에서 Mapbox GL JS의 월간 지도 로드 50,000건이 무료이고, 이후 1,000건당 $5.00이라고 나와 있어요. Mapbox 가격을 참고하세요.

Leaflet과 OpenStreetMap

Leaflet은 스스로를 모바일에 친화적인 인터랙티브 지도를 위한 오픈소스 자바스크립트 라이브러리이며, 약 42KB 크기라고 설명해요. 지도 타일(지도 이미지)은 어딘가에서 가져와야 해요. OpenStreetMap의 공개 타일 서버는 유혹적이지만, 타일 사용 정책은 눈에 보이는 출처 표시를 요구하고, 대량 다운로드를 금지하고, 서비스 보장이 없으며, 상업 서비스에는 접근이 중단될 수 있다고 경고해요. 실제 제품이라면 Leaflet과 함께 쓸 수 있는 상용 또는 자체 호스팅 타일 소스를 쓰세요.

API 키: 공개되지만 제한하세요

브라우저에서 쓰는 지도 키는 페이지를 여는 누구에게나 보여요. 이는 예상된 동작이지만, 누군가 키를 복사해서 여러분의 요금으로 사용할 수 있다는 뜻이에요. Google의 보안 가이드는 여러분의 도메인을 나열하는 웹사이트(HTTP 리퍼러) 제한과, 사용하는 API에서만 키가 작동하도록 하는 API 제한을 추가하라는 것이에요.

지오코딩처럼 서버 측 서비스의 키(예: 수천 개의 주소를 좌표로 바꾸는 작업)는 별도의 키로 만들고 서버 측 시크릿에 보관해야 해요. 또한 제공업체 콘솔에서 예산 알림이나 할당량을 설정해서, 실수가 큰 요금으로 이어지지 않게 하세요.

지오코딩: 주소는 한 번만 좌표로 바꾸기

지도는 주소가 아니라 위도와 경도를 표시해요. 주소를 좌표로 바꾸는 것을 지오코딩이라고 하며, 대부분의 제공업체는 요청마다 요금을 받아요. 효율적인 패턴은 다음과 같아요:

1. 목록이 저장될 때 서버에서 주소를 지오코딩하세요.
2. 위도와 경도를 데이터베이스에 저장하세요.
3. 지도는 저장된 좌표를 읽을 뿐, 페이지를 볼 때 지오코딩하지 않아요.

지오코딩 결과를 얼마나 오래 저장해도 되는지는 제공업체마다 약관이 다르니 확인하세요.

프롬프트 예시

단일 임베드 지도:

연락처 페이지에 임베드된 Google 지도를 추가해 줘. 주소는 12 High Street, Leeds이고, Maps Embed API를 쓰고, 키는 GOOGLE_MAPS_EMBED_KEY에 넣어 줘. 그 아래에 "길 찾기" 링크를 추가해. 휴대폰에서는 전체 너비로 보여 주고, 지연 로드해 줘.

listings의 인터랙티브 지도:

listings 테이블에 위도와 경도를 추가해 줘. 목록이 생성되거나 주소가 바뀌면 서버에서 GEOCODING_API_KEY에 있는 키로 지오코딩하고 좌표를 저장해. Browse 페이지에는 Leaflet으로 목록마다 마커가 있는 지도를 보여 주고, 마커가 겹치면 클러스터링해 줘. 마커를 클릭하면 제목, 가격, 링크를 보여 줘. 지도와 목록은 같은 필터를 사용해야 해.

"내 근처":

"내 근처" 버튼을 추가해 줘. 방문자의 위치를 요청하고 10km 이내의 목록을 거리순으로 보여 줘. 위치 접근을 거부하면 도시 이름을 입력할 수 있게 해 줘.

단계별 진행

1. 위 표에서 지도 종류를 고르세요.
2. 제공업체 계정과 프로젝트를 만들고, 필요한 API만 활성화하세요.
3. 키를 만드세요: 여러분의 도메인(만드는 동안에는 미리보기 도메인 포함)으로 제한한 브라우저 키, 그리고 필요하면 지오코딩용 서버 키.
4. 키를 시크릿으로 저장하고, AI 빌더가 이를 쓰도록 요청하세요. 브라우저 키는 페이지에 들어가더라도 여전히 제한해 두세요.
5. 모든 장소의 좌표를 데이터베이스에 저장하세요.
6. 지도를 만드세요: 마커, 팝업, 클러스터링, 적절한 기본 줌.
7. 목록과 함께 보여 주세요. 지도만 있으면 휴대폰이나 스크린 리더에서 쓰기 어려워요. 같은 결과를 목록으로도 보여 주세요.
8. 제공업체 콘솔에서 예산 알림을 설정하세요.
9. 공개된 도메인에서 테스트하세요. 리퍼러 제한은 실제 도메인을 추가하기 전까지 지도가 막히는 경우가 많아요.

흔한 실수

• 제한 없는 키. 누구나 자기 사이트에서 재사용할 수 있어요.
• 페이지를 볼 때마다 지오코딩. 느리고 비싸요. 저장할 때 한 번만 지오코딩하세요.
• 키 제한에 실제 도메인을 빼먹음. 미리보기에서는 되지만 운영 환경에서는 회색 상자만 보여요.
• 지도만 있는 레이아웃. 목록 없는 핀은 작은 화면에서 불편하고 접근성도 떨어져요.
• 클러스터링 없이 수백 개의 마커. 읽기 어렵고 느려요.
• 출처 표시 누락. 대부분의 지도와 타일 제공업체는 출처 표시를 요구하며, 이를 숨기면 약관을 어기는 거예요.
• 페이지가 열릴 때 위치 권한 요청. "내 근처"를 누를 때만 요청하세요.

체크리스트

• 작업에 맞는 지도 종류를 골랐어요
• 브라우저 키가 여러분의 도메인과 필요한 API로 제한되어 있어요
• 서버 측 키는 시크릿에 보관돼요
• 좌표는 데이터베이스에 저장되고 한 번만 지오코딩돼요
• 결과는 목록으로도 보여요
• 마커가 많으면 클러스터링을 써요
• 출처 표시가 보여요
• 제공업체에서 예산 알림을 설정했어요
• 공개된 도메인과 휴대폰에서 테스트했어요

Mythex에서 지도 추가하기

Mythex에는 내장 지도 연동이 없어요. 여러분의 제공업체 키를 가져와서, 프로젝트 시크릿으로 추가하거나(에이전트가 시크릿 카드를 보여 주면 그때 붙여 넣어도 돼요), 채팅에서 지도를 요청하세요. 방법은 모든 API 연동하기에 설명되어 있어요. 좌표는 프로젝트의 데이터베이스에 저장하세요. 키의 웹사이트 제한에 미리보기 도메인과 공개된 도메인을 모두 추가하는 것을 잊지 마세요. 시크릿을 바꾼 뒤에는 다시 공개하세요.

지도는 보통 검색 및 목록과 함께 쓰여요. 앱에 검색을 추가하는 방법, 디렉터리 웹사이트 만드는 방법, 소규모 사업자 웹사이트 만드는 방법을 참고하세요.

자주 묻는 질문