Google 지도 그라운딩
Google 지도 그라운딩
Grounding with Google Maps는 Gemini의 생성 능력과 Google Maps의 풍부하고 사실적이며 최신의 데이터를 연결해요. 이 기능은 개발자가 애플리케이션에 위치 인식 기능을 쉽게 통합할 수 있게 해줘요. 사용자 쿼리에 Maps 데이터와 관련된 컨텍스트가 있을 때 Gemini 모델은 Google Maps를 활용해 사용자가 지정한 위치나 일반 지역에 관련된 사실적으로 정확하고 신선한 답변을 제공해요.
- 정확하고 위치 인식적인 응답: 지리적으로 특정한 쿼리에 Google Maps의 광범위하고 최신 데이터를 활용해요.
- 향상된 개인화: 사용자가 제공한 위치에 따라 추천과 정보를 맞춤화해요.
출처: 원문
본문
시작하기
이 예시는 사용자 쿼리에 정확하고 위치 인식적인 응답을 제공하도록 애플리케이션에 Grounding with Google Maps를 통합하는 방법을 보여줘요. 프롬프트는 선택적 사용자 위치와 함께 로컬 추천을 요청해 Gemini 모델이 Google Maps 데이터를 사용할 수 있게 해요.
from google import genai
from google.genai import types
client = genai.Client()
prompt = "What are the best Italian restaurants within a 15-minute walk from here?"
response = client.models.generate_content(
model='gemini-3.8-flash',
contents=prompt,
config=types.GenerateContentConfig(
# Turn on grounding with Google Maps
tools=[types.Tool(google_maps=types.GoogleMaps())],
# Optionally provide the relevant location context (this is in Los Angeles)
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
lat_lng=types.LatLng(
latitude=34.050481, longitude=-118.248526))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in grounding.grounding_chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function generateContentWithMapsGrounding() {
const response = await ai.models.generateContent({
model: "gemini-3.8-flash",
contents: "What are the best Italian restaurants within a 15-minute walk from here?",
config: {
// Turn on grounding with Google Maps
tools: [{ googleMaps: {} }],
toolConfig: {
retrievalConfig: {
// Optionally provide the relevant location context (this is in Los Angeles)
latLng: {
latitude: 34.050481,
longitude: -118.248526,
},
},
},
},
});
console.log("Generated Response:");
console.log(response.text);
const grounding = response.candidates[0]?.groundingMetadata;
if (grounding?.groundingChunks) {
console.log("-".repeat(40));
console.log("Sources:");
for (const chunk of grounding.groundingChunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
}
generateContentWithMapsGrounding();
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMI...EY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "What are the best Italian restaurants within a 15-minute walk from here?"
}]
}],
"tools": [{"googleMaps": {}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 34.050481, "longitude": -118.248526}
}
}
}'
Grounding with Google Maps의 작동 방식
Grounding with Google Maps는 Maps API를 그라운딩 소스로 사용해 Gemini API를 Google Geo 생태계에 통합해요. 사용자 쿼리에 지리적 컨텍스트가 포함되면 Gemini 모델이 Grounding with Google Maps 도구를 호출할 수 있어요. 그런 다음 모델은 제공된 위치와 관련된 Google Maps 데이터에 기반한 응답을 생성할 수 있어요.
이 프로세스는 일반적으로 다음과 같아요.
- 사용자 쿼리: 사용자가 애플리케이션에 쿼리를 제출하며, 지리적 컨텍스트를 포함할 수 있어요(예: "내 근처 커피숍", "샌프란시스코의 박물관").
- 도구 호출: Gemini 모델이 지리적 의도를 인식하고 Grounding with Google Maps 도구를 호출해요. 이 도구에는 선택적으로 사용자의
latitude와longitude가 제공될 수 있어요. 도구는 텍스트 검색 도구이고 Maps에서 검색하는 것과 유사하게 동작해요. "내 근처" 같은 로컬 쿼리는 좌표를 사용하지만, 특정하거나 비로컬 쿼리는 명시적 위치의 영향을 받지 않을 가능성이 높아요. - 데이터 검색: Grounding with Google Maps 서비스가 Google Maps에서 관련 정보(예: 장소, 리뷰, 사진, 주소, 영업 시간)를 쿼리해요.
- 그라운딩된 생성: 검색된 Maps 데이터가 Gemini 모델의 응답을 구성하는 데 사용되어 사실적 정확성과 관련성을 보장해요.
- 응답: 모델이 Google Maps 소스에 대한 인용을 포함하는 텍스트 응답을 반환해요.
Grounding with Google Maps를 사용해야 하는 이유와 시기
Grounding with Google Maps는 정확하고 최신이며 위치 특정적인 정보가 필요한 애플리케이션에 이상적이에요. 전 세계 2억 5천만 개 이상의 장소를 보유한 Google Maps의 광범위한 데이터베이스로 뒷받침되는 관련성 있고 개인화된 콘텐츠를 제공해 사용자 경험을 향상시켜요.
애플리케이션에서 다음이 필요할 때 Grounding with Google Maps를 사용해야 해요.
- 지리적으로 특정한 질문에 완전하고 정확한 응답 제공
- 대화형 여행 플래너와 로컬 가이드 구축
- 위치와 레스토랑·상점 같은 사용자 선호도에 기반한 관심 지점 추천
- 소셜, 소매, 음식 배달 서비스를 위한 위치 인식 경험 만들기
Grounding with Google Maps는 "내 근처 최고의 커피숍" 찾기나 길찾기처럼 근접성과 현재 사실적 데이터가 중요한 사용 사례에서 탁월해요.
API 메서드 및 매개변수
Grounding with Google Maps는 generateContent 메서드 내 도구로 Gemini API를 통해 노출돼요. 요청의 tools 매개변수에 googleMaps 객체를 포함해 Grounding with Google Maps를 활성화하고 구성해요.
{
"contents": [{
"parts": [
{"text": "Restaurants near Times Square."}
]
}],
"tools": { "googleMaps": {} }
}
또한 도구는 컨텍스트 위치를 toolConfig로 전달하는 것을 지원해요.
{
"contents": [{
"parts": [
{"text": "Restaurants near here."}
]
}],
"tools": { "googleMaps": {} },
"toolConfig": {
"retrievalConfig": {
"latLng": {
"latitude": 40.758896,
"longitude": -73.985130
}
}
}
}
그라운딩 응답 이해
응답이 Google Maps 데이터로 성공적으로 그라운딩되면 응답에 groundingMetadata 필드가 포함돼요. 이 구조화된 데이터는 주장을 검증하고 애플리케이션에 풍부한 인용 경험을 구축하며 서비스 사용 요구사항을 충족하는 데 필수적이에요.
{
"candidates": [
{
"content": {
"parts": [
{
"text": "CanteenM is an American restaurant with..."
}
],
"role": "model"
},
"groundingMetadata": {
"groundingChunks": [
{
"maps": {
"uri": "https://maps.google.com/?cid=13100894621228039586",
"title": "Heaven on 7th Marketplace",
"placeId": "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
},
// repeated ...
}
],
"groundingSupports": [
{
"segment": {
"startIndex": 0,
"endIndex": 79,
"text": "CanteenM is an American restaurant with a 4.6-star rating and is open 24 hours."
},
"groundingChunkIndices": [0]
},
// repeated ...
],
"webSearchQueries": [
"restaurants near me"
]
}
}
]
}
Gemini API는 groundingMetadata와 함께 다음 정보를 반환해요.
groundingChunks:maps소스(uri,placeId,title)를 포함하는 객체 배열.groundingSupports: 모델 응답 텍스트를groundingChunks의 소스에 연결하는 청크 배열. 각 청크는 텍스트 범위(startIndex와endIndex로 정의)를 하나 이상의groundingChunkIndices에 연결해요. 이는 인라인 인용을 구축하는 핵심이에요.
텍스트에서 인라인 인용을 렌더링하는 방법을 보여주는 코드 스니펫은 Grounding with Google Search 문서의 예시를 참조하세요.
사용 사례
Grounding with Google Maps는 다양한 위치 인식 사용 사례를 지원해요. 다음 예시는 다양한 프롬프트와 매개변수가 Grounding with Google Maps를 활용하는 방법을 보여줘요. Google Maps 그라운딩 결과의 정보는 실제 상황과 다를 수 있어요.
특정 장소 질문 처리
특정 장소에 대한 상세 질문을 해 Google 사용자 리뷰와 기타 Maps 데이터에 기반한 답변을 받으세요.
from google import genai
from google.genai import types
client = genai.Client()
prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?"
response = client.models.generate_content(
model='gemini-3.8-flash',
contents=prompt,
config=types.GenerateContentConfig(
# Turn on the Maps tool
tools=[types.Tool(google_maps=types.GoogleMaps())],
# Provide the relevant location context (this is in Los Angeles)
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
lat_lng=types.LatLng(
latitude=34.050481, longitude=-118.248526))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if chunks := grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
async function run() {
const prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?";
const response = await ai.models.generateContent({
model: 'gemini-3.8-flash',
contents: prompt,
config: {
// Turn on the Maps tool
tools: [{googleMaps: {}}],
// Provide the relevant location context (this is in Los Angeles)
toolConfig: {
retrievalConfig: {
latLng: {
latitude: 34.050481,
longitude: -118.248526
}
}
}
},
});
console.log("Generated Response:");
console.log(response.text);
const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
if (chunks) {
console.log('-'.repeat(40));
console.log("Sources:");
for (const chunk of chunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
}
run();
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMI...EY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Is there a cafe near the corner of 1st and Main that has outdoor seating?"
}]
}],
"tools": [{"googleMaps": {}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 34.050481, "longitude": -118.248526}
}
}
}'
위치 기반 개인화 제공
사용자 선호도와 특정 지리적 지역에 맞춘 추천을 받으세요.
from google import genai
from google.genai import types
client = genai.Client()
prompt = "Which family-friendly restaurants near here have the best playground reviews?"
response = client.models.generate_content(
model='gemini-3.8-flash',
contents=prompt,
config=types.GenerateContentConfig(
tools=[types.Tool(google_maps=types.GoogleMaps())],
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
# Provide the location as context; this is Austin, TX.
lat_lng=types.LatLng(
latitude=30.2672, longitude=-97.7431))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if chunks := grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
async function run() {
const prompt = "Which family-friendly restaurants near here have the best playground reviews?";
const response = await ai.models.generateContent({
model: 'gemini-3.8-flash',
contents: prompt,
config: {
tools: [{googleMaps: {}}],
toolConfig: {
retrievalConfig: {
// Provide the location as context; this is Austin, TX.
latLng: {
latitude: 30.2672,
longitude: -97.7431
}
}
}
},
});
console.log("Generated Response:");
console.log(response.text);
const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
if (chunks) {
console.log('-'.repeat(40));
console.log("Sources:");
for (const chunk of chunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
}
run();
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMI...EY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Which family-friendly restaurants near here have the best playground reviews?"
}],
}],
"tools": [{"googleMaps": {}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 30.2672, "longitude": -97.7431}
}
}
}'
여행 일정 계획 지원
여행 애플리케이션에 완벽한 다양한 장소의 방향과 정보가 담긴 다일 계획을 생성하세요.
from google import genai
from google.genai import types
client = genai.Client()
prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."
response = client.models.generate_content(
model='gemini-3.8-flash',
contents=prompt,
config=types.GenerateContentConfig(
tools=[types.Tool(google_maps=types.GoogleMaps())],
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
# Provide the location as context, this is in San Francisco.
lat_lng=types.LatLng(
latitude=37.78193, longitude=-122.40476))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in grounding.grounding_chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
async function run() {
const prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.";
const response = await ai.models.generateContent({
model: 'gemini-3.8-flash',
contents: prompt,
config: {
tools: [{googleMaps: {}}],
toolConfig: {
retrievalConfig: {
// Provide the location as context, this is in San Francisco.
latLng: {
latitude: 37.78193,
longitude: -122.40476
}
}
}
},
});
console.log("Generated Response:");
console.log(response.text);
const groundingMetadata = response.candidates[0]?.groundingMetadata;
if (groundingMetadata) {
if (groundingMetadata.groundingChunks) {
console.log('-'.repeat(40));
console.log("Sources:");
for (const chunk of groundingMetadata.groundingChunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
}
}
run();
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMI...EY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."
}]
}],
"tools": [{"googleMaps": {}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 37.78193, "longitude": -122.40476}
}
}
}'
서비스 사용 요구사항
이 섹션은 Grounding with Google Maps의 서비스 사용 요구사항을 설명해요.
Google Maps 소스 사용에 대해 사용자에게 알리기
각 Google Maps 그라운딩 결과와 함께 각 응답을 뒷받침하는 소스가 groundingChunks로 제공돼요. 다음 메타데이터도 반환돼요.
- 소스 uri
- 제목
- ID
Grounding with Google Maps의 결과를 제시할 때 관련 Google Maps 소스를 명시하고 사용자에게 다음을 알려야 해요.
- Google Maps 소스는 소스가 뒷받침하는 생성 콘텐츠 바로 뒤에 따라와야 해요. 이 생성 콘텐츠는 Google Maps 그라운딩 결과라고도 해요.
- Google Maps 소스는 한 번의 사용자 상호작용 내에서 볼 수 있어야 해요.
Google Maps 링크로 Google Maps 소스 표시
groundingChunks와 grounding_chunks.maps.placeAnswerSources.reviewSnippets의 각 소스에 대해 다음 요구사항에 따라 링크 미리보기가 생성되어야 해요.
- 각 소스를 Maps 텍스트 속성 지침에 따라 Google Maps로 속성 표시하세요.
- 응답에서 제공된 소스 제목을 표시하세요.
- 응답의
uri또는googleMapsUri를 사용해 소스에 연결하세요.
이 이미지는 소스와 Google Maps 링크를 표시하기 위한 최소 요구사항을 보여줘요.

