Google 지도를 사용한 그라운딩

Google 지도 기반 그라운딩은 Gemini의 생성 기능을 Google 지도의 풍부하고 사실적이며 최신 데이터와 연결합니다. 이 기능을 사용하면 개발자가 위치 인식 기능을 애플리케이션에 손쉽게 통합할 수 있습니다. 사용자 쿼리에 지도 데이터와 관련된 컨텍스트가 있는 경우 Gemini 모델은 Google 지도를 활용하여 사용자가 지정한 위치 또는 대략적인 위치와 관련된 사실적으로 정확하고 최신 답변을 제공합니다.

  • 정확한 위치 인식 응답: 지리적으로 구체적인 쿼리에 Google 지도의 광범위하고 최신 데이터를 활용합니다.
  • 향상된 맞춤설정: 사용자 제공 위치를 기반으로 추천 및 정보를 맞춤설정합니다.
  • 컨텍스트 정보 및 위젯: 생성된 콘텐츠와 함께 대화형 Google 지도 위젯을 렌더링하는 컨텍스트 토큰입니다.

시작하기

이 예에서는 Google 지도 기반 그라운딩을 애플리케이션에 통합하여 사용자 쿼리에 정확한 위치 인식 응답을 제공하는 방법을 보여줍니다. 프롬프트는 선택적 사용자 위치와 함께 지역 추천을 요청하여 Gemini 모델이 Google 지도 데이터를 사용할 수 있도록 합니다.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What are the best Italian restaurants within a 15-minute walk from here?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

# Print the model's text response and annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What are the best Italian restaurants within a 15-minute walk from here?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  // Print the model's text response and annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What are the best Italian restaurants within a 15-minute walk from here?",
    "tools": [{
      "type": "google_maps",
      "latitude": 34.050481,
      "longitude": -118.248526
    }]
  }'

Google 지도 기반 그라운딩 작동 방식

Google 지도 기반 그라운딩은 지도 API를 그라운딩 소스로 사용하여 Gemini API를 Google Geo 생태계와 통합합니다. 사용자 쿼리에 지리적 컨텍스트가 포함되어 있으면 Gemini 모델이 Google 지도 기반 그라운딩 도구를 호출할 수 있습니다. 그러면 모델이 제공된 위치와 관련된 Google 지도 데이터를 기반으로 응답을 생성할 수 있습니다.

이 프로세스에는 일반적으로 다음이 포함됩니다.

  1. 사용자 쿼리: 사용자가 애플리케이션에 쿼리를 제출합니다. 여기에는 지리적 컨텍스트 (예: '내 주변 카페', '샌프란시스코 박물관')가 포함될 수 있습니다.
  2. 도구 호출: Gemini 모델은 지리적 인텐트를 인식하고 Google 지도 기반 그라운딩 도구를 호출합니다. 이 도구에는 선택적으로 사용자의 latitude 및 longitude가 제공될 수 있습니다. 이 도구는 텍스트 검색 도구이며 지도에서 검색하는 것과 유사하게 작동합니다. 즉, 지역 쿼리('내 주변')는 좌표를 사용하지만 특정 또는 비지역 쿼리는 명시적 위치의 영향을 받지 않을 가능성이 높습니다.
  3. 데이터 검색: Google 지도 기반 그라운딩 서비스는 Google 지도에 관련 정보 (예: 장소, 리뷰, 사진, 주소, 영업시간)를 쿼리합니다.
  4. 그라운딩 생성: 검색된 지도 데이터는 Gemini 모델의 응답에 정보를 제공하여 사실적 정확성과 관련성을 보장하는 데 사용됩니다.
  5. 응답 및 주석: 모델은 Google 지도 소스에 연결되는 인라인 주석이 포함된 텍스트 응답을 반환하므로 개발자는 인용을 표시하고 선택적으로 컨텍스트 Google 지도 위젯을 렌더링할 수 있습니다.

Google 지도 기반 그라운딩을 사용해야 하는 이유와 시기

Google 지도 기반 그라운딩은 정확하고 최신이며 위치별 정보가 필요한 애플리케이션에 적합합니다. 전 세계 2억 5천만 개 이상의 장소로 구성된 Google 지도의 광범위한 데이터베이스를 기반으로 관련성 있고 맞춤설정된 콘텐츠를 제공하여 사용자 환경을 개선합니다.

애플리케이션에서 다음 작업을 수행해야 하는 경우 Google 지도 기반 그라운딩을 사용해야 합니다.

  • 지리적 질문에 완전하고 정확한 답변을 제공합니다.
  • 대화형 여행 플래너 및 지역 가이드를 빌드합니다.
  • 레스토랑이나 상점과 같은 위치 및 사용자 선호도를 기반으로 관심 장소를 추천합니다.
  • 소셜, 소매 또는 음식 배달 서비스를 위한 위치 인식 환경을 만듭니다.

Google 지도 기반 그라운딩은 '내 주변 최고의 카페 찾기' 또는 길찾기와 같이 근접성과 현재 사실 데이터가 중요한 사용 사례에서 뛰어납니다.

사용 사례

Google 지도 기반 그라운딩은 다양한 위치 인식 사용 사례를 지원합니다.

장소별 질문 처리

특정 장소에 관해 자세한 질문을 하여 Google 사용자 리뷰 및 기타 지도 데이터를 기반으로 답변을 받습니다.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

위치 기반 맞춤설정 제공

사용자의 선호도와 특정 지리적 영역에 맞게 맞춤설정된 추천을 받습니다.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Which family-friendly restaurants near here have the best playground reviews?",
    tools=[{
        "type": "google_maps",
        "latitude": 30.2672,
        "longitude": -97.7431
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Which family-friendly restaurants near here have the best playground reviews?",
    tools: [{
      type: "google_maps",
      latitude: 30.2672,
      longitude: -97.7431
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

일정 계획 지원

여행 애플리케이션에 적합한 다양한 위치에 관한 길찾기 및 정보가 포함된 다일 계획을 생성합니다.

Python

from google import genai

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."

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476,
        "enable_widget": True
    }]
)
# ... code to process response and widget token

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: '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: [{
      type: "google_maps",
      latitude: 37.78193,
      longitude: -122.40476,
      enableWidget: true
    }],
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "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": [{
      "type": "google_maps",
      "latitude": 37.78193,
      "longitude": -122.40476,
      "enable_widget": true
    }]
  }'

서비스 사용 요구사항

이 섹션에서는 Google 지도 기반 그라운딩에 대한 서비스 사용 요구사항을 설명합니다.

사용자에게 Google 지도 소스 사용 알림

각 Google 지도 그라운딩 결과와 함께 각 응답을 지원하는 model_output 단계의 콘텐츠 블록에 소스 주석이 수신됩니다. 다음 메타데이터가 반환됩니다.

  • 소스 URL
  • 이름

Google 지도 기반 그라운딩 결과를 표시할 때는 연결된 Google 지도 소스를 명시하고 사용자에게 다음 사항을 알려야 합니다.

  • Google 지도 소스는 해당 소스를 뒷받침하는 생성된 콘텐츠 직후에 따라와야 합니다. 이렇게 생성된 콘텐츠를 Google 지도 그라운딩 결과라고도 합니다.
  • Google 지도 소스는 단일 사용자 상호작용 내에서 확인 가능해야 합니다.

Google 지도 소스를 Google 지도 링크와 함께 표시

각 소스 주석에 대해 다음 요구사항에 따라 링크 미리보기를 생성해야 합니다.

  • 각 소스는 Google 지도에서 제공한 것임을 명시하고 Google 지도의 텍스트 저작자 표시 지침을 따라야 합니다.
  • 응답에 포함된 소스 이름을 표시해야 합니다.
  • 주석에 제공된 url을 사용하여 소스에 연결해야 합니다.

Google 지도 텍스트 저작자 표시 가이드라인

Google 지도의 텍스트 저작자 소스를 표시할 때는 다음 가이드라인을 따라야 합니다.

  • Google 지도 텍스트를 어떤 방식으로도 수정하지 마세요.
    • Google 지도의 대소문자를 변경하지 마세요.
    • Google 지도를 여러 줄로 나누어 표시하지 마세요.
    • Google 지도를 다른 언어로 현지화하지 마세요.
    • 브라우저가 Google 지도를 번역하지 못하도록 HTML 속성 translate="no"를 사용해야 합니다.

일부 Google 지도 데이터 제공업체 및 해당 라이선스 조건에 대한 자세한 내용은 Google 지도 및 Google 어스 법적 고지를 참조하세요.

권장사항

  • 사용자 위치 제공: 가장 관련성 있고 맞춤설정된 응답을 위해서는 사용자 위치를 알고 있는 경우 항상 google_maps 도구 구성에 latitude 및 longitude를 포함하세요.
  • Google 지도 컨텍스트 위젯 렌더링: 이 컨텍스트 위젯은 Gemini API 응답에 포함된 컨텍스트 토큰인 google_maps_widget_context_token을 사용하여 렌더링됩니다. 이 토큰을 활용하면 Google 지도의 시각적 콘텐츠를 렌더링할 수 있습니다.
  • 최종 사용자에게 알림: 특히 도구가 사용 설정된 경우 Google 지도 데이터가 쿼리에 답변하는 데 사용되고 있음을 최종 사용자에게 명확하게 알립니다.
  • 필요하지 않은 경우 전환: Google 지도 기반 그라운딩은 기본적으로 사용 중지되어 있습니다. 성능과 비용을 최적화하려면 쿼리에 명확한 지리적 컨텍스트가 있는 경우에만 사용 설정 ("tools": [{"type": "google_maps"}])하세요.

제한사항

  • Google 지도 기반 그라운딩은 현재 영어 프롬프트와 응답만 지원합니다.
  • 일부 지역에서는 이 도구를 사용하지 못할 수 있습니다.
  • 결과는 위치 정확도 및 사용 가능한 지도 데이터에 따라 다를 수 있습니다.
  • 지리적 범위: Google 지도 기반 그라운딩은 전 세계에서 사용할 수 있습니다.
  • 기본 상태: Google 지도 기반 그라운딩 도구는 기본적으로 사용 중지되어 있습니다. API 요청에서 명시적으로 사용 설정해야 합니다.

가격 책정 및 비율 제한

Google 지도 기반 그라운딩 가격은 쿼리를 기반으로 합니다. 현재 요금은 그라운딩된 프롬프트 1,000개당$25 입니다. 무료 등급에서는 일일 최대 500개의 요청도 사용할 수 있습니다. 프롬프트가 Google 지도 그라운딩 결과 (즉, Google 지도 소스를 하나 이상 포함하는 결과)를 하나 이상 성공적으로 반환하는 경우에만 요청이 할당량에 포함됩니다. 단일 요청에서 Google 지도에 여러 쿼리가 전송되면 비율 제한에 대해 하나의 요청으로 계산됩니다.

자세한 가격 책정 정보는 Gemini API 가격 책정 페이지를 참조하세요.

지원되는 모델

다음 모델은 Google 지도 기반 그라운딩을 지원합니다.

모델 Google 지도 기반 그라운딩
Gemini 3.1 Pro 프리뷰 ✔️
Gemini 3.1 Flash-Lite ✔️
Gemini 3.1 Flash-Lite 프리뷰 ✔️
Gemini 3 Flash 프리뷰 ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

지원되는 도구 조합

Gemini 3 모델은 Google 지도 기반 그라운딩과 같은 기본 제공 도구를 맞춤 도구(함수 호출)와 결합하는 것을 지원합니다. 도구 조합 페이지에서 자세히 알아보세요.

다음 단계

  • 사용 가능한 다른 도구에 대해 알아봅니다.
  • 책임감 있는 AI 권장사항 및 Gemini API의 안전 필터에 대해 자세히 알아보려면 안전 설정 가이드를 참조하세요.