Lovable 앱에 Google Maps Platform을 연결해 주소 지오코딩, 경로 계산, 장소 검색, 인터랙티브 지도 임베드, 그리고 날씨·대기질·태양광 잠재력 같은 위치 기반 데이터를 가져오세요. 관리형 연결이나 자체 API 키 모두 사용 가능합니다.
Google Maps Platform은 지오코딩, 경로, 장소, 인터랙티브 지도를 위한 Google의 위치 API와 SDK 모음입니다. Google Maps Platform 앱 커넥터는 Lovable 앱이 Lovable 보안 게이트웨이를 통해 서버 사이드 API를 호출하게 하고, 별도의 리퍼러 제한 키로 브라우저에서 인터랙티브 지도를 렌더링합니다. 두 키 모두 워크스페이스 단위로 관리되며 연결한 모든 프로젝트가 사용할 수 있습니다.
Google Maps Platform을 연결하면 앱에서 다음을 할 수 있습니다.
- 주소를 좌표로 변환(지오코딩)하고 좌표를 주소로 역변환
- Routes API로 경로와 이동 시간 계산
- Places API (New)로 장소·비즈니스 검색 및 상세 정보 조회
- 인터랙티브·정적 지도 임베드
- 주소 유효성 검사 및 GPS 트레이스를 도로에 스냅
- 임의의 위치에 대한 환경 데이터(Weather, Air Quality, Pollen, Solar) 가져오기
- Aerial View, Geolocation, Elevation, Time Zone, Route Optimization, Area Insights 사용
위치, 매핑, 내비게이션, 장소 데이터가 백엔드(서버 사이드 호출) 또는 프런트엔드(브라우저 임베디드 지도)에서 필요한 앱에 적합합니다.
일반적인 사용 사례와 예시 앱
| 예시 앱 | 예시 프롬프트 | 설명 |
|---|---|---|
| 부동산 매물 검색 | Build a property listing app where users browse homes on a map, filter by neighborhood, and see commute times from each listing to a chosen address. | 이동 시간 포함 지도 기반 탐색. 임베디드 지도로 둘러보고, 지오코딩으로 핀을 배치하며, Routes API로 각 매물에서 통근 시간을 추정합니다. |
| 지역 비즈니스 디렉터리 | Build a directory app where users search nearby restaurants, view details, and see opening hours and reviews on a map. | 장소 검색과 발견. 검색창에 Places Autocomplete를, 장소 상세·평점·영업 시간 조회에 Places API를 사용합니다. |
| 배송 디스패치 도구 | Build an internal tool that plans delivery routes for drivers, optimizes stop order, and shows estimated arrival times. | 운영을 위한 경로 계산과 ETA. Routes API를 서버 사이드에서 호출해 최적화된 경로를 계산하고 임베디드 지도에 렌더링합니다. |
| 필드 서비스 스케줄링 | Build a scheduling app where dispatchers assign jobs to technicians based on location and see travel times between appointments. | 위치 인지 스케줄링. 작업 주소를 지오코딩하고 Routes API로 연속 예약 간 이동 시간을 계산합니다. |
| 매장 찾기 | Build a store locator page that shows my retail locations on a map, with filters for services offered and an address search. | 검색이 포함된 공개용 지도. Places Autocomplete로 사용자 주소를 받고, 지오코딩으로 지도를 중앙에 두고, 인터랙티브 지도에 인근 매장을 표시합니다. |
| 여행 일정 플래너 | Build a trip planner where users add stops, see them on a map, and view driving distance and time between each leg. | 다중 정차 일정. Places Autocomplete로 정차지를 추가하고, Routes API로 구간·거리를 계산하며, 임베디드 지도로 시각화합니다. |
정확한 동작은 활성화한 Google Maps Platform API, 각 키를 어떻게 제한했는지, Lovable에게 어떻게 빌드를 요청했는지에 따라 달라집니다.
Google Maps Platform 연결의 동작 방식
Google Maps Platform은 일부 API가 서버에서, 다른 API가 브라우저에서 실행되기 때문에 두 개의 키 모델을 사용합니다.
- Server API key: 비공개, API별로 제한됨. Lovable 커넥터 게이트웨이가 Geocoding, Routes, Places, Weather, Air Quality 같은 서버 사이드 API 호출에 사용합니다. 브라우저에 절대 노출되지 않습니다. 게이트웨이는 사용 추적을 위해 워크스페이스별 추적 ID도 함께 첨부합니다.
- Browser API key: 공개, 웹사이트 리퍼러로 제한됨. 연결 폼에서 Public 으로 표시되며 프로젝트에
VITE_LOVABLE_CONNECTOR_GOOGLE_MAPS_BROWSER_KEY라는 공개 환경 변수로 주입됩니다. Maps JavaScript API와 Places Autocomplete를 위해 프런트엔드가 사용합니다.
Lovable 워크스페이스 내에서 여러 Google Maps Platform 연결을 만들 수 있습니다.
서버 사이드 호출은 항상 Lovable 커넥터 게이트웨이를 통합니다. 한도와 동작은 게이트웨이 기반 커넥터를 참고하세요. 브라우저 키는 Maps JavaScript API와 Places API (New)에만 권한이 부여됩니다. Geocoding, Routes, 다른 서버 사이드 API를 브라우저에서 직접 호출하지 마세요. REQUEST_DENIED 로 실패합니다. 대신 게이트웨이를 사용하세요.
Google Maps Platform 사용량은 API 호출과 지도 로드를 기준으로 Google Cloud가 결제 계정에 직접 청구합니다. 자체 키를 가져오는 경우 Lovable이 Google Maps Platform 사용량을 청구하지 않습니다. Google Maps Platform은 반복 월별 무료 사용량을 포함합니다. 최신 정보는 Google Maps Platform 가격을 참고하세요.
Google Maps Platform 연결 방법
워크스페이스 admin 과 owner 가 Google Maps Platform을 연결할 수 있습니다. 연결 추가 시 다음 중에서 선택합니다.
- Managed by Lovable: Google Cloud 계정이나 API 키 없이 가능.
*.lovable.app도메인에서만 작동합니다. - Your own credentials: 자체 서버·브라우저 API 키 사용. 커스텀 도메인에는 필수이며 프로덕션에 권장됩니다.
연결이 생성되면 연결한 프로젝트에서 Google Maps Platform을 사용할 수 있습니다.
아래 단계는 Google Maps Platform을 어떻게 연결할지에 따라 따르세요.
Managed by Lovable
가장 빠른 설정이 필요할 때, 프로토타이핑에 이상적입니다. Google Cloud 계정이나 API 키가 필요 없습니다. Lovable이 자격 증명을 제공하고 관리합니다.
관리형 연결은 *.lovable.app 미리보기 도메인에서만 작동합니다. 프로젝트가 커스텀 도메인을 사용하면 지도가 로드되지 않습니다. 커스텀 도메인에서 Google Maps Platform을 사용하려면 Your own credentials 로 전환하고 브라우저 키의 리퍼러 제한에 커스텀 도메인을 추가하세요. 커스텀 도메인 프로젝트에서 관리형 연결이 감지되면 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 에서 본인만 사용하거나, 워크스페이스 전체를 초대하거나, 특정 사람으로 제한합니다. 자세한 내용은 연결 단위 접근을 참고하세요.
Connect
Connect 를 클릭합니다.
연결되면 Lovable 앱이 *.lovable.app 도메인에서 지오코딩, 경로, 장소, 임베디드 지도에 Google Maps를 사용할 수 있습니다.
Your own credentials
커스텀 도메인이 필요하거나, Google Cloud 결제를 직접 관리하거나, 어떤 API를 활성화할지·각 키를 어떻게 제한할지 전적으로 통제하고 싶다면 자체 자격 증명을 가져오세요.
서로 다른 키로 여러 Google Maps 연결을 만들 수 있습니다. 환경 분리나 서로 다른 Google Cloud 결제 계정 연결에 유용합니다.
모든 Google Maps Platform 사용량은 Lovable이 아닌 Google Cloud가 결제 계정에 직접 청구합니다.
사전 요구 사항
연결 전 다음을 준비하세요.
- 결제가 활성화된 Google Cloud 프로젝트
- 해당 프로젝트에서 사용할 Google Maps Platform API 활성화(1단계 참조)
- 해당 프로젝트에서 API 키를 생성·관리할 권한
- 프로젝트의 도메인(
*.lovable.appURL과 커스텀 도메인 포함) - Lovable 워크스페이스 admin 또는 owner 역할
1단계: 필요한 Google Maps 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를 deprecate 했습니다. 대신 Routes API와 Places API (New)를 사용하세요.
2단계: 서버 API 키 생성
서버 키는 Lovable 커넥터 게이트웨이가 호출합니다. 리퍼러나 IP가 아니라 API로 제한하세요.
자격 증명 페이지 열기
Google Cloud Console 자격 증명 페이지를 열고 프로젝트를 선택합니다.
키 생성
Create credentials → API key 를 클릭합니다.
키 이름 지정
설명적인 이름을 부여합니다(예: Lovable Google Maps Platform server key).
키 편집
Edit API key 를 클릭합니다.
API로 제한
API restrictions 에서 Restrict key 를 선택하고 1단계에서 활성화한 서버 사이드 API 중 앱이 사용하는 것만 활성화합니다.
애플리케이션 제한은 그대로 두기
Application restrictions 에서 None 을 선택한 상태로 둡니다. Lovable 게이트웨이 IP는 공개되지 않으므로 IP 허용 목록을 추가하면 요청이 깨집니다.
저장하고 복사
저장하고 키를 복사합니다. AIza 로 시작하며 39자 길이입니다.
서버 키를 실제로 호출하는 API로만 제한하세요. 키가 유출되어도 영향이 제한됩니다.
3단계: 브라우저 API 키 생성
브라우저 키는 리퍼러로 제한되며 공개 환경 변수로 프런트엔드에 노출됩니다. Lovable 연결 폼에서 이 필드는 Public 으로 표시되며 "This value will be publicly visible in your published app." 라는 캡션이 붙습니다.
키 생성
같은 자격 증명 페이지에서 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 와 Places API (New) 만 활성화합니다. 브라우저 키는 Geocoding, Routes, 기타 서버 사이드 API에 대해 권한이 부여되지 않습니다.
저장하고 복사
저장하고 키를 복사합니다.
브라우저 키는 설계상 공개이며 앱의 프런트엔드 코드에 표시됩니다. 다른 사이트가 재사용하지 못하게 막는 것은 웹사이트 리퍼러 제한입니다. 프로덕션 전에 반드시 설정하세요.
키 잠금에 대한 자세한 내용은 Google의 API 보안 모범 사례를 참고하세요.
4단계: Lovable에 Google Maps Platform 연결
커넥터 열기
Connectors → App connectors 로 이동해 Google Maps Platform 을 선택합니다.
연결 추가
Add connection 을 클릭합니다.
연결 이름 지정
Display name 에 이름을 입력합니다(예: Google Maps Platform Prod).
자체 자격 증명 선택
Your own credentials 를 선택합니다.
서버 키 추가
2단계 키를 Server API Key("Server-restricted API key for backend use (geocoding, directions, places)")에 붙여넣습니다.
브라우저 키 추가
3단계 키를 Browser API Key("Referrer-restricted API key for the Maps JavaScript API (embedded maps, autocomplete)")에 붙여넣습니다.
접근 권한 설정
Who can access this connection 에서 본인만 사용하거나, 워크스페이스 전체를 초대하거나, 특정 사람으로 제한합니다.
Connect
Connect 를 클릭합니다.
연결되면 서버 사이드 호출은 서버 키를 사용해 Lovable 게이트웨이로 라우팅되고, 브라우저 키는 VITE_LOVABLE_CONNECTOR_GOOGLE_MAPS_BROWSER_KEY 로 프런트엔드에서 사용 가능합니다. 연결 폼은 키 형식(AIza + 35자 영숫자)만 검증하며, Google API에 실제로 작동하는지는 검증하지 않습니다. 설정 후 항상 백엔드 요청 하나와 프런트엔드 지도 로드 하나를 테스트하세요.
제한사항
Google Maps Platform 커넥터의 제한사항:
- 관리형 연결은
*.lovable.app도메인에서만 작동합니다. 커스텀 도메인에는 자체 자격 증명을 사용하세요. - 브라우저 키는 Maps JavaScript API와 Places API (New)에만 권한이 부여됩니다. 다른 모든 Google Maps Platform API는 Lovable 게이트웨이를 통해 서버에서 호출해야 합니다.
- 결제와 쿼터는 Lovable이 아니라 Google Cloud에서 관리합니다. Google Cloud 콘솔에서 예산 알림과 쿼터 상한을 설정하세요.
- 커넥터는 최종 사용자별 인증을 지원하지 않습니다. 각 연결은 워크스페이스용 단일 공유 키 세트를 사용합니다.
- 연결 생성 폼은 키 형식만 검증하며 API 제한이나 리퍼러 규칙은 검증하지 않습니다. 설정 후 실제 요청을 반드시 테스트하세요.
- Lovable 커넥터 게이트웨이는 송출 IP 공개 목록을 제공하지 않으므로 서버 키의 IP 기반 제한은 지원되지 않습니다.
자주 발생하는 문제
RefererNotAllowedMapError로 지도 렌더링 실패. 브라우저 키의 웹사이트 제한에 앱이 실제로 제공되는 도메인이 포함되지 않았습니다. Google Cloud 자격 증명 페이지에서 정확한 origin(서브도메인과 프로토콜 포함)을 추가하세요.- 서버 사이드 호출이
REQUEST_DENIED반환. Google Cloud 프로젝트에서 API가 활성화되지 않았거나, 서버 키의 API 제한에 호출하는 API가 포함되지 않았습니다. Google Cloud 콘솔에서 둘 다 다시 확인하세요. - 브라우저에서 호출한
Geocoder또는DirectionsService호출 실패. 브라우저 키는 Geocoding, Routes, 기타 서버 사이드 API에 권한이 없습니다. 해당 호출을 서버로 옮겨 서버 키와 Lovable 게이트웨이를 통해 라우팅되도록 하세요. - 관리형 연결에서 커스텀 도메인 지도 실패. 예상된 동작입니다. 관리형 브라우저 키는
*.lovable.app에 잠겨 있습니다. 자체 자격 증명으로 전환하고 브라우저 키의 리퍼러 제한에 커스텀 도메인을 추가하세요.
Google Maps Platform 연결에서 프로젝트 연결 해제
Editor 이상은 연결 자체를 삭제하지 않고 특정 프로젝트만 연결에서 제거할 수 있습니다. 연결은 다른 프로젝트에서 계속 사용 가능합니다.
프로젝트 연결 해제:
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 를 클릭하고 확인합니다.