Google Maps 접지

Google Maps 접지 (Grounding with Google Maps)

Google Maps 접지는 Gemini의 생성 능력을 Google Maps의 풍부하고 사실적이며 최신 데이터와 연결해요. 이를 통해 개발자가 애플리케이션에 위치 인식 기능을 쉽게 추가할 수 있어요. 사용자 쿼리에 Maps 데이터와 관련된 컨텍스트가 있으면 Gemini 모델이 Google Maps를 활용해 사용자의 위치나 일반 지역에 관련된 사실적으로 정확하고 신선한 답변을 제공해요.

출처: 원문

본문

Google Maps 접지는 Gemini의 생성 능력과 Google Maps의 풍부하고 사실적이며 최신 데이터를 연결해요. 이 기능을 통해 개발자가 애플리케이션에 위치 인식 기능을 쉽게 통합할 수 있어요. 사용자 쿼리에 Maps 데이터와 관련된 컨텍스트가 있으면 Gemini 모델이 Google Maps를 활용해 사용자의 지정된 위치나 일반 지역에 관련된 사실적으로 정확하고 신선한 답변을 제공해요.

• 정확하고 위치 인식적인 응답: 지리적으로 특정한 쿼리에 대해 Google Maps의 광범위하고 현재의 데이터 활용.
• 향상된 개인화: 사용자가 제공한 위치에 기반해 추천과 정보를 맞춤화.

시작하기

이 예시는 애플리케이션에 Google Maps 접지를 통합해 사용자 쿼리에 정확하고 위치 인식적인 응답을 제공하는 방법을 보여줘요. 프롬프트는 선택적 사용자 위치와 함께 로컬 추천을 요청해, Gemini 모델이 Google Maps 데이터를 사용할 수 있게 해요.

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    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

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    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();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.PlaceCitation;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "What are the best Italian restaurants within a 15-minute walk from here?"))
        .tools(
            Arrays.asList(
                GoogleMaps.builder().latitude(34.050481).longitude(-118.248526).build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

// Print the model's text response and annotations
if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            System.out.println(textContent.text().orElse(""));
            if (textContent.annotations().isPresent()
                && !textContent.annotations().get().isEmpty()) {
              System.out.println("\nSources:");
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof PlaceCitation) {
                  PlaceCitation citation = (PlaceCitation) annotation;
                  System.out.printf(
                      "  - %s: %s%n", citation.name().orElse(""), citation.url().orElse(""));
                }
              }
            }
          }
        }
      }
    }
  }
}

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("What are the best Italian restaurants within a 15-minute walk from here?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleMaps{
                        Latitude:  genai.Ptr(34.050481),
                        Longitude: genai.Ptr(-118.248526),
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Print the model's text response and annotations
    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    fmt.Println(content.TextContent.Text)
                    if len(content.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range content.TextContent.Annotations {
                            if annotation.PlaceCitation != nil {
                                c := annotation.PlaceCitation
                                name := ""
                                if c.Name != nil {
                                    name = *c.Name
                                }
                                url := ""
                                if c.URL != nil {
                                    url = *c.URL
                                }
                                fmt.Printf("  - %s: %s\n", name, url)
                            }
                        }
                    }
                }
            }
        }
    }
}

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "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 Maps 접지의 동작 방식

Google Maps 접지는 Maps API를 접지 소스로 사용해 Gemini API를 Google Geo 생태계에 통합해요. 사용자 쿼리에 지리적 컨텍스트가 포함되면 Gemini 모델이 Google Maps 접지 도구를 호출할 수 있어요. 그다음 모델은 제공된 위치와 관련된 Google Maps 데이터에 접지된 응답을 생성할 수 있어요.

이 프로세스는 보통 다음을 포함해요:

1. 사용자 쿼리: 사용자가 애플리케이션에 쿼리를 제출하며, 지리적 컨텍스트를 포함할 수 있어요 (예: "내 근처 커피숍", "샌프란시스코 박물관").
2. 도구 호출: Gemini 모델이 지리적 의도를 인식해 Google Maps 접지 도구를 호출해요. 이 도구는 선택적으로 사용자의 latitude와 longitude를 제공받을 수 있어요. 이 도구는 텍스트 검색 도구로, Maps에서 검색하는 것과 유사하게 동작해요. "near me" 같은 로컬 쿼리는 좌표를 사용하지만, 특정하거나 로컬이 아닌 쿼리는 명시적 위치에 영향을 받을 가능성이 낮아요.
3. 데이터 검색: Google Maps 접지 서비스가 Google Maps에서 관련 정보(장소, 리뷰, 사진, 주소, 영업시간 등)를 쿼리해요.
4. 접지 생성: 검색된 Maps 데이터가 Gemini 모델의 응답을 알려 사실적 정확성과 관련성을 보장해요.
5. 응답 및 주석: 모델이 Google Maps 소스에 연결되는 인라인 주석이 있는 텍스트 응답을 반환해, 개발자가 인용을 표시할 수 있게 해요.