소스 보기를 접을 수 있어요.

선택 사항: 다음과 같은 추가 콘텐츠로 링크 미리보기를 강화하세요.
- Google Maps 텍스트 속성 앞에 Google Maps 파비콘 삽입.
- 소스 URL의 사진(
og:image).
Google Maps 데이터 제공업체와 라이선스 조건에 대한 자세한 내용은 Google Maps 및 Google Earth 법적 고지를 참조하세요.
Google Maps 텍스트 속성 지침
텍스트에서 소스를 Google Maps로 속성 표시할 때 다음 지침을 따르세요.
- Google Maps 텍스트를 어떤 방식으로도 수정하지 마세요: Google Maps의 대문자화를 바꾸지 마세요. Google Maps를 여러 줄로 감싸지 마세요. Google Maps를 다른 언어로 현지화하지 마세요. HTML 속성
translate="no"를 사용해 브라우저가 Google Maps를 번역하지 못하게 하세요. - Google Maps 텍스트를 다음 표에 설명된 대로 스타일링하세요.
| 속성 | 스타일 |
|---|---|
| 글꼴 패밀리 | Roboto. 글꼴 로딩은 선택 사항. |
| 대체 글꼴 패밀리 | 제품에서 이미 사용하는 sans serif 본문 글꼴 또는 기본 시스템 글꼴을 호출하는 "Sans-Serif" |
| 글꼴 스타일 | 보통 |
| 글꼴 두께 | 400 |
| 글꼴 색상 | 흰색, 검정(#1F1F1F), 또는 회색(#5E5E5E). 배경 대비 접근성(4.5:1) 유지. |
| 글꼴 크기 | 최소 12sp, 최대 16sp. sp에 대한 자세한 내용은 Material Design 웹사이트의 글꼴 크기 단위를 참조하세요. |
| 간격 | 보통 |
예시 CSS
다음 CSS는 흰색 또는 밝은 배경에서 Google Maps를 적절한 타이포그래피 스타일과 색상으로 렌더링해요.
@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');
.GMP-attribution {
font-family: Roboto, Sans-Serif;
font-style: normal;
font-weight: 400;
font-size: 1rem;
letter-spacing: normal;
white-space: nowrap;
color: #5e5e5e;
}
장소 ID 및 리뷰 ID
Google Maps 데이터에는 장소 ID와 리뷰 ID가 포함돼요. 다음 응답 데이터를 캐시, 저장, 내보낼 수 있어요.
placeIdreviewId
Grounding with Google Maps 약관의 캐싱에 대한 제한은 적용되지 않아요.
금지 활동 및 지역
Grounding with Google Maps는 안전하고 신뢰할 수 있는 플랫폼을 유지하기 위해 특정 콘텐츠와 활동에 대한 추가 제한이 있어요. 약관의 사용 제한에 더해:
- 응급 대응 서비스를 포함한 고위험 활동에 Grounding with Google Maps를 사용하지 않을 거예요.
- 금지 지역에서 Grounding with Google Maps를 제공하는 애플리케이션을 배포하거나 마케팅하지 않을 거예요. 자세한 내용은 Google Maps Platform 금지 지역을 참조하세요. 금지 지역 목록은 때때로 업데이트될 수 있어요.
모범 사례
- 사용자 위치 제공: 가장 관련성 높고 개인화된 응답을 위해 사용자 위치를 알 때는 항상
googleMapsGrounding구성에user_location(위도·경도)을 포함하세요. - 최종 사용자에게 알리기: 특히 도구가 활성화된 경우 Google Maps 데이터가 쿼리 응답에 사용되고 있음을 최종 사용자에게 명확히 알리세요.
- 지연 시간 모니터링: 대화형 애플리케이션의 경우 그라운딩된 응답의 P95 지연 시간이 원활한 사용자 경험을 유지하도록 허용 가능한 임계값 내에 있는지 확인하세요.
- 필요 없을 때 끄기: Grounding with Google Maps는 기본적으로 꺼져 있어요. 쿼리에 명확한 지리적 컨텍스트가 있을 때만 활성화하세요(
"tools": [{"googleMaps": {}}]), 성능과 비용을 최적화하기 위해.
제한 사항
- 지리적 범위: Grounding with Google Maps는 전 세계에서 사용 가능해요.
- 모델 지원: 지원 모델 섹션을 참조하세요.
- 멀티모달 입력/출력: Grounding with Google Maps는 현재 텍스트를 넘어서는 멀티모달 입력이나 출력을 지원하지 않아요.
- 기본 상태: Grounding with Google Maps 도구는 기본적으로 꺼져 있어요. API 요청에서 명시적으로 활성화해야 해요.
가격 및 요금 한도
Grounding with Google Maps 가격은 쿼리 기준이에요. 현재 요금은 그라운딩된 프롬프트 1,000개당 $25예요. 무료 계층에도 하루 최대 500개 요청이 제공돼요. 프롬프트가 성공적으로 Google Maps 그라운딩 결과를 하나 이상 반환할 때만 요청이 할당량에 포함돼요. 단일 요청에서 Google Maps로 여러 쿼리를 보내면 요금 한도 측면에서 한 번의 요청으로 계산돼요.
자세한 가격 정보는 Gemini API 가격 페이지를 참조하세요.
지원 모델
다음 모델이 Grounding with Google Maps를 지원해요.
| 모델 | Grounding with Google Maps |
|---|---|
| Gemini 3.8 Flash | ✔️ |
| Gemini 3.7 Flash | ✔️ |
| Gemini 3.6 Flash | ✔️ |
| Gemini 3.5 Flash-Lite | ✔️ |
| Gemini 3.5 Flash | ✔️ |
| Gemini 3.1 Pro Preview | ✔️ |
| Gemini 3.1 Flash-Lite | ✔️ |
| Gemini 3 Flash Preview | ✔️ |
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
지원 도구 조합
Grounding with Google Search(Gemini 3.5 Flash 이상 모델에서 지원) 같은 다른 내장 도구와 함께 Grounding with Google Maps를 사용해 더 복잡한 사용 사례를 구현할 수 있어요. Gemini 3 모델은 이러한 내장 도구를 커스텀 도구(함수 호출)와 결합하는 것도 지원해요. 도구 조합 페이지에서 자세히 알아보세요.
다음 단계
- Gemini API Cookbook의 Grounding with Google Search를 사용해 보세요.
- 다른 사용 가능한 도구에 대해 알아보세요.
- 책임 있는 AI 모범 사례와 Gemini API 안전 필터에 대한 자세한 내용은 안전 설정 가이드를 참조하세요.