Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Maps Grounding Lite

Google Maps Platform Grounding Lite는 모델 컨텍스트 프로토콜(MCP)을 지원하는 서비스로, Google 지도의 신뢰할 수 있는 지리공간 데이터를 사용하여 AI 애플리케이션을 쉽게 그라운딩할 수 있습니다. MCP 서버는 LLM이 장소, 날씨, 경로 기능을 이용할 수 있도록 하는 도구를 제공합니다. MCP 서버를 지원하는 도구에서 Maps Grounding Lite를 사용 설정하여 사용해 볼 수 있습니다.

도구

Maps Grounding Lite는 LLM이 다음 Google 지도 기능에 액세스할 수 있도록 하는 도구를 제공합니다.

장소 검색: 장소에 관한 정보를 요청하고 AI 생성 장소 데이터 요약과 요약에 포함된 각 장소의 장소 ID, 위도 및 경도 좌표, Google 지도 링크를 가져옵니다. 반환된 장소 ID와 위도 및 경도 좌표를 다른 Google Maps Platform API와 함께 사용하여 지도에 장소를 표시할 수 있습니다.
**날씨 조회**: 날씨에 관한 정보를 요청하고 현재 상태, 시간별 예보, 일별 예보를 반환합니다.
경로 계산: 두 위치 간의 운전 또는 도보 경로에 관한 정보를 요청하고 경로 거리 및 소요 시간 정보를 반환합니다.

**참고:** Maps Grounding Lite는 단계별 경로 안내, 길찾기, 실시간 교통정보, 내비게이션 정보를 제공하지 않습니다.

Maps Grounding Lite MCP 서버를 사용 설정하면 LLM이 서버에서 노출하는 새 도구를 호출하여 위에 나열된 데이터 유형에 관한 추가 그라운딩 정보를 반환할 수 있습니다. LLM은 이 추가 정보를 컨텍스트에 사용할 수 있지만 LLM이 궁극적으로 생성하는 응답에는 MCP 서버에서 반환된 정확한 정보가 포함되지 않을 수 있습니다. 생성된 응답의 정확성을 확인해야 합니다.

Resolution API (실험용)

Maps Grounding Lite는 자유 형식 위치 텍스트와 URL을 구조화된 Google 지도 장소 식별자로 변환할 수 있는 Resolution API를 제공합니다. Resolution API는 두 개의 엔드포인트로 구성됩니다.

이름 변환: Google 지도의 특정 장소 항목으로 위치 이름 또는 주소 일괄 변환합니다. 이는 구조화되지 않은 사용자 쿼리를 안정적인 장소 ID로 그라운딩하는 데 유용합니다.
지도 URL 변환: Google 지도 URL을 특정 장소 항목으로 일괄 변환합니다. 지원되는 형식에는 표준 장소 URL과 단축 URL이 포함됩니다.

이러한 엔드포인트를 사용하여 구조화되지 않은 사용자 쿼리 또는 링크를 안정적인 장소 ID로 그라운딩하여 다른 Google Maps Platform API와 통합할 수 있습니다.

자세한 내용은 지도 도구 Resolution API (실험용) 를 참고하세요.

Maps Grounding Lite 샘플 앱 사용해 보기(새 탭에서 열기)

결제 및 할당량

요금 청구 방식

Google Maps Platform 사용한 만큼만 지불하는 요금 모델을 사용하면 각 요청에 대해 Maps Grounding Lite 사용량이 계산되며 각 요청은 하나의 결제 이벤트를 나타냅니다. 사용량은 각 제품 SKU별로 추적됩니다. 청구서에는 총 요금 외에 각 SKU의 항목이 표시됩니다. 자세한 내용은 보고 개요 를 참고하세요.

가격 책정 세부정보는 기본 가격표 및 인도 가격표 를 참고하세요.

Maps Grounding Lite는 Essentials 및 Pro Subscribe to save 패키지를 통해서도 제공됩니다.

할당량

다음 할당량은 Maps Grounding Lite에서 제공하는 도구 및 API에 적용됩니다.

장소 검색: 프로젝트별 분당 쿼리 300개
날씨 조회: 프로젝트별 분당 쿼리 300개
경로 계산: 프로젝트별 분당 쿼리 300개
이름 변환 (실험용): 프로젝트별 분당 쿼리 600개
지도 URL 변환 (실험용): 프로젝트별 분당 쿼리 600개

정책 및 서비스 약관

Maps Grounding Lite에는 Google Maps Platform 서비스 약관과 이 서비스의 서비스별 약관이 적용됩니다. 이 섹션에서는 호환되는 LLM 및 소스 저작자 표시 요구사항을 비롯한 Maps Grounding Lite의 추가 서비스 사용 요구사항을 설명합니다.

호환되는 LLM 요구사항

Google Maps Platform 서비스 약관을 준수하는 LLM에서만 Maps Grounding Lite를 사용할 수 있습니다.

예를 들어 사용자가 선택한 LLM에서 Google 지도 콘텐츠가 캐시되거나 저장되거나 LLM을 개선하는 데 사용되지 않도록 하는 것은 사용자의 책임입니다. Maps Grounding Lite를 사용하기 전에 Maps Grounding Lite와 함께 사용하려는 모델의 서비스 약관을 검토해야 합니다. 모델 학습 또는 개선을 위해 모델에 입력된 데이터를 사용하는 모델에는 Maps Grounding Lite를 사용해서는 안 됩니다. 서비스별 약관을 포함한 Google Maps Platform 서비스 약관의 Google 지도 콘텐츠에 관한 제한사항을 모델 사용 시 완전히 준수하는지 확인하는 것은 사용자의 책임입니다.

Google 지도 소스의 저작자 표시 요구사항

Maps Grounding Lite의 각 도구 응답에는 소스가 포함됩니다. Maps Grounding Lite에서 제공하는 도구를 사용하는 결과를 표시할 때는 다음 요구사항을 충족하는 방식으로 연결된 Google 지도 소스를 포함해야 합니다.

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

장소 검색 도구의 소스

search_places 도구 places 필드는 summary를 지원하는 소스를 제공합니다. places의 경우 다음 메타데이터가 반환됩니다.

place (리소스 이름)
id
location
googleMapsLinks

각 장소에 대해 다음 요구사항을 충족하는 링크 미리보기를 생성해야 합니다.

각 소스는 Google 지도에서 제공한 것임을 명시하고 Maps Grounding Lite 의 텍스트 저작자 표시 지침을 따라야 합니다.
응답에 제공된 places.googleMapsLinks.placeUrl을 사용하여 소스에 연결해야 합니다.

MCP 서버를 사용하도록 LLM 구성

Maps Grounding Lite를 사용하려면 먼저 Maps Grounding Lite API 서비스가 사용 설정된 Google Cloud 프로젝트와 API 키 또는 OAuth 클라이언트 ID가 필요합니다. 그런 다음 LLM이 MCP 서버에 액세스하도록 구성할 수 있습니다. Grounding Lite MCP 서버는 스트리밍 가능한 HTTP 전송을 사용합니다.

Google Cloud 프로젝트에서 Maps Grounding Lite 서비스 사용 설정

프로젝트에서 API를 사용 설정하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Maps Grounding Lite에 사용할 프로젝트를 선택합니다.
Google Cloud Console에서 프로젝트의 결제를 설정합니다.
Google Cloud Console API 라이브러리에서 Maps Grounding Lite를 사용 설정합니다.

API 키를 사용하여 인증

Google Cloud 프로젝트와 키 모두에서 Maps Grounding Lite API 서비스 를 사용 설정하는 한 Maps Grounding Lite에서 기존 API 키를 사용하거나 새 API 키를 만들 수 있습니다.

API 키를 사용하여 인증하려면 다음 단계를 따르세요.

Google Maps Platform 시작하기 의 단계에 따라 API 키를 만들거나 구성합니다.
X-Goog-Api-Key 헤더를 사용하여 키를 MCP 서버에 전달합니다. LLM의 MCP 도구 구성에서 이를 커스텀 HTTP 헤더로 지정해야 합니다.

OAuth를 사용하여 인증

OAuth 사용자 인증 정보를 만들고 이를 MCP 호스트 또는 MCP 서버 애플리케이션에 전달하여 OAuth를 사용하여 인증할 수 있습니다.

OAuth를 사용하여 인증하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Maps Grounding Lite에 사용할 프로젝트를 선택합니다.
API 및 서비스 메뉴에서 사용자 인증 정보 를 선택합니다.
상단 메뉴에서 사용자 인증 정보 만들기 > OAuth 클라이언트 ID 를 선택합니다.
프로젝트에 구성된 동의 화면이 없는 경우 동의 화면 구성 을 클릭하고 화면에 표시된 안내를 따릅니다.
측정항목 섹션에서 OAuth 클라이언트 만들기 를 클릭합니다.
OAuth 클라이언트 ID 만들기 화면에서 애플리케이션 유형을 선택하고 클라이언트 ID의 이름을 입력합니다.
애플리케이션 유형과 관련된 추가 세부정보를 지정합니다. 예를 들어 웹 애플리케이션을 만드는 경우 브라우저 및 서버 요청에 승인된 URI를 추가합니다.
클라이언트가 생성되면 클라이언트 ID와 보안 비밀을 저장합니다.
Maps Grounding Lite에 액세스하도록 MCP 호스트 또는 MCP 서버 애플리케이션을 구성할 때 OAuth 클라이언트 ID와 보안 비밀을 전달합니다. 다음 범위도 요청해야 합니다. https://www.googleapis.com/auth/maps-platform.mapstools.

자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스하기를 참고하세요.

Maps Grounding Lite MCP 서버에 액세스하도록 LLM 구성

Maps Grounding Lite API 서비스가 사용 설정된 Google Cloud 프로젝트와 API 키 또는 OAuth 클라이언트 ID 및 보안 비밀과 같은 유효한 사용자 인증 정보가 있으면 해당 MCP 구성 문서를 따르고 Maps Grounding Lite MCP 서버 URL인 https://mapstools.googleapis.com/mcp 를 사용하여 LLM이 MCP 서버에 액세스하도록 구성할 수 있습니다.

자세한 내용은 AI 애플리케이션에서 MCP 구성을 참고하세요.

Gemini CLI로 Maps Grounding Lite 구성

이 섹션에서는 Gemini CLI를 사용하여 Maps Grounding Lite MCP 서버를 구성하는 방법을 보여주는 예를 제공합니다. 자세한 내용은 Gemini CLI를 사용하는 MCP 서버를 참고하세요.

Gemini CLI를 설치한 후 add 명령어를 사용하여 Maps Grounding Lite MCP 서버를 구성할 수 있습니다.
```
gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
```
구성이 완료되면 서버가 사용자 설정에 추가되었다는 확인 메시지가 표시됩니다.

서버가 올바르게 작동하는지 확인하려면 /mcp list 명령어를 실행합니다.

> /mcp list

Configured MCP servers:

maps-grounding-lite-mcp - Ready (3 tools)
Tools:
-   compute_routes
-   lookup_weather
-   search_places

CLI를 사용하여 지도 관련 질문을 시작합니다. 예를 들어 'Mountain View의 레스토랑 추천해 줘'를 사용해 보세요. 그러면 사용자를 대신하여 search_places 도구가 호출됩니다.

에이전트 개발 키트 (ADK)로 Grounding Lite 구성

이 섹션에서는 에이전트 개발 키트 (ADK)와 Python, Java 또는 TypeScript를 사용하여 Grounding Lite MCP 서버를 구성하는 방법을 보여주는 예를 제공합니다.

Python

1단계: Google Maps Grounding Lite의 `McpToolset`로 에이전트 정의

agent.py 파일을 수정합니다. Replace YOUR_GOOGLE_MAPS_API_KEY를 실제 API 키로 바꿉니다.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mapstools.googleapis.com/mcp",
                headers={
                    "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream"
                }
            )
        )
    ]
)

2단계: `init.py`가 있는지 확인

`agent.py`와 동일한 디렉터리에 `__init__.py`가 있는지 확인합니다.

from . import agent

3단계: `adk web` 실행 및 상호작용

환경 변수 설정:
터미널에서 Google 지도 API 키를 환경 변수로 설정합니다.
```
export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
        
```
adk web 실행:
다음 명령어를 실행하여 ADK 웹 인터페이스를 시작합니다.
```
adk web
        
```
UI에서 상호작용:
- travel_planner_agent를 선택합니다.
- 다음과 같은 프롬프트를 사용해 보세요.
  - '내일 샌프란시스코에 갈 거야. 날씨가 어때?'
  - 골든 게이트 파크 근처의 커피숍 찾아 줘.
  - 'GooglePlex에서 SFO까지 길찾기해 줘.'

자바

Java에서 McpToolset을 초기화하는 에이전트를 정의합니다. 환경 변수를 사용하지 않는 경우 가져온 실제 API 키 로 YOUR_GOOGLE_MAPS_API_KEY_HERE를 바꿉니다.

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams =
                StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                        .headers(headers)
                        .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText =
                    "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService()
                    .createSession(runner.appName(), userId, null, sessionId)
                    .blockingGet()
                    .sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

TypeScript

TypeScript에서 MCPToolset을 초기화하는 에이전트를 정의합니다.

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error(
        'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.'
    );
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "SseConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            headers: {
                "X-Goog-Api-Key": googleMapsApiKey,
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream"
            }
        })
    ],
});

의견 공유

Maps Grounding Lite에 관한 의견을 공유하려면 다음 양식을 사용하세요.