Google Haritalar ile temellendirme

Google Haritalar ile temellendirme, Gemini'ın üretken özelliklerini Google Haritalar'ın zengin, doğru ve güncel verileriyle birleştirir. Bu özellik, geliştiricilerin konuma duyarlı işlevleri uygulamalarına kolayca dahil etmelerini sağlar. Kullanıcı sorgusu Haritalar verileriyle ilgili bir bağlama sahip olduğunda Gemini modeli, kullanıcının belirttiği konum veya genel alanla alakalı, olgusal olarak doğru ve güncel yanıtlar sağlamak için Google Haritalar'dan yararlanır.

  • Doğru ve konuma duyarlı yanıtlar: Coğrafi olarak belirli sorgular için Google Haritalar'ın kapsamlı ve güncel verilerinden yararlanın.
  • Gelişmiş kişiselleştirme: Kullanıcı tarafından sağlanan konumlara göre önerileri ve bilgileri uyarlayın.
  • Bağlamsal bilgiler ve widget'lar: Oluşturulan içeriğin yanında etkileşimli Google Haritalar widget'ları oluşturmak için bağlam jetonları.

Başlayın

Bu örnekte, kullanıcı sorgularına doğru ve konuma duyarlı yanıtlar sağlamak için Grounding with Google Maps'i uygulamanıza nasıl entegre edeceğiniz gösterilmektedir. İstemde, yerel öneriler isteniyor ve isteğe bağlı olarak kullanıcı konumu da belirtiliyor. Böylece Gemini modeli, Google Haritalar verilerinden yararlanabiliyor.

Python

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-2.5-flash-lite',
    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})')

JavaScript

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

const ai = new GoogleGenAI({});

async function generateContentWithMapsGrounding() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-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();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -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}
    }
  }
}'

Google Haritalar ile temellendirmenin işleyiş şekli

Google Haritalar ile temellendirme, temellendirme kaynağı olarak Haritalar API'sini kullanarak Gemini API'yi Google Coğrafi Ekosistemi ile entegre eder. Kullanıcının sorgusu coğrafi bağlam içerdiğinde Gemini modeli, Google Haritalar ile Temellendirme aracını çağırabilir. Model daha sonra, sağlanan konumla alakalı Google Haritalar verilerine dayalı yanıtlar üretebilir.

Bu süreç genellikle şunları içerir:

  1. Kullanıcı sorgusu: Bir kullanıcı, uygulamanıza sorgu gönderir.Bu sorgu, coğrafi bağlam (ör. "yakınımdaki kafeler", "San Francisco'daki müzeler").
  2. Araç çağırma: Gemini modeli, coğrafi amacı tanıyarak Google Haritalar ile Temellendirme aracını çağırır. Bu araç, konumla ilgili sonuçlar için isteğe bağlı olarak kullanıcının latitude ve longitude ile birlikte sağlanabilir.
  3. Veri alma: Google Haritalar ile Temellendirme hizmeti, Google Haritalar'da alakalı bilgiler (ör. yerler, yorumlar, fotoğraflar, adresler, çalışma saatleri) için sorgu gönderir.
  4. Temellendirilmiş üretim: Alınan Haritalar verileri, Gemini modelinin yanıtını bilgilendirmek için kullanılır. Bu sayede, yanıtın olgusal doğruluğu ve alaka düzeyi sağlanır.
  5. Yanıt ve widget jetonu: Model, Google Haritalar kaynaklarına alıntılar içeren bir metin yanıtı döndürür. İsteğe bağlı olarak, API yanıtı google_maps_widget_context_token da içerebilir. Bu sayede geliştiriciler, görsel etkileşim için uygulamalarında bağlamsal bir Google Haritalar widget'ı oluşturabilir.

Google Haritalar ile Temellendirme neden ve ne zaman kullanılmalı?

Google Haritalar ile temellendirme, doğru, güncel ve konuma özel bilgiler gerektiren uygulamalar için idealdir. Dünya genelinde 250 milyondan fazla yerin bulunduğu Google Haritalar'ın kapsamlı veritabanı tarafından desteklenen alakalı ve kişiselleştirilmiş içerikler sunarak kullanıcı deneyimini iyileştirir.

Uygulamanızın aşağıdaki durumlarda Google Haritalar ile Temellendirme'yi kullanması gerekir:

  • Coğrafi konuma özel sorulara eksiksiz ve doğru yanıtlar verin.
  • Sohbet tabanlı gezi planlayıcıları ve yerel rehberler oluşturun.
  • Konuma ve kullanıcı tercihlerine (ör. restoranlar veya mağazalar) göre ilgi çekici yerler önerin.
  • Sosyal medya, perakende veya yemek teslimatı hizmetleri için konuma duyarlı deneyimler oluşturun.

Google Haritalar ile temellendirme, "yakınımdaki en iyi kahve dükkanını" bulma veya yol tarifi alma gibi yakınlık ve güncel gerçek verilerin kritik olduğu kullanım alanlarında mükemmeldir.

API yöntemleri ve parametreleri

Google Haritalar ile temellendirme, Gemini API üzerinden generateContent yöntemi içinde bir araç olarak sunulur. İsteğinizin tools parametresine bir googleMaps nesnesi ekleyerek Google Haritalar ile Temellendirme'yi etkinleştirip yapılandırabilirsiniz.

JSON

{
  "contents": [{
    "parts": [
      {"text": "Restaurants near Times Square."}
    ]
  }],
  "tools":  { "googleMaps": {} }
}

googleMaps aracı, googleMapsWidgetContextToken alanının yanıtta döndürülüp döndürülmeyeceğini kontrol etmek için kullanılan bir boole enableWidget parametresini de kabul edebilir. Bu, bağlama dayalı Yerler widget'ı göstermek için kullanılabilir.

JSON

{
"contents": [{
    "parts": [
      {"text": "Restaurants near Times Square."}
    ]
  }],
  "tools":  { "googleMaps": { "enableWidget": true } }
}

Ayrıca araç, bağlamsal konumun toolConfig olarak iletilmesini destekler.

JSON

{
  "contents": [{
    "parts": [
      {"text": "Restaurants near here."}
    ]
  }],
  "tools":  { "googleMaps": {} },
  "toolConfig":  {
    "retrievalConfig": {
      "latLng": {
        "latitude": 40.758896,
        "longitude": -73.985130
      }
    }
  }
}

Temellendirme yanıtını anlama

Bir yanıt, Google Haritalar verileriyle başarıyla temellendirildiğinde yanıtta groundingMetadata alanı bulunur. Bu yapılandırılmış veriler, iddiaları doğrulamak, uygulamanızda zengin bir alıntı deneyimi oluşturmak ve hizmet kullanım şartlarını karşılamak için gereklidir.

JSON

{
  "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"
        ],
        "googleMapsWidgetContextToken": "widgetcontent/..."
      }
    }
  ]
}

Gemini API, groundingMetadata ile aşağıdaki bilgileri döndürür:

  • groundingChunks: maps kaynaklarını (uri, placeId ve title) içeren nesne dizisi.
  • groundingSupports: Model yanıtı metnini groundingChunks içindeki kaynaklara bağlamak için kullanılacak parçalar dizisi. Her parça, bir metin aralığını (startIndex ve endIndex ile tanımlanır) bir veya daha fazla groundingChunkIndices ile bağlar. Bu, satır içi alıntılar oluşturmanın anahtarıdır.
  • googleMapsWidgetContextToken: Bağlamsal Yerler widget'ı oluşturmak için kullanılabilen bir metin jetonu.

Metindeki satır içi alıntıların nasıl oluşturulacağını gösteren kod snippet'i için örneğe bakın. Bu örneği, Google Arama ile temellendirme dokümanlarında bulabilirsiniz.

