Google Maps Platform을 Lovable 앱에 연결하여 주소 지오코딩, 경로 계산, 장소 검색, 인터랙티브 지도 임베드, 날씨, 공기 질, 태양광 잠재력 같은 위치 인식 데이터를 가져옵니다. 관리되는 연결 또는 자체 API 키를 사용합니다.
Google Maps Platform에 앱 연결하기
Google Maps Platform을 Lovable 앱에 연결하여 주소 지오코딩, 경로 계산, 장소 검색, 인터랙티브 지도 임베드, 날씨, 공기 질, 태양광 잠재력 같은 위치 인식 데이터를 가져옵니다. 관리되는 연결 또는 자체 API 키를 사용합니다.
Google Maps Platform은 지오코딩, 라우팅, 장소, 인터랙티브 지도를 위한 Google의 위치 API 및 SDK 모음입니다. Google Maps Platform 앱 커넥터를 통해 Lovable 앱이 Lovable의 안전한 게이트웨이를 통해 server-side API를 호출하고, 별도의 referrer 제한 키를 사용해 브라우저에서 인터랙티브 지도를 렌더링할 수 있습니다. 두 키 모두 워크스페이스 수준에서 관리되므로 연결에 링크하는 모든 프로젝트가 사용할 수 있습니다.
Google Maps Platform이 연결되면 앱에서 다음을 할 수 있습니다:
- 주소 지오코딩 및 좌표 역지오코딩
- Routes API로 경로 및 이동 시간 계산
- Places API (New)로 장소 및 비즈니스 검색 및 세부 정보 검색
- 인터랙티브 및 정적 지도 임베드
- 주소 검증 및 GPS 트레이스를 도로에 스냅
- 모든 위치에 대한 환경 데이터(Weather, Air Quality, Pollen, Solar) 가져오기
- Aerial View, Geolocation, Elevation, Time Zone, Route Optimization, Area Insights 사용
Google Maps Platform은 앱이 백엔드(server-side 호출) 또는 프런트엔드(브라우저의 임베드된 지도)에서 위치, 매핑, 내비게이션 또는 장소 데이터가 필요할 때 적합합니다.
주요 활용 사례 및 예시 앱
| 예시 앱 | 프롬프트 예시 | 설명 |
|---|---|---|
| 부동산 매물 | 사용자가 지도에서 집을 탐색하고, 동네별로 필터링하고, 각 매물에서 선택된 주소까지의 통근 시간을 볼 수 있는 부동산 매물 앱을 만들어줘. | 이동 시간이 포함된 지도 기반 발견. 앱이 탐색에 임베드된 지도를, 핀 배치에 지오코딩을, 각 매물의 통근을 추정하는 데 Routes API를 사용합니다. |
| 로컬 비즈니스 디렉토리 | 사용자가 근처 레스토랑을 검색하고, 세부 정보를 보고, 영업 시간과 리뷰를 지도에서 볼 수 있는 디렉토리 앱을 만들어줘. | 장소 검색과 발견. 앱이 검색 바에 Places Autocomplete를, 장소 세부 정보, 등급, 시간 가져오기에 Places API를 사용합니다. |
| 배송 디스패치 도구 | 드라이버의 배송 경로를 계획하고, 정차 순서를 최적화하고, 예상 도착 시간을 표시하는 내부 도구를 만들어줘. | 운영을 위한 라우팅과 ETA.\ |
| 앱이 server-side에서 Routes API를 호출해 최적화된 경로를 계산하고 임베드된 지도에 렌더링합니다. | ||
| 현장 서비스 스케줄링 | 디스패처가 위치를 기반으로 기술자에게 작업을 할당하고 약속 사이의 이동 시간을 볼 수 있는 스케줄링 앱을 만들어줘. | 위치 인식 스케줄링.\ |
| 앱이 작업 주소를 지오코딩하고 Routes API를 사용해 연속된 약속 사이의 이동 시간을 계산합니다. | ||
| 매장 위치 검색 | 서비스 제공 필터와 주소 검색이 있는 지도에 소매 위치를 표시하는 매장 로케이터 페이지를 만들어줘. | 검색이 있는 공개 지도.\ |
| 앱이 사용자 주소 캡처에 Places Autocomplete를, 지도 중앙 설정에 지오코딩을, 근처 매장 표시에 인터랙티브 지도를 사용합니다. | ||
| 여행 일정 플래너 | 사용자가 정차 지점을 추가하고, 지도에서 보고, 각 구간의 운전 거리와 시간을 볼 수 있는 여행 플래너를 만들어줘. | 다중 정차 일정.\ |
| 앱이 정차 지점 추가에 Places Autocomplete를, 구간과 거리에 Routes API를, 시각화에 임베드된 지도를 사용합니다. |
정확한 동작은 활성화하는 Google Maps Platform API, 각 키를 제한하는 방법, Lovable에게 빌드를 요청하는 내용에 따라 다릅니다.
Google Maps Platform 연결 작동 방식
Google Maps Platform은 일부 API가 서버에서, 다른 API는 브라우저에서 실행되기 때문에 two-key 모델을 사용합니다:
- Server API key: 비공개, API로 제한됨. Lovable의 커넥터 게이트웨이가 Geocoding, Routes, Places, Weather, Air Quality 같은 server-side API를 호출하는 데 사용됩니다. 브라우저에 절대 노출되지 않습니다. 게이트웨이는 사용량 귀속을 위해 워크스페이스별 추적 ID도 첨부합니다.
- Browser API key: 공개, 웹사이트 referrer로 제한됨. 연결 폼에서 Public으로 표시되고
VITE_LOVABLE_CONNECTOR_GOOGLE_MAPS_BROWSER_KEY라는 공개 환경 변수로 프로젝트에 주입됩니다. Maps JavaScript API와 Places Autocomplete를 위해 프런트엔드에서 사용됩니다.
Lovable 워크스페이스 내에서 여러 Google Maps Platform 연결을 만들 수 있습니다.
Server-side 호출은 항상 Lovable의 커넥터 게이트웨이를 통해 이루어집니다. 한도와 동작은 Gateway-based connectors를 참조하세요. 브라우저 키는 Maps JavaScript API와 Places API (New)에만 인가됩니다. 브라우저에서 직접 Geocoding, Routes, 또는 다른 server-side API를 호출하지 마세요. 그러한 요청은 REQUEST_DENIED로 실패합니다. 대신 게이트웨이를 사용하세요.
Google Maps Platform 사용량은 API 호출과 지도 로드에 따라 Google Cloud가 청구 계정으로 직접 청구합니다. 자체 키를 가져올 때 Lovable은 Google Maps Platform 사용량을 청구하지 않습니다. Google Maps Platform에는 반복되는 월간 무료 등급이 포함됩니다. 현재 세부 정보는 Google Maps Platform pricing을 참조하세요.
Google Maps Platform 연결 방법
워크스페이스 admin과 owner가 Google Maps Platform을 연결할 수 있습니다. 연결을 추가할 때 다음 중 선택할 수 있습니다:
- Managed by Lovable: Google Cloud 계정이나 API 키가 필요 없습니다.
*.lovable.app도메인에서만 작동합니다. - Your own credentials: 자체 server 및 browser API 키를 가져옵니다. 커스텀 도메인에 필요하며 운영에 권장됩니다.
연결이 생성되면 Google Maps Platform이 링크한 프로젝트에서 사용 가능해집니다.
Google Maps Platform을 연결하려는 방법에 따라 아래 설정 단계를 따르세요.
Managed by Lovable
가장 빠른 설정을 위해 이 옵션을 선택하세요. 프로토타이핑에 이상적입니다. Google Cloud 계정이나 API 키가 필요 없습니다. Lovable이 자격 증명을 제공하고 관리합니다.
관리되는 연결은 *.lovable.app 미리보기 도메인에서만 작동합니다. 프로젝트가 커스텀 도메인을 사용하면 지도가 로드되지 않습니다. 커스텀 도메인에서 Google Maps Platform을 사용하려면 Your own credentials로 전환하고 브라우저 키의 referrer 제한에 커스텀 도메인을 추가하세요. Lovable은 커스텀 도메인이 있는 프로젝트에서 관리되는 연결을 감지하면 연결 세부 정보와 Publish 대화상자에 경고도 표시합니다.
Google Maps Platform을 연결하려면:
커넥터 열기
Connectors → App connectors를 열고 Google Maps Platform을 선택합니다.
연결 추가
Add connection을 클릭합니다.
연결 이름 지정
Display name에 이름을 입력합니다. 예: Google Maps Platform Managed. 이 이름은 Lovable에서 연결을 식별하는 용도로만 사용됩니다.
관리되는 자격 증명 선택
Managed by Lovable을 선택합니다.
접근 설정
Who can access this connection 아래에서 본인으로 접근을 제한하거나, 전체 워크스페이스를 초대하거나, 특정 사람으로 제한합니다. 자세한 내용은 Connection-level access를 참조하세요.
연결
Connect를 클릭합니다.
연결되면 Lovable 앱이 *.lovable.app 도메인에서 지오코딩, 경로, 장소, 임베드된 지도에 Google Maps Platform을 사용할 수 있습니다.
자체 자격 증명
커스텀 도메인이 필요하거나, Google Cloud 청구를 직접 관리하고 싶거나, 어떤 API가 활성화되어 있고 각 키가 어떻게 제한되는지에 대한 완전한 제어를 원할 때 자체 자격 증명을 가져옵니다.
다른 키를 사용해 여러 Google Maps Platform 연결을 만들 수 있어 환경을 분리하거나 다른 Google Cloud 청구 계정을 첨부할 때 유용합니다.
모든 Google Maps Platform 사용량은 Lovable이 아닌 Google Cloud가 청구 계정으로 청구합니다.
사전 준비 사항
연결하기 전에 다음을 확인하세요:
- 청구가 활성화된 Google Cloud 프로젝트
- 해당 프로젝트에서 사용할 Google Maps Platform API 활성화됨 (Step 1 참조)
- 해당 프로젝트에서 API 키를 만들고 관리할 권한
*.lovable.appURL과 커스텀 도메인을 포함한 프로젝트의 도메인- Lovable 워크스페이스 admin 또는 owner 역할
Step 1: 필요한 Google Maps Platform API 활성화
Google Cloud Console에서 앱이 사용하는 API만 활성화하세요.
브라우저 키의 경우 프런트엔드 API를 활성화합니다:
- Maps JavaScript API
- Places API (New)
선택적으로 서버에서 렌더링된 지도 이미지나 지도 임베드를 원한다면 다음도 활성화합니다:
- Maps Static API
- Maps Embed API
서버 키(Lovable의 게이트웨이를 통해 호출됨)의 경우 앱이 사용하는 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
- Time Zone API
- Weather API
Google은 레거시 Directions API, Distance Matrix API, 원래 Places API를 deprecation했습니다. 대신 Routes API와 Places API (New)를 사용하세요.
Step 2: 서버 API 키 만들기
서버 키는 Lovable의 커넥터 게이트웨이에서 호출됩니다. referrer 또는 IP가 아닌 API로 제한합니다.
자격 증명 열기
Google Cloud Console 자격 증명 페이지를 열고 프로젝트를 선택합니다.
키 생성
Create credentials → API key를 클릭합니다.
키 이름 지정
설명적인 이름을 부여합니다. 예: Lovable Google Maps Platform server key.
키 편집
Edit API key를 클릭합니다.
API로 제한
API restrictions 아래에서 Restrict key를 선택하고 Step 1에서 앱이 사용하는 server-side API만 활성화합니다.
애플리케이션 제한 끄기
Application restrictions 아래에서 None을 선택된 상태로 둡니다. Lovable의 게이트웨이 IP는 게시되지 않으므로 IP allowlist를 추가하면 요청이 깨집니다.
저장하고 복사
저장하고 키를 복사합니다. AIza로 시작하고 39자입니다.
실제로 호출하는 API로만 서버 키를 제한하세요. 이는 키가 유출될 경우 영향을 제한합니다.
Step 3: 브라우저 API 키 만들기
브라우저 키는 referrer 제한이며 공개 환경 변수로 프런트엔드에 노출됩니다. Lovable 연결 폼에서 이 필드는 "This value will be publicly visible in your published app." 캡션과 함께 Public으로 표시됩니다.
키 생성
동일한 자격 증명 페이지에서 Create credentials → API key를 클릭합니다.
키 이름 지정
설명적인 이름을 부여합니다. 예: Lovable Google Maps Platform browser key.
키 편집
Edit API key를 클릭합니다.
웹사이트 referrer로 제한
Application restrictions 아래에서 Websites를 선택하고 앱이 제공되는 모든 도메인을 추가합니다. 예:
https://your-project.lovable.app/*https://yourdomain.com/*및https://www.yourdomain.com/*(커스텀 도메인)
API로 제한
API restrictions 아래에서 Restrict key를 선택하고 Maps JavaScript API와 **Places API (New)**만 활성화합니다. 브라우저 키는 Geocoding, Routes, 또는 다른 server-side API에 인가되지 않습니다.
저장하고 복사
저장하고 키를 복사합니다.
브라우저 키는 의도적으로 공개이며 앱의 프런트엔드 코드에 나타납니다. 웹사이트 referrer 제한은 다른 사이트가 재사용하지 못하게 막는 것이므로 운영에 가기 전에 항상 설정하세요.
키 잠금에 대한 자세한 내용은 Google의 API 보안 모범 사례를 참조하세요.
Step 4: Google Maps Platform을 Lovable에 연결
커넥터 열기
Connectors → App connectors를 열고 Google Maps Platform을 선택합니다.
연결 추가
Add connection을 클릭합니다.
연결 이름 지정
Display name에 이름을 입력합니다. 예: Google Maps Platform Prod.
자체 자격 증명 선택
Your own credentials를 선택합니다.
서버 키 추가
Step 2의 키를 Server API Key("Server-restricted API key for backend use (geocoding, directions, places)")에 붙여넣습니다.
브라우저 키 추가
Step 3의 키를 Browser API Key("Referrer-restricted API key for the Maps JavaScript API (embedded maps, autocomplete)")에 붙여넣습니다.
접근 설정
Who can access this connection 아래에서 본인으로 접근을 제한하거나, 전체 워크스페이스를 초대하거나, 특정 사람으로 제한합니다.
연결
Connect를 클릭합니다.
연결되면 server-side 호출은 서버 키를 사용해 Lovable의 게이트웨이를 통해 라우팅되고, 브라우저 키는 VITE_LOVABLE_CONNECTOR_GOOGLE_MAPS_BROWSER_KEY로 프런트엔드에 사용 가능합니다. 연결 폼은 키 형식(35자의 영숫자가 뒤따르는 AIza와 일치해야 함)을 검증하지만 키가 실제로 Google의 API에 대해 작동하는지는 확인하지 않습니다. 설정 후 항상 하나의 백엔드 요청과 하나의 프런트엔드 지도 로드를 테스트하세요.
제한 사항
Google Maps Platform 커넥터에는 다음과 같은 제한이 있습니다:
- 관리되는 연결은
*.lovable.app도메인에서만 작동합니다. 커스텀 도메인에는 자체 자격 증명을 사용하세요. - 브라우저 키는 Maps JavaScript API와 Places API (New)에만 인가됩니다. 다른 모든 Google Maps Platform API는 Lovable의 게이트웨이를 통해 서버에서 호출해야 합니다.
- 청구 및 할당량은 Lovable이 아닌 Google Cloud에서 관리됩니다. Google Cloud 콘솔에서 예산 알림과 할당량 한도를 설정하세요.
- 커넥터는 end-user별 인증을 지원하지 않습니다. 각 연결은 워크스페이스에 대한 단일 공유 키 세트를 사용합니다.
- 연결 생성 폼은 키 형식만 검증하고 API 제한이나 referrer 규칙은 검증하지 않습니다. 설정 후 항상 실제 요청을 테스트하세요.
- Lovable 커넥터 게이트웨이는 공개 egress IP 목록을 노출하지 않으므로 서버 키의 IP 기반 제한은 지원되지 않습니다.
일반적인 이슈
- 지도가
RefererNotAllowedMapError로 렌더링되지 않음. 브라우저 키의 웹사이트 제한에 앱이 실제로 제공되는 도메인이 포함되지 않습니다. Google Cloud 자격 증명 페이지에 정확한 origin(서브도메인과 프로토콜 포함)을 추가하세요. - Server-side 호출이
REQUEST_DENIED를 반환. Google Cloud 프로젝트에서 API가 활성화되지 않았거나 서버 키의 API 제한에 호출 중인 API가 포함되지 않았습니다. Google Cloud 콘솔에서 둘 다 다시 확인하세요. - 브라우저에서 호출 시
Geocoder또는DirectionsService호출 실패. 브라우저 키는 Geocoding, Routes, 또는 다른 server-side API에 인가되지 않습니다. 해당 호출을 서버로 이동해 서버 키와 함께 Lovable의 게이트웨이를 통해 라우팅되도록 하세요. - 관리되는 연결을 사용한 커스텀 도메인에서 지도 실패. 예상된 동작입니다. 관리되는 브라우저 키는
*.lovable.app에 잠겨 있습니다. 자체 자격 증명으로 전환하고 브라우저 키의 referrer 제한에 커스텀 도메인을 추가하세요.
Google Maps Platform 연결에서 프로젝트 연결 해제 방법
Editors 이상은 연결 전체를 삭제하지 않고 특정 프로젝트만 연결에서 제거할 수 있습니다. 연결은 다른 프로젝트에 대해 그대로 사용 가능한 상태로 유지됩니다.
프로젝트 연결을 해제하려면:
Connectors 열기
Connectors를 열고 App connectors로 이동한 뒤 **Google Maps Platform**을 선택합니다.
연결 열기
관리할 연결을 엽니다.
프로젝트 선택
Linked projects 아래에서 연결을 해제할 프로젝트를 체크합니다.
확인
Unlink projects를 클릭하고 확인합니다.
연결이 해제되면 해당 프로젝트들은 이 연결을 통한 Google Maps Platform 접근을 더 이상 가지지 않습니다. 프로젝트가 다시 Google Maps Platform을 필요로 한다면 사용 가능한 연결에 다시 연결할 수 있습니다.
Google Maps Platform 연결 삭제 방법
워크스페이스 admin과 owner는 Google Maps Platform 연결을 삭제할 수 있습니다. 다른 멤버는 본인이 만든 연결이거나 명시적으로 접근 권한을 부여받은 연결인 경우 삭제할 수 있습니다.
연결 삭제는 영구적이며 되돌릴 수 없습니다. 모든 연결된 프로젝트에서 자격 증명이 제거되고, 이 연결을 사용하는 앱은 새 연결이 추가될 때까지 작동을 멈춥니다.
삭제하기 전에 Linked projects 섹션을 검토하여 현재 어떤 프로젝트가 이 연결을 사용 중인지 확인하세요.
연결을 삭제하려면:
Connectors 열기
Connectors를 열고 App connectors로 이동한 뒤 **Google Maps Platform**을 선택합니다.
연결 열기
제거할 연결을 엽니다.
연결된 프로젝트 검토
Linked projects 섹션을 검토합니다.
삭제
Delete this connection 아래의 Delete를 클릭하고 확인합니다.