Google Maps 접지를 언제, 왜 사용해야 하나요

Google Maps 접지는 정확하고 최신이며 위치 특정적인 정보가 필요한 애플리케이션에 적합해요. 전 세계 2억 5천만 개 이상의 장소에 대한 Google Maps의 방대한 데이터베이스로 뒷받침되는 관련성 있고 개인화된 콘텐츠를 제공해 사용자 경험을 향상시켜요.

애플리케이션이 다음을 필요로 할 때 Google Maps 접지를 사용해야 해요:

• 지리 특정 질문에 완전하고 정확한 응답 제공.
• 대화형 여행 플래너와 로컬 가이드 구축.
• 위치와 사용자 선호도(레스토랑, 상점 등)에 기반한 관심 지점 추천.
• 소셜, 리테일, 음식 배달 서비스를 위한 위치 인식 경험 생성.

Google Maps 접지는 근접성과 현재 사실적 데이터가 중요한 사용 사례(예: "내 근처 최고의 커피숍" 찾기, 길찾기)에서 뛰어나요.

사용 사례

Google Maps 접지는 다양한 위치 인식 사용 사례를 지원해요.

장소 특정 질문 처리

특정 장소에 대한 상세 질문을 해 Google 사용자 리뷰와 기타 Maps 데이터에 기반한 답변을 받아보세요.

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    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

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    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();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.PlaceCitation;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Is there a cafe near the corner of 1st and Main that has outdoor seating?"))
        .tools(
            Arrays.asList(
                GoogleMaps.builder().latitude(34.050481).longitude(-118.248526).build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            System.out.println(textContent.text().orElse(""));
            if (textContent.annotations().isPresent()
                && !textContent.annotations().get().isEmpty()) {
              System.out.println("\nSources:");
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof PlaceCitation) {
                  PlaceCitation citation = (PlaceCitation) annotation;
                  System.out.printf(
                      "  - %s: %s%n", citation.name().orElse(""), citation.url().orElse(""));
                }
              }
            }
          }
        }
      }
    }
  }
}

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Is there a cafe near the corner of 1st and Main that has outdoor seating?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleMaps{
                        Latitude:  genai.Ptr(34.050481),
                        Longitude: genai.Ptr(-118.248526),
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    fmt.Println(content.TextContent.Text)
                    if len(content.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range content.TextContent.Annotations {
                            if annotation.PlaceCitation != nil {
                                c := annotation.PlaceCitation
                                name := ""
                                if c.Name != nil {
                                    name = *c.Name
                                }
                                url := ""
                                if c.URL != nil {
                                    url = *c.URL
                                }
                                fmt.Printf("  - %s: %s\n", name, url)
                            }
                        }
                    }
                }
            }
        }
    }
}

위치 기반 개인화 제공

사용자의 선호도와 특정 지리적 영역에 맞춘 추천을 받아보세요.

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    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

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    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();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.PlaceCitation;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Which family-friendly restaurants near here have the best playground reviews?"))
        .tools(
            Arrays.asList(GoogleMaps.builder().latitude(30.2672).longitude(-97.7431).build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            System.out.println(textContent.text().orElse(""));
            if (textContent.annotations().isPresent()
                && !textContent.annotations().get().isEmpty()) {
              System.out.println("\nSources:");
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof PlaceCitation) {
                  PlaceCitation citation = (PlaceCitation) annotation;
                  System.out.printf(
                      "  - %s: %s%n", citation.name().orElse(""), citation.url().orElse(""));
                }
              }
            }
          }
        }
      }
    }
  }
}

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Which family-friendly restaurants near here have the best playground reviews?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleMaps{
                        Latitude:  genai.Ptr(30.2672),
                        Longitude: genai.Ptr(-97.7431),
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    fmt.Println(content.TextContent.Text)
                    if len(content.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range content.TextContent.Annotations {
                            if annotation.PlaceCitation != nil {
                                c := annotation.PlaceCitation
                                name := ""
                                if c.Name != nil {
                                    name = *c.Name
                                }
                                url := ""
                                if c.URL != nil {
                                    url = *c.URL
                                }
                                fmt.Printf("  - %s: %s\n", name, url)
                            }
                        }
                    }
                }
            }
        }
    }
}

여행 일정 계획 지원

여행 애플리케이션에 완벽한 다양한 위치에 대한 방향과 정보를 가진 다중 일일 계획을 생성하세요.

Python

# This will only work for SDK newer than 2.0.0
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.8-flash",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476
    }]
)
# ... code to process response

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    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
    }]
  });
}

main();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

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

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of(prompt))
        .tools(
            Arrays.asList(GoogleMaps.builder().latitude(37.78193).longitude(-122.40476).build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

// ... code to process response
System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

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

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput(prompt),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleMaps{
                        Latitude:  genai.Ptr(37.78193),
                        Longitude: genai.Ptr(-122.40476),
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    // ... code to process response
    fmt.Println(resp.Interaction.GetOutputText())
}

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "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
    }]
  }'

