Google Maps Platform을 연결해 주소 지오코딩, 경로 계산, 장소 검색, 인터랙티브 지도, 날씨와 공기질 같은 위치 데이터를 사용합니다.
Google Maps Platform에 앱 연결하기
Google Maps Platform을 Lovable 앱에 연결해 주소를 지오코딩하고, 경로를 계산하고, 장소를 검색하고, 인터랙티브 지도를 임베드하고, 날씨와 공기질 같은 위치 데이터를 가져오세요. 관리형 연결 또는 자체 API 키를 사용할 수 있습니다.
Google Maps Platform은 지오코딩, 라우팅, 장소, 인터랙티브 지도를 위한 Google의 위치 API 및 SDK 제품군입니다. Google Maps Platform 커넥터를 사용하면 Lovable 앱이 Lovable의 connector gateway를 통해 Google의 위치 API를 호출하고 브라우저에서 인터랙티브 지도를 렌더링할 수 있습니다. 이 커넥터는 화면에 보이든 백그라운드에서 동작하든 위치, 지도, 내비게이션, 장소 데이터가 필요한 앱을 위해 설계되었습니다.
Google Maps Platform은 앱 + 채팅 커넥터로 제공됩니다. 하나의 공유 연결이 빌드 중 프로젝트 채팅과 게시된 앱 모두에서 작동합니다.
Google Maps Platform을 사용하면 앱은 다음 작업을 할 수 있습니다.
- 주소를 좌표로, 좌표를 주소로 변환
- 경로, 이동 시간, distance matrix 계산
- 장소와 비즈니스를 검색하고 세부 정보, 영업 시간, 평점 표시
- 마커와 주소 autocomplete가 있는 인터랙티브 또는 임베드 지도, 정적 지도 이미지 표시
- 주소 검증 및 GPS trace를 도로에 스냅
- 위치의 날씨, 공기질, 꽃가루, 태양광 데이터 조회
- Aerial View, Geolocation, Elevation, Time Zone, Route Optimization, Area Insights 사용
Google Maps Platform은 앱에 Google의 지도 및 장소 데이터가 필요하거나 관리형 연결로 몇 분 안에 작동하는 지도를 만들고 싶을 때 적합합니다.
주요 사용 사례 및 예시 앱
다음 예시는 Google Maps Platform으로 빌드할 수 있는 앱과 시작 프롬프트를 보여줍니다.
| 예시 앱 | 예시 프롬프트 | 설명 |
|---|---|---|
| 부동산 매물 | Use Google Maps Platform and build a property listing app where people browse homes on a map, filter by neighborhood, and see commute times to a chosen address. | 이동 시간이 포함된 지도 기반 탐색입니다. 앱이 인터랙티브 지도에 매물을 표시하고, 각 주소를 지오코딩해 핀을 배치하고, Routes API로 통근 시간을 계산합니다. |
| 로컬 비즈니스 디렉터리 | Use Google Maps Platform and build a directory where people search nearby restaurants and see details, opening hours, and ratings on a map. | 장소 검색과 발견입니다. 앱이 검색창의 address autocomplete와 Places API를 사용해 세부 정보, 평점, 영업 시간을 가져옵니다. |
| 배송 배차 도구 | Use Google Maps Platform and build an internal tool that plans delivery routes for drivers, optimizes stop order, and shows estimated arrival times. | 운영을 위한 라우팅과 도착 시간입니다. 앱이 Routes API로 최적화된 경로를 계산하고 임베드 지도에 그립니다. |
| 현장 서비스 스케줄링 | Use Google Maps Platform and build a scheduling app where dispatchers assign jobs to technicians by location and see travel times between appointments. | 위치 인식 스케줄링입니다. 앱이 작업 주소를 지오코딩하고 Routes API로 연속된 약속 사이의 이동 시간을 계산합니다. |
| 매장 찾기 | Use Google Maps Platform and build a store locator that shows my retail locations on a map, with an address search and filters for services offered. | 검색이 있는 공개 지도입니다. 앱이 autocomplete로 방문자 주소를 받고 지도를 해당 위치로 가운데 정렬한 뒤 가까운 매장을 보여줍니다. |
| 여행 일정 플래너 | Use Google Maps Platform and build a trip planner where people add stops, see them on a map, and view driving distance and time between each leg. | 여러 경유지가 있는 일정입니다. 앱이 autocomplete로 경유지를 추가하고 Routes API로 각 구간을 계산한 뒤 임베드 지도에 여정을 그립니다. |
Google Maps Platform 연결 작동 방식
Google Maps Platform은 일부 API가 서버에서 실행되고 다른 API는 브라우저에서 실행되기 때문에 두 개의 API 키를 사용합니다.
- server key는 비공개입니다. Lovable의 connector gateway가 Geocoding, Routes, Places, Weather, Air Quality 같은 서버 측 API를 호출할 때 사용합니다. 이 키는 브라우저에 도달하지 않습니다.
- browser key는 공개입니다. 앱의 프런트엔드가 지도를 로드할 때 사용합니다. 인터랙티브 지도를 위한 Maps JavaScript API, map embed, 정적 지도 이미지가 여기에 포함됩니다. 연결 폼은 이 키를 Public으로 표시하며, Lovable은 이 값을
VITE_LOVABLE_CONNECTOR_GOOGLE_MAPS_BROWSER_KEY환경 변수로 앱 프런트엔드에 노출하므로 게시된 앱 코드에 나타납니다.
지도 로드를 제외한 모든 작업은 server key를 사용해 gateway를 거칩니다. 여기에는 address autocomplete와 place details도 포함됩니다. 관리형 browser key는 Maps JavaScript, Maps Embed, Maps Static, Map Tiles API에만 승인되어 있으며, 3단계에서는 자체 browser key도 같은 방식으로 제한합니다. Places, Geocoding, Routes, 그 밖의 서버 측 API를 브라우저에서 호출하면 REQUEST_DENIED로 실패합니다.
gateway를 통한 서버 측 요청은 연결 유형마다 워크스페이스당 24시간 기준 6,000 요청으로 제한됩니다. 관리형 연결과 자체 자격 증명 연결은 각각 별도의 6,000건을 가집니다. 브라우저가 browser key로 Google에 보내는 요청은 이 한도에 포함되지 않습니다.
Google Maps Platform 연결 방법
Google Maps Platform 연결을 만들 수 있는 사람은 플랜과 워크스페이스 설정에 따라 달라집니다. 앱 + 채팅 커넥터는 Free, Pro, Business 플랜에서 기본으로 사용할 수 있습니다. Enterprise 플랜에서는 처음에는 사실상 비활성화되어 있습니다. 관리자가 Connectors → Admin settings → App + chat connectors에서 변경하기 전까지 Who can create connections and clients가 기본적으로 No one입니다.
연결을 추가할 때 두 옵션 중 하나를 선택합니다.
- Managed by Lovable: Lovable이 자격 증명을 제공하고 관리합니다. 등록은 필요 없으며 프로덕션용은 아닙니다. 커스텀 도메인에서는 지도가 로드되지 않습니다.
- Use your own credentials: 자체 server 및 browser API 키를 연결합니다. 커스텀 도메인과 프로덕션 앱에 필요합니다.
연결을 만든 뒤에는 사용하려는 프로젝트에 연결을 링크할 수 있습니다. 프로젝트에서 빌드하는 사람은 누구나 프로젝트 채팅에서 Lovable에게 이 연결을 프로젝트에 링크해 달라고 요청할 수 있습니다.
원하는 옵션에 따라 아래 설정 단계를 따르세요.
프로토타입을 만드는 동안 가장 빠르게 설정하려면 이 옵션을 선택하세요. Google Cloud 계정이나 API 키가 필요하지 않습니다.
관리형 연결은 *.lovable.app 도메인에서 작동하며 커스텀 도메인에서는 지도를 로드하지 않습니다. Lovable은 연결에 Custom domains 안내를 표시하고, 관리형 연결을 사용하는 프로젝트에 커스텀 도메인이 있으면 Publish 대화상자에서 경고합니다. 커스텀 도메인에서 Google Maps Platform을 사용하려면 Use your own credentials 연결을 추가하고 browser key의 website restrictions에 커스텀 도메인을 넣으세요.
관리형 연결은 프로토타이핑과 프리뷰용이며 프로덕션용이 아닙니다. Lovable의 connector gateway를 통한 서버 측 요청은 워크스페이스당 24시간 기준 6,000건으로 제한됩니다. 서비스를 출시할 때는 Use your own credentials 연결을 추가해 사용량이 본인의 Google Cloud 프로젝트와 청구 계정에서 처리되도록 하세요. 자체 자격 증명도 gateway를 통한 별도의 6,000건 요청 한도를 가지므로, 전환은 gateway 한도를 없애는 것이 아니라 청구 주체를 바꾸는 것입니다.
워크스페이스당 관리형 Google Maps Platform 연결은 하나만 만들 수 있습니다. 이미 존재하면 해당 연결을 삭제하기 전까지 폼에서 Managed by Lovable 옵션을 사용할 수 없습니다.
Connectors에서 Google Maps Platform 열기
Connectors를 열고 Google Maps Platform을 선택합니다. 카탈로그를 여는 다른 위치는 Where to find connectors를 참고하세요.
연결 추가하기
Add connection을 클릭합니다.
연결 이름 지정하기
Display name에 Google Maps Platform처럼 연결 이름을 지정합니다. 이 이름은 Lovable 안에서 연결을 식별하는 용도로만 사용됩니다.
Managed by Lovable 선택하기
Authentication 아래에서 Managed by Lovable을 선택합니다. 이 옵션에는 자격 증명 필드가 표시되지 않으며 폼에 Custom domains 안내가 표시됩니다.
이 연결을 사용할 수 있는 사람 선택하기
관리형 연결은 기본적으로 전체 워크스페이스와 공유됩니다. 사용할 사람을 제한하려면 Sharing 아래에서 Restrict to specific people을 클릭합니다.
자세한 내용은 Who can use connections and clients를 참고하세요.
연결하기
Connect를 클릭합니다.
앱이 커스텀 도메인을 사용하거나, 프로덕션으로 전환하거나, 어떤 API를 활성화하고 각 키를 어떻게 제한할지 제어하려면 이 옵션을 선택하세요.
서로 다른 키로 여러 Google Maps Platform 연결을 만들 수 있습니다. 환경을 분리하거나 서로 다른 Google Cloud 청구 계정을 붙일 때 유용합니다.
전제 조건
자체 자격 증명으로 Google Maps Platform을 연결하기 전에 다음을 준비하세요.
- 청구가 활성화된 Google Cloud 프로젝트
- 해당 프로젝트에서 API를 활성화하고 API 키를 만들 수 있는 권한
- 앱의 도메인.
*.lovable.appURL과 모든 커스텀 도메인이 포함됩니다. - Lovable 워크스페이스에서 create connections 권한. Who can create connections and clients를 참고하세요.
이 연결을 통한 모든 Google Maps Platform 사용량은 API 호출과 지도 로드에 따라 Google Cloud가 청구 계정에 청구합니다. Google Maps Platform에는 반복 월간 무료 등급이 포함됩니다. Google Maps Platform pricing을 참고하세요. 청구와 할당량은 Lovable이 아닌 Google에서 직접 처리하므로 Google Cloud 콘솔에서 예산 알림과 할당량 한도를 설정하세요.
1단계: 필요한 API 활성화
Google Maps Platform은 API별로 과금하므로 앱이 사용하는 API만 활성화하세요. Google Cloud console에서 프로젝트의 APIs & Services를 엽니다.
browser key에는 앱이 브라우저에서 로드하는 API를 활성화합니다.
- Maps JavaScript API
- Maps Embed API, 앱이 지도를 임베드하는 경우
- Maps Static API, 앱이 정적 지도 이미지를 보여주는 경우
server key에는 앱이 Lovable gateway를 통해 호출하는 API를 활성화합니다. 커넥터는 다음 API를 모두 라우팅합니다.
- Geocoding API
- Routes API
- Places API (New)
- Address Validation API
- Aerial View API
- Air Quality API
- Geolocation API
- Maps Elevation API
- Maps Platform Datasets API
- Places Aggregate API (Area Insights)
- Pollen API
- Roads API
- Route Optimization API
- Solar API
- Street View Static API
- Time Zone API
- Weather API
Google은 legacy Directions API, Distance Matrix API, original Places API를 deprecated 처리했으며 커넥터는 해당 API 호출을 거부합니다. Lovable은 대신 Routes API와 Places API (New)를 사용합니다.
2단계: server API key 만들기
server key는 Lovable connector gateway에서 사용하므로 API로 제한하세요. 앱이 호출하는 API만 허용하면 키가 유출되더라도 영향을 줄일 수 있습니다. website restriction은 추가하지 마세요. gateway 요청에는 referrer가 없으므로 referrer 제한 키는 모든 서버 호출을 거부합니다.
Credentials 열기
Google Cloud console에서 Credentials page를 열고 프로젝트를 선택합니다.
키 만들기
Create credentials → API key를 클릭합니다.
키 이름 지정하기
Lovable Google Maps Platform server key처럼 설명적인 이름을 지정합니다.
키 편집하기
Edit API key를 클릭합니다.
API로 제한하기
API restrictions 아래에서 Restrict key를 선택하고 Step 1에서 앱이 사용하는 서버 측 API만 선택합니다.
애플리케이션 제한 설정하기
Application restrictions 아래에서 None을 선택한 상태로 두거나 IP addresses를 선택하고 IP allowlisting의 Lovable gateway 범위를 추가합니다. 이 키에는 절대 Websites를 선택하지 마세요.
저장하고 복사하기
저장하고 키를 복사합니다. AIza로 시작하며 길이는 39자입니다.
3단계: browser API key 만들기
browser key는 의도적으로 공개이며 앱 프런트엔드 코드에 나타납니다. website restriction이 다른 사이트의 재사용을 막습니다.
키 만들기
같은 Credentials 페이지에서 Create credentials → API key를 클릭합니다.
키 이름 지정하기
Lovable Google Maps Platform browser key처럼 설명적인 이름을 지정합니다.
키 편집하기
Edit API key를 클릭합니다.
웹사이트로 제한하기
Application restrictions 아래에서 Websites를 선택하고 앱이 제공되는 모든 도메인을 추가합니다. 예를 들어 https://your-project.lovable.app/*, 커스텀 도메인용 https://yourdomain.com/* 및 https://www.yourdomain.com/*를 추가합니다.
API로 제한하기
API restrictions 아래에서 Restrict key를 선택하고 Maps JavaScript API를 선택합니다. Step 1에서 활성화했다면 Maps Embed API와 Maps Static API도 선택합니다. Places, Geocoding, Routes, 그 밖의 서버 측 API는 이 키에서 제외하세요. Lovable은 server key로 gateway를 통해 해당 API를 호출합니다.
저장하고 복사하기
저장하고 키를 복사합니다. AIza로 시작하며 길이는 39자입니다.
server key는 비밀번호처럼 작동합니다. 안전하게 보관하고 절대 공개적으로 공유하지 마세요. 게시하기 전에 browser key의 website restriction을 설정하세요. 다음 단계에서 두 키가 모두 필요합니다.
자세한 내용은 Google 문서의 API security best practices를 참고하세요.
4단계: Google Maps Platform을 Lovable에 연결하기
서로 다른 키로 여러 연결을 만들 수 있습니다.
Connectors에서 Google Maps Platform 열기
Connectors를 열고 Google Maps Platform을 선택합니다. 카탈로그를 여는 다른 위치는 Where to find connectors를 참고하세요.
연결 추가하기
Add connection을 클릭합니다.
연결 이름 지정하기
Display name에 Google Maps Platform Prod처럼 연결 이름을 지정합니다. 이 이름은 Lovable 안에서 연결을 식별하는 용도로만 사용됩니다.
자체 자격 증명 선택하기
Authentication 아래에서 Use your own credentials를 선택합니다. 폼에는 두 키를 사용하라는 짧은 안내가 표시됩니다.
server key 추가하기
Step 2의 키를 Server API Key에 붙여 넣습니다. 필드 옆의 Create key를 누르면 Google Cloud Credentials 페이지가 열립니다.
browser key 추가하기
Step 3의 키를 Browser API Key에 붙여 넣습니다. 이 값은 게시된 앱에 나타나므로 필드가 Public으로 표시됩니다.
이 연결을 사용할 수 있는 사람 선택하기
Sharing 아래에서 연결은 기본적으로 본인에게만 비공개이며 Private 라벨이 표시됩니다. 공유하려면 Share with others를 클릭합니다. 그런 다음 이메일로 워크스페이스 멤버를 추가하거나 Invite entire workspace를 클릭해 Lovable 워크스페이스의 모든 사람이 연결을 사용할 수 있게 합니다.
자세한 내용은 Who can use connections and clients를 참고하세요.
연결하기
Connect를 클릭합니다. Lovable은 각 키의 형식이 올바른지만 확인하고 Google을 호출해 테스트하지 않습니다. 키 제한 때문에 테스트가 실패할 수 있기 때문입니다. 연결 후 Lovable에게 지도 하나와 주소 조회 하나를 요청해 두 키가 모두 작동하는지 확인하세요.
연결되면 프로젝트에서 빌드하는 사람은 누구나 구성된 연결 수준 접근 권한에 따라 프로젝트 채팅에서 Lovable에게 프로젝트를 Google Maps Platform에 링크해 달라고 요청할 수 있습니다. 그러면 Lovable 앱이 Google Maps Platform으로 지오코딩, 라우팅, 장소 검색, 지도 표시를 할 수 있습니다.
제한 사항
Google Maps Platform 커넥터는 다음을 할 수 없습니다.
- 관리형 연결로 커스텀 도메인에서 지도를 로드할 수 없습니다. 관리형 browser key는 Lovable 도메인으로 제한됩니다.
- 각 연결 유형에 대해 워크스페이스당 24시간 기준 6,000개의 서버 측 gateway 요청을 초과할 수 없습니다.
- legacy Directions, Distance Matrix, original Places API를 호출할 수 없습니다. Google이 deprecated 처리했으며 gateway가 해당 경로를 거부합니다.
- 최종 사용자별 Google 로그인을 지원할 수 없습니다. 각 연결은 링크된 모든 프로젝트가 공유하는 하나의 키 세트를 나타냅니다.
- Google이 Maps Platform을 금지한 지역에서 작동할 수 없습니다. 중국, 쿠바, 이란, 북한, 시리아, 베트남, 크림반도와 우크라이나의 다른 점령 지역이 포함됩니다. Lovable은 해당 위치에서 연결과 gateway 요청을 차단하고 Google's list를 안내합니다.
문제 해결
지도 또는 위치 요청이 실패한다면 아래 섹션에서 가장 흔한 오류와 해결 방법을 확인하세요.
Google Maps Platform 연결 관리하기
연결은 Connectors에서 관리합니다. **Google Maps Platform**을 선택한 다음 연결을 엽니다.
- Unlink projects로 특정 프로젝트에서 Google Maps Platform 접근을 제거하면서도 다른 프로젝트에서는 연결을 계속 사용할 수 있게 둡니다. 단계는 Unlink projects from a connection을 참고하세요.
- Delete the connection으로 워크스페이스에서 연결을 완전히 제거합니다. 삭제는 영구적입니다. 링크된 모든 프로젝트에서 자격 증명을 제거하며, Google Maps Platform을 사용하는 앱 기능은 새 연결을 추가할 때까지 작동하지 않습니다. 단계와 삭제 가능한 사람은 Delete a connection을 참고하세요.