Haritalar Grounding Lite

Google Haritalar Platformu Grounding Lite, Model Context Protocol (MCP) desteği sunan bir hizmettir. Bu hizmet, yapay zeka uygulamalarınızı Google Haritalar'dan alınan güvenilir coğrafi verilerle kolayca temellendirmenizi sağlar. MCP sunucusu, LLM'lerin yerler, hava durumu ve rotalarla ilgili özelliklere erişmesine ve konum adları ile Google Haritalar URL'lerini yer kimliklerine dönüştürmesine olanak tanıyan araçlar sağlar. Maps Grounding Lite'ı, MCP sunucularını destekleyen herhangi bir araçta etkinleştirerek deneyebilirsiniz.

Araçlar

Maps Grounding Lite, LLM'lerin aşağıdaki Google Haritalar özelliklerine erişmesine olanak tanıyan araçlar sağlar:

• Yerler için arama yapma: Yerler hakkında bilgi isteyin ve yapay zeka tarafından oluşturulan yer verisi özetlerinin yanı sıra özette yer alan her yer için yer kimlikleri, enlem ve boylam koordinatları ve Google Haritalar bağlantıları alın. Döndürülen yer kimliklerini ve enlem ile boylam koordinatlarını diğer Google Maps Platform API'leriyle birlikte kullanarak yerleri haritada gösterebilirsiniz.
• Hava durumunu öğrenme: Hava durumu hakkında bilgi isteyin ve mevcut koşulları, saatlik tahminleri ve günlük tahminleri öğrenin.

• Rotaları hesaplama: İki konum arasındaki sürüş veya yürüyüş rotaları hakkında bilgi isteyin ve rota mesafesi ile süre bilgilerini döndürün.

• Adları çözümleme ve Haritalar URL'lerini çözümleme: Konum adlarını, adresleri ve Google Haritalar URL'lerini yer kimliklerine çözümleyin. Daha fazla bilgi için Resolution API sayfasına bakın.

Maps Grounding Lite MCP sunucusunu etkinleştirmek, LLM'lerin sunucu tarafından sunulan yeni araçları çağırarak yukarıda listelenen veri türleri için ek temellendirme bilgileri döndürmesine olanak tanır. LLM, bu ek bilgileri bağlam için kullanabilse de nihai olarak ürettiği yanıt, MCP sunucusu tarafından döndürülen bilgilerin tamamını içermeyebilir. Oluşturulan yanıtın doğruluğunu kontrol etmeniz gerekir.

Resolution API

Maps Grounding Lite, serbest biçimli konum metinlerini ve URL'leri yapılandırılmış Google Haritalar yer tanımlayıcılarına dönüştürmenize olanak tanıyan Resolution API'yi sunar. Resolution API, Maps Grounding Lite MCP sunucusunda REST yöntemleri ve araçlar olarak kullanılabilir:

• Adları çözümleme (REST, MCP): Bir grup konum adını veya adresini Google Haritalar'daki belirli yer varlıklarıyla eşleştirin. Bu, yapılandırılmamış kullanıcı sorgularını sabit yer kimliklerine dayandırmak için kullanışlıdır.
• Haritalar URL'lerini çözümleme (REST, MCP): Bir grup Google Haritalar URL'sini belirli yer öğelerine çözümler. Desteklenen biçimler arasında standart yer URL'leri ve kısaltılmış URL'ler bulunur.

Döndürülen yer kimliklerini diğer Google Haritalar Platformu API'leriyle kullanabilirsiniz. Her yanıtta, çözümlenen yerleri Google Haritalar'da liste olarak kaydeden bir bağlantı da bulunur.

Daha fazla bilgi için Maps Tools Resolution API sayfasına bakın.

Maps Grounding Lite örnek uygulamasını deneyin (Yeni sekmede açılır)

Faturalandırma ve kotalar

Nasıl faturalandırılırsınız?

Google Haritalar Platformu'nun kullandıkça öde fiyatlandırma modelinde, Maps Grounding Lite kullanımı her istek için hesaplanır. Her istek, bir faturalandırma etkinliğini temsil eder. Kullanım, her ürün SKU'su için takip edilir. Faturanızda, toplam ücretlerinizin yanı sıra her SKU için bir satır öğesi gösterilir. Daha fazla bilgi için Raporlamaya genel bakış bölümüne bakın.

Fiyatlandırma ayrıntıları için Ana fiyatlandırma tablosu ve Hindistan fiyatlandırma tablosu'na bakın.

Resolution API'ye (ResolveNames ve ResolveMapsUrls) gönderilen istekler, Places API Text Search Essentials (IDs Only) SKU'su kapsamında ücretsiz olarak faturalandırılır.

Maps Grounding Lite, Essentials ve Pro paketleri kapsamında da sunulur. Tasarruf etmek için abone olun.

Kotalar

Maps Grounding Lite tarafından sağlanan araçlar ve API'ler için aşağıdaki kotalar geçerlidir:

• Search Places: Proje başına dakikada 300 sorgu.
• Hava durumu arama: Proje başına dakikada 300 sorgu.
• Compute Routes: Proje başına dakikada 300 sorgu.
• Adları çözümleme: Proje başına dakikada 600 sorgu.
• Resolve Maps URLs: Proje başına dakikada 600 sorgu.

Her Resolution API isteği, içerdiği öğe sayısına bakılmaksızın bir sorgu olarak sayılır.

Politikalar ve hizmet şartları

Maps Grounding Lite, bu hizmete ilişkin hizmete özel şartlar da dahil olmak üzere Google Haritalar Platformu Hizmet Şartları'na tabidir. Bu bölümde, uyumlu LLM'ler ve kaynak ilişkilendirme şartları dahil olmak üzere Maps Grounding Lite için ek hizmet kullanım şartları açıklanmaktadır.

Uyumlu LLM'ler için koşullar

Maps Grounding Lite'ı yalnızca Google Haritalar Platformu Hizmet Şartları'na uygun bir LLM ile kullanabilirsiniz.

Örneğin, Google Haritalar içeriğinin, kullanmayı seçtiğiniz LLM tarafından önbelleğe alınmamasını, depolanmamasını veya LLM'yi iyileştirmek için kullanılmamasını sağlamak sizin sorumluluğunuzdadır. Maps Grounding Lite'ı kullanmadan önce, Maps Grounding Lite ile kullanmayı planladığınız tüm modellerin Hizmet Şartları'nı incelemeniz gerekir. Maps Grounding Lite'ı, modele girilen verileri model eğitimi veya iyileştirme için kullanan modellerle kullanmamalısınız. Modeli kullanımınızın, hizmete özel şartlar da dahil olmak üzere Google Haritalar Platformu Hizmet Şartları'ndaki Google Haritalar İçeriği ile ilgili kısıtlamalara tam olarak uymasını sağlamak sizin sorumluluğunuzdadır.

Google Haritalar kaynakları için ilişkilendirme koşulları

Maps Grounding Lite'ın her araç yanıtı kaynakları içerir. Maps Grounding Lite tarafından sağlanan araçları kullanan sonuçları sunarken ilgili Google Haritalar kaynaklarını aşağıdaki şartları karşılayacak şekilde eklemeniz gerekir:

• Google Haritalar kaynakları, destekledikleri oluşturulan içeriğin hemen ardından gelmelidir. Oluşturulan bu içerik, temellendirilmiş çıkış olarak da adlandırılır.
• Google Haritalar kaynakları, tek bir kullanıcı etkileşimiyle görüntülenebilir olmalıdır.

Yer arama aracı için kaynaklar

search_places aracının places alanı, summary destekleyen kaynaklar sağlar. places için aşağıdaki meta veriler döndürülür:

• place (kaynak adı)
• id
• location
• googleMapsLinks

Her yer için aşağıdaki şartları karşılayan bir bağlantı önizlemesi oluşturmanız gerekir:

• Maps Grounding Lite metin ilişkilendirme yönergelerini uygulayarak her kaynağı Google Haritalar ile ilişkilendirin.
• Yanıttaki places.googleMapsLinks.placeUrl öğesini kullanarak kaynağa bağlantı oluşturun.

LLM'leri MCP sunucusunu kullanacak şekilde yapılandırma

Maps Grounding Lite'ı kullanmak için öncelikle Maps Grounding Lite API hizmetinin etkin olduğu bir Google Cloud projenizin yanı sıra API anahtarınız veya OAuth istemci kimliğiniz olmalıdır. Ardından, LLM'leri MCP sunucusuna erişecek şekilde yapılandırabilirsiniz. Grounding Lite MCP sunucusu, akışlı HTTP aktarımı kullanır.

Google Cloud projenizde Maps Grounding Lite hizmetini etkinleştirme

Projenizde API'yi etkinleştirmek için:

1. Google Cloud Console'da, Maps Grounding Lite için kullanmak istediğiniz projeyi seçin.
2. Google Cloud Console'da proje için faturalandırmayı etkinleştirin.
3. Google Cloud Console API Kitaplığı'nda Maps Grounding Lite'ı etkinleştirin.

API anahtarı kullanarak kimlik doğrulama

Hem Google Cloud projesinde hem de anahtarda Maps Grounding Lite API hizmetini etkinleştirdiğiniz sürece Maps Grounding Lite ile mevcut bir API anahtarını kullanabilir veya yeni bir anahtar oluşturabilirsiniz.

API anahtarı kullanarak kimlik doğrulaması yapmak için:

1. Google Haritalar Platformu'nu kullanmaya başlama bölümündeki adımları uygulayarak bir API anahtarı oluşturun veya yapılandırın.
2. X-Goog-Api-Key başlığını kullanarak anahtarı MCP sunucusuna iletin. Bunu, LLM'nin MCP aracı yapılandırmasında özel bir HTTP başlığı olarak belirtmeniz gerekir.

OAuth kullanarak kimlik doğrulama

OAuth kimlik bilgileri oluşturup bunları MCP ana makinesine veya MCP sunucu uygulamasına ileterek OAuth ile kimlik doğrulaması yapabilirsiniz.

OAuth kullanarak kimlik doğrulamak için:

1. Google Cloud Console'da, Maps Grounding Lite için kullanmak istediğiniz projeyi seçin.
2. API ve Hizmetler menüsünde Kimlik Bilgileri'ni seçin.
3. Üst menüde Kimlik bilgileri oluştur > OAuth istemci kimliği'ni seçin.
4. Projenin yapılandırılmış bir kullanıcı rızası ekranı yoksa Configure consent screen'i (Kullanıcı rızası ekranını yapılandır) tıklayın ve ekrandaki talimatları uygulayın.
5. Metrikler bölümünde OAuth istemcisi oluştur'u tıklayın.
6. OAuth istemci kimliği oluştur ekranında bir uygulama türü seçin ve istemci kimliği için bir ad girin.
7. Uygulama türünüzle ilgili ek ayrıntıları belirtin. Örneğin, bir web uygulaması oluşturuyorsanız tarayıcı ve sunucu istekleri için yetkili URI'ler ekleyin.
8. İstemciniz oluşturulduktan sonra istemci kimliğini ve gizli anahtarı kaydedin.
9. MCP ana makinenizi veya MCP sunucu uygulamanızı Maps Grounding Lite'a erişecek şekilde yapılandırırken OAuth istemci kimliğinizi ve gizli anahtarınızı iletin. Ayrıca şu kapsamı da istemeniz gerekir: https://www.googleapis.com/auth/maps-platform.mapstools.

Daha fazla bilgi için Google API'lerine Erişmek İçin OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.

LLM'leri Maps Grounding Lite MCP sunucusuna erişecek şekilde yapılandırma

Maps Grounding Lite API hizmetinin etkin olduğu bir Google Cloud projeniz ve geçerli kimlik bilgileriniz (ör. API anahtarı veya OAuth istemci kimliği ve gizli anahtarı) varsa LLM'leri, ilgili MCP yapılandırma belgelerini uygulayarak ve Maps Grounding Lite MCP sunucu URL'sini (https://mapstools.googleapis.com/mcp) kullanarak MCP sunucusuna erişecek şekilde yapılandırabilirsiniz.

Daha fazla bilgi için Yapay zeka uygulamasında MCP'yi yapılandırma başlıklı makaleyi inceleyin.

Gemini CLI ile Maps Grounding Lite'ı yapılandırma

Bu bölümde, Gemini CLI kullanarak Maps Grounding Lite MCP sunucusunun nasıl yapılandırılacağıyla ilgili bir örnek verilmiştir. Daha fazla bilgi için Gemini CLI ile MCP sunucuları başlıklı makaleyi inceleyin.

1. Gemini CLI'yı yükledikten sonra, Maps Grounding Lite MCP sunucusunu yapılandırmak için add komutunu kullanabilirsiniz:

   gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
   

   Yapılandırma başarılı olduysa sunucunun kullanıcı ayarlarınıza eklendiğini belirten bir onay mesajı görürsünüz.

2. Sunucunun doğru çalıştığını doğrulamak için /mcp list komutunu çalıştırın:

   > /mcp list
   
   Configured MCP servers:
   
   maps-grounding-lite-mcp - Ready (5 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   resolve_maps_urls
   -   resolve_names
   -   search_places
   

3. KSA ile Haritalar'a Sor ile ilgili sorular sormaya başlayın. Örneğin, "Bana Mountain View'da birkaç restoran öner" diyerek search_places aracını sizin adınıza çağırabilirsiniz.

Agent Development Kit (ADK) ile Grounding Lite'ı yapılandırma

Bu bölümde, Agent Development Kit (ADK) ve Python, Java veya TypeScript kullanarak Grounding Lite MCP sunucusunu nasıl yapılandıracağınızı gösteren örnekler verilmiştir.

# ./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"
                }
            )
        )
    ]
)
    

from . import agent
    

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();
        }
    }
}
    

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"
            }
        })
    ],
});
    

Geri bildirim paylaşma

Maps Grounding Lite ile ilgili geri bildirimlerinizi paylaşmak için aşağıdaki formları kullanın:

• Hata bildirme
• Özellik isteği gönderme
• Geri bildirim gönderme