Google Haritalar bağlamsal widget'ını görüntüleme

Döndürülen googleMapsWidgetContextToken değerini kullanmak için Google Maps JavaScript API'yi yüklemeniz gerekir.

Kullanım alanları

Google Haritalar ile temellendirme, konuma duyarlı çeşitli kullanım alanlarını destekler. Aşağıdaki örneklerde, farklı istemlerin ve parametrelerin Google Haritalar ile Temellendirme'den nasıl yararlanabileceği gösterilmektedir. Google Haritalar'daki temellendirilmiş sonuçlarda yer alan bilgiler gerçek koşullardan farklı olabilir.

Yere özgü soruları yanıtlama

Google kullanıcı yorumlarına ve diğer Haritalar verilerine dayalı yanıtlar almak için belirli bir yer hakkında ayrıntılı sorular sorun.

Python

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-2.5-flash-lite',
    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})')
  ```

JavaScript

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

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -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}
    }
  }
}'

Konuma dayalı kişiselleştirme sağlama

Kullanıcının tercihlerine ve belirli bir coğrafi bölgeye göre uyarlanmış öneriler alın.

Python

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-2.5-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})')

JavaScript

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

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -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}
    }
  }
}'

Seyahat planı oluşturma konusunda yardım

Çeşitli yerler hakkında yol tarifleri ve bilgiler içeren çok günlük planlar oluşturun. Bu planlar, seyahat uygulamaları için idealdir.

Bu örnekte, Google Haritalar aracında widget etkinleştirilerek googleMapsWidgetContextToken istenmiştir. Etkinleştirildiğinde, döndürülen jeton, Google Maps JavaScript API'den <gmp-places-contextual> component kullanılarak bağlamsal bir Yerler widget'ı oluşturmak için kullanılabilir.

Python

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-2.5-flash',
    contents=prompt,
    config=types.GenerateContentConfig(
      tools=[types.Tool(google_maps=types.GoogleMaps(enable_widget=True))],
      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})')

  if widget_token := grounding.google_maps_widget_context_token:
    print('-' * 40)
    print(f'<gmp-place-contextual context-token="{widget_token}"></gmp-place-contextual>')

JavaScript

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-2.5-flash',
    contents: prompt,
    config: {
      tools: [{googleMaps: {enableWidget: true}}],
      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})`);
        }
      }
    }

    if (groundingMetadata.googleMapsWidgetContextToken) {
      console.log('-'.repeat(40));
      document.body.insertAdjacentHTML('beforeend', `<gmp-place-contextual context-token="${groundingMetadata.googleMapsWidgetContextToken}`"></gmp-place-contextual>`);
    }
  }
}

run();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -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": {"enableWidget":"true"}}],
  "toolConfig": {
    "retrievalConfig": {
    "latLng": {"latitude": 37.78193, "longitude": -122.40476}
  }
  }
}'

Widget oluşturulduğunda aşağıdaki gibi görünür:

Oluşturulan bir harita widget&#39;ı örneği

Hizmet kullanım şartları

Bu bölümde, Google Haritalar ile Temellendirme için hizmet kullanım şartları açıklanmaktadır.

Kullanıcıyı Google Haritalar kaynaklarının kullanımı hakkında bilgilendirme

Her Google Haritalar Temellendirilmiş Sonucu ile birlikte, her yanıtı destekleyen kaynaklar groundingChunks alacaksınız. Aşağıdaki meta veriler de döndürülür:

  • kaynak URI
  • title
  • Kimlik

Google Haritalar ile Temellendirme'den elde edilen sonuçları sunarken ilişkili Google Haritalar kaynaklarını belirtmeniz ve kullanıcılarınızı aşağıdakiler hakkında bilgilendirmeniz gerekir:

  • Google Haritalar kaynakları, kaynakların desteklediği oluşturulmuş içeriği hemen takip etmelidir. Bu oluşturulan içeriğe Google Haritalar'a dayalı sonuç da denir.
  • Google Haritalar kaynakları, tek bir kullanıcı etkileşimi içinde görüntülenebilmelidir.

groundingChunks ve grounding_chunks.maps.placeAnswerSources.reviewSnippets içindeki her kaynak için aşağıdaki şartlara uygun bir bağlantı önizlemesi oluşturulmalıdır:

  • Google Haritalar metin atfetme yönergelerine uyarak her kaynağı Google Haritalar'a atfedin.
  • Yanıtta verilen kaynak başlığını gösterir.
  • Yanıtın uri veya googleMapsUri simgesini kullanarak kaynağa bağlantı verin.

Bu resimlerde, kaynakların ve Google Haritalar bağlantılarının gösterilmesi için gereken minimum koşullar açıklanmaktadır.

Kaynakları gösteren yanıt istemi

Kaynakların görünümünü daraltabilirsiniz.

Yanıt ve kaynakların daraltıldığı istem

İsteğe bağlı: Bağlantı önizlemesini aşağıdaki gibi ek içeriklerle zenginleştirin:

  • Google Haritalar metin ilişkilendirmesinden önce Google Haritalar favicon'u eklenir.
  • Kaynak URL'deki (og:image) bir fotoğraf.

Google Haritalar veri sağlayıcılarımız ve lisans şartları hakkında daha fazla bilgi için Google Haritalar ve Google Earth yasal bildirimleri'ne bakın.

Google Haritalar metin atıfı yönergeleri

Metinde kaynakları Google Haritalar'a atfederken aşağıdaki yönergelere uyun:

  • Google Haritalar metnini hiçbir şekilde değiştirmeyin:
    • Google Haritalar'ın büyük harf kullanımını değiştirmeyin.
    • Google Haritalar'ı birden fazla satıra sarmayın.
    • Google Haritalar'ı başka bir dile yerelleştirmeyin.
    • HTML özelliğini kullanarak tarayıcıların Google Haritalar'ı çevirmesini engelleyin.
  • Google Haritalar metnini aşağıdaki tabloda açıklandığı şekilde stilize edin:
Mülk Stil
Font family Roboto. Yazı tipini yüklemek isteğe bağlıdır.
Fallback font family Ürününüzde zaten kullanılan herhangi bir sans serif gövde yazı tipi veya varsayılan sistem yazı tipini çağırmak için "Sans-Serif"
Font style Normal
Font weight 400
Font color Beyaz, siyah (#1F1F1F) veya gri (#5E5E5E). Arka planla erişilebilir (4.5:1) kontrastı koruyun.
Font size
  • Minimum yazı tipi boyutu: 12 sp
  • Maksimum yazı tipi boyutu: 16sp
  • sp hakkında bilgi edinmek için Materyal Tasarım web sitesindeki yazı tipi boyutu birimlerine bakın.
Spacing Normal

Örnek CSS

Aşağıdaki CSS, Google Haritalar'ı beyaz veya açık renkli bir arka planda uygun tipografik stil ve renkle oluşturur.

CSS

@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;
}

Bağlam jetonu, yer kimliği ve yorum kimliği

Google Haritalar verileri bağlam jetonu, yer kimliği ve yorum kimliğini içerir. Aşağıdaki yanıt verilerini önbelleğe alabilir, depolayabilir ve dışa aktarabilirsiniz:

  • googleMapsWidgetContextToken
  • placeId
  • reviewId

Google Haritalar ile Temellendirme Şartları'ndaki önbelleğe alma kısıtlamaları geçerli değildir.

Yasaklanan etkinlik ve bölge

Google Haritalar ile temellendirme, güvenli ve güvenilir bir platform sağlamak için belirli içerik ve etkinliklerle ilgili ek kısıtlamalara sahiptir. Şartlar'daki kullanım kısıtlamalarına ek olarak, Google Haritalar ile Temellendirme'yi acil durum müdahale hizmetleri de dahil olmak üzere yüksek riskli faaliyetler için kullanmayacaksınız. Google Haritalar ile Temellendirme sunan uygulamanızı Yasaklanan Bölge'de dağıtmayacak veya pazarlamayacaksınız. Şu anda yasaklanmış bölgeler şunlardır:

  • Çin
  • Kırım
  • Küba
  • Donetsk Halk Cumhuriyeti
  • İran
  • Luhansk Halk Cumhuriyeti
  • Kuzey Kore
  • Suriye
  • Vietnam

Bu liste zaman zaman güncellenebilir.

En iyi uygulamalar

  • Kullanıcı konumunu sağlama: En alakalı ve kişiselleştirilmiş yanıtlar için kullanıcının konumu bilindiğinde googleMapsGrounding yapılandırmanıza her zaman user_location (enlem ve boylam) ekleyin.
  • Google Haritalar bağlamsal widget'ını oluşturun: Bağlamsal widget, Gemini API yanıtında döndürülen ve Google Haritalar'daki görsel içerikleri oluşturmak için kullanılabilen bağlam jetonu googleMapsWidgetContextToken ile oluşturulur. İçeriğe dayalı widget hakkında daha fazla bilgi için Google Geliştirici Kılavuzu'ndaki Google Haritalar widget'ı ile temellendirme başlıklı makaleyi inceleyin.
  • Son Kullanıcıları Bilgilendirin: Özellikle araç etkinleştirildiğinde, Google Haritalar verilerinin sorgularını yanıtlamak için kullanıldığını son kullanıcılarınıza net bir şekilde bildirin.
  • Gecikmeyi İzleme: Sohbet uygulamalarında, temellendirilmiş yanıtların P95 gecikmesinin sorunsuz bir kullanıcı deneyimi sağlamak için kabul edilebilir eşiklerde kalmasını sağlayın.
  • Gerekmediğinde Kapatma: Google Haritalar ile temellendirme varsayılan olarak kapalıdır. Performansı ve maliyeti optimize etmek için yalnızca bir sorgunun net bir coğrafi bağlamı olduğunda ("tools": [{"googleMaps": {}}]) etkinleştirin.

Sınırlamalar

  • Coğrafi Kapsam: Google Haritalar ile Temellendirme şu anda dünya genelinde kullanılabilir.
  • Model Desteği: Google Haritalar ile Temellendirme yalnızca belirli Gemini modellerinde desteklenir: Gemini 2.5 Flash-Lite, Gemini 2.5 Pro, Gemini 2.5 Flash ve Gemini 2.0 Flash (2.0 Flash Lite değil).
  • Çok Formatlı Girişler/Çıkışlar: Google Haritalar ile temellendirme şu anda metin ve bağlamsal harita widget'larının ötesinde çok formatlı girişleri veya çıkışları desteklememektedir.
  • Varsayılan Durum: Google Haritalar ile Temellendirme aracı varsayılan olarak devre dışıdır. Bu özelliği API isteklerinizde açıkça etkinleştirmeniz gerekir.

Fiyatlandırma ve sıklık sınırları

Google Haritalar ile temellendirme fiyatlandırması sorgulara göre belirlenir. Geçerli ücret 25 ABD doları / 1.000 temellendirilmiş istem'dir. Bir istek yalnızca istem başarıyla en az bir Google Haritalar temelli sonuç (ör. en az bir Google Haritalar kaynağı içeren sonuçlar) döndürdüğünde kotaya dahil edilir. Tek bir istekten Google Haritalar'a birden fazla sorgu gönderilirse bu, hız sınırına göre tek bir istek olarak sayılır.

Ayrıntılı fiyatlandırma bilgileri için Gemini API fiyatlandırma sayfasına bakın.

Desteklenen modeller

Bu modellerin özelliklerini Modele genel bakış sayfasında bulabilirsiniz.

Model Google Haritalar ile temellendirme
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

Sırada ne var?