서비스 사용 요구사항

이 섹션은 Google Maps 접지의 서비스 사용 요구사항을 설명해요.

Google Maps 소스 사용을 사용자에게 알리기

각 Google Maps 접지 결과와 함께, 각 응답을 지원하는 model_output 단계의 콘텐츠 블록에 소스 주석이 제공돼요. 다음 메타데이터가 반환돼요:

• 소스 URL
• 이름

Google Maps 접지 결과를 제시할 때는 관련 Google Maps 소스를 지정하고 사용자에게 다음을 알려야 해요:

• Google Maps 소스는 소스가 지원하는 생성 콘텐츠 바로 뒤에 와야 해요. 이 생성 콘텐츠는 Google Maps 접지 결과라고도 해요.
• Google Maps 소스는 한 번의 사용자 상호작용 안에서 볼 수 있어야 해요.

Google Maps 링크로 Google Maps 소스 표시

각 소스 주석에 대해 다음 요구사항을 따르는 링크 프리뷰를 생성해야 해요:

• 각 소스를 Google Maps 텍스트 출처 표시 가이드라인에 따라 Google Maps에 귀속시키세요.
• 응답에서 제공된 소스 이름을 표시하세요.
• 주석의 url을 사용해 소스에 연결하세요.

Google Maps 텍스트 출처 표시 가이드라인

텍스트에서 소스를 Google Maps에 귀속시킬 때는 다음 가이드라인을 따르세요:

• Google Maps 텍스트를 어떤 방식으로도 수정하지 마세요:
  • Google Maps의 대소문자를 바꾸지 마세요.
  • Google Maps를 여러 줄로 감싸지 마세요.
  • Google Maps를 다른 언어로 현지화하지 마세요.
  • HTML 속성 translate="no"를 사용해 브라우저가 Google Maps를 번역하지 못하게 하세요.

일부 Google Maps 데이터 제공자와 라이선스 조건에 대한 자세한 내용은 Google Maps 및 Google Earth 법적 고지를 참고하세요.

모범 사례

• 사용자 위치 제공: 가장 관련성 있고 개인화된 응답을 위해, 사용자의 위치가 알려져 있으면 항상 google_maps 도구 구성에 latitude와 longitude를 포함하세요.
• 최종 사용자에게 알리기: 특히 도구가 활성화되어 있을 때 Google Maps 데이터로 쿼리에 답하고 있음을 최종 사용자에게 명확히 알리세요.
• 필요 없을 때 끄기: Google Maps 접지는 기본적으로 꺼져 있어요. 쿼리에 명확한 지리적 컨텍스트가 있을 때만 ("tools": [{"type": "google_maps"}]) 활성화해 성능과 비용을 최적화하세요.

제한 사항

• Google Maps 접지는 현재 영어 프롬프트와 응답만 지원해요.
• 도구가 모든 지역에서 사용 가능하지 않을 수 있어요.
• 결과는 위치 정확도와 사용 가능한 Maps 데이터에 따라 달라질 수 있어요.
• 지리적 범위: Google Maps 접지는 전 세계적으로 사용 가능해요.
• 기본 상태: Google Maps 접지 도구는 기본적으로 꺼져 있어요. API 요청에서 명시적으로 활성화해야 해요.

가격과 속도 제한

Google Maps 접지 가격은 모델 세대에 따라 달라져요:

• Gemini 3 모델: 모델이 실행하기로 결정한 각 검색 쿼리에 대해 프로젝트가 청구돼요. 단일 검색 프롬프트(모델에 대한 API 요청)가 필요한 정보를 찾기 위해 여러 검색 쿼리를 실행할 수 있어요. 각 검색 쿼리는 도구의 과금 가능한 사용으로 계산돼요.
• Gemini 2.5 및 이전 모델: 검색 프롬프트마다 프로젝트가 청구돼요. 프롬프트가 Google Maps 접지 결과를 하나 이상 성공적으로 반환하는 경우에만 요청이 청구되며, 모델이 그 결과를 얻기 위해 내부적으로 수행한 개별 검색 쿼리 수와는 무관해요.

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

지원 모델

다음 모델이 Google Maps 접지를 지원해요:

모델	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	✔️

지원 도구 조합

Google Maps 접지를 Google 검색 접지(Gemini 3.5 Flash 이상 모델에서 지원) 같은 다른 내장 도구와 함께 사용해 더 복잡한 사용 사례를 지원할 수 있어요. Gemini 3 모델은 이 내장 도구들을 커스텀 도구(함수 호출)와 결합하는 것도 지원해요. 자세한 내용은 도구 결합 페이지를 참고하세요.

다음으로

• 다른 사용 가능한 도구 알아보기.
• 책임 있는 AI 모범 사례와 Gemini API 안전 필터에 대해 안전 설정 가이드 참고.

더 알아보기 (Learn more)

• 도구
• 도구 결합
• 안전 설정