ההארקה באמצעות מפות Google מחברת בין היכולות הגנרטיביות של Gemini לבין הנתונים העשירים, העובדתיים והעדכניים של מפות Google. התכונה הזו מאפשרת למפתחים לשלב בקלות באפליקציות שלהם פונקציונליות שמבוססת על מיקום. כשהשאילתה של המשתמש כוללת הקשר שקשור לנתונים של מפות Google, מודל Gemini משתמש במפות Google כדי לספק תשובות מדויקות מבחינה עובדתית ועדכניות שרלוונטיות למיקום הספציפי או לאזור הכללי שהמשתמש ציין.
- תשובות מדויקות שמודעות למיקום: שימוש בנתונים המקיפים והעדכניים של מפות Google לשאילתות ספציפיות מבחינה גיאוגרפית.
- התאמה אישית משופרת: התאמת ההמלצות והמידע על סמך המיקומים שהמשתמשים סיפקו.
- ווידג'טים ומידע לפי הקשר: טוקנים של הקשר להצגת ווידג'טים אינטראקטיביים של מפות Google לצד תוכן שנוצר.
שנתחיל?
בדוגמה הזו אפשר לראות איך לשלב Grounding עם מפות Google באפליקציה כדי לספק תשובות מדויקות שמתייחסות למיקום לשאילתות של משתמשים. ההנחיה מבקשת המלצות מקומיות עם מיקום משתמש אופציונלי, ומאפשרת למודל Gemini להשתמש בנתונים של מפות Google.
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',
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: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
ההארקה באמצעות מפות Google משלבת את Gemini API עם המערכת האקולוגית של Google Geo באמצעות Maps API כמקור הארקה. כששאילתה של משתמש מכילה הקשר גיאוגרפי, מודל Gemini יכול להפעיל את הכלי Grounding עם מפות Google. לאחר מכן, המודל יכול ליצור תשובות שמבוססות על נתונים ממפות Google שרלוונטיים למיקום שצוין.
התהליך בדרך כלל כולל:
- שאילתת משתמש: משתמש שולח שאילתה לאפליקציה שלכם, שיכולה לכלול הקשר גיאוגרפי (למשל, "coffee shops near me" (בתי קפה בסביבה), "museums in San Francisco" (מוזיאונים בסן פרנסיסקו).
- הפעלת כלי: מודל Gemini, שמזהה את הכוונה הגיאוגרפית, מפעיל את הכלי Grounding עם מפות Google. אפשר גם לספק לכלי את
latitudeוlongitudeשל המשתמש. הכלי הוא כלי לחיפוש טקסטואלי, והוא פועל באופן דומה לחיפוש במפות Google. כלומר, בשאילתות מקומיות ("בקרבתי") נעשה שימוש בקואורדינטות, בעוד שבשאילתות ספציפיות או לא מקומיות, סביר להניח שהמיקום המפורש לא ישפיע על התוצאות. - אחזור נתונים: שירות ה-Grounding עם מפות Google שולח שאילתות למפות Google כדי לקבל מידע רלוונטי (לדוגמה, מקומות, ביקורות, תמונות, כתובות, שעות פתיחה).
- יצירה מבוססת-קרקע: נתוני המפות שאוחזרו משמשים ליצירת התשובה של מודל Gemini, כדי להבטיח דיוק עובדתי ורלוונטיות.
- אסימון של תגובה ווידג'ט: המודל מחזיר תגובה טקסטואלית, שכוללת ציטוטים ממקורות במפות Google. אופציונלית, תגובת ה-API עשויה להכיל גם
google_maps_widget_context_token, שיאפשר למפתחים להציג בווידג'ט של מפות Google בהקשר מסוים באפליקציה שלהם, כדי ליצור אינטראקציה חזותית.
למה ומתי כדאי להשתמש בהארקה במפות Google
ההארקה באמצעות מפות Google מתאימה במיוחד לאפליקציות שנדרש בהן מידע מדויק, עדכני וספציפי למיקום. הוא משפר את חוויית המשתמש באמצעות תוכן רלוונטי ומותאם אישית שמבוסס על מסד הנתונים הנרחב של מפות Google, שכולל יותר מ-250 מיליון מקומות ברחבי העולם.
כדאי להשתמש ב-Grounding עם מפות Google כשהאפליקציה צריכה:
- לספק תשובות מלאות ומדויקות לשאלות שקשורות למיקום גיאוגרפי.
- פיתוח כלים לשיחות לתכנון טיולים ומדריכים מקומיים.
- המלצה על נקודות עניין על סמך מיקום והעדפות משתמש, כמו מסעדות או חנויות.
- ליצור חוויות מבוססות-מיקום לשירותים חברתיים, קמעונאיים או למשלוחי אוכל.
ההארקה באמצעות מפות Google מצטיינת בתרחישי שימוש שבהם נתונים עובדתיים עדכניים וקרבה הם קריטיים, כמו חיפוש של "בית הקפה הכי טוב בסביבה שלי" או קבלת הוראות הגעה.
שיטות ופרמטרים של API
ההארקה באמצעות מפות Google נחשפת דרך Gemini API ככלי בתוך השיטה generateContent. כדי להפעיל ולהגדיר Grounding באמצעות מפות Google, צריך לכלול אובייקט googleMaps בפרמטר tools של הבקשה.
JSON
{
"contents": [{
"parts": [
{"text": "Restaurants near Times Square."}
]
}],
"tools": { "googleMaps": {} }
}
בנוסף, הכלי googleMaps יכול לקבל פרמטר בוליאני enableWidget, שמשמש כדי לקבוע אם השדה googleMapsWidgetContextToken יוחזר בתגובה. אפשר להשתמש בזה כדי להציג ווידג'ט של מקומות לפי הקשר.
JSON
{
"contents": [{
"parts": [
{"text": "Restaurants near Times Square."}
]
}],
"tools": { "googleMaps": { "enableWidget": true } }
}
בנוסף, הכלי תומך בהעברת המיקום ההקשרי כ-toolConfig.
JSON
{
"contents": [{
"parts": [
{"text": "Restaurants near here."}
]
}],
"tools": { "googleMaps": {} },
"toolConfig": {
"retrievalConfig": {
"latLng": {
"latitude": 40.758896,
"longitude": -73.985130
}
}
}
}
הסבר על תגובת ההארקה
כשמבססים תגובה על נתונים ממפות Google, התגובה כוללת את השדה groundingMetadata.
הנתונים המובנים האלה חיוניים לאימות ההצהרות וליצירת חוויית ציטוט עשירה באפליקציה, וגם לעמידה בדרישות השימוש בשירות.
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:
-
groundingChunks: מערך של אובייקטים שמכילים את מקורותmaps(uri,placeIdו-title). -
groundingSupports: מערך של נתחי טקסט לחיבור טקסט התגובה של המודל למקורות ב-groundingChunks. כל מקטע מקשר בין טווח טקסט (מוגדר על ידיstartIndexו-endIndex) לביןgroundingChunkIndicesאחד או יותר. זהו המפתח ליצירת ציטוטים בגוף הטקסט. -
googleMapsWidgetContextToken: אסימון טקסט שאפשר להשתמש בו כדי לעבד ווידג'ט של מקומות בהקשר.
דוגמה לקטע קוד שמראה איך להציג ציטוטים בגוף הטקסט מופיעה במאמר בנושא ביסוס תשובות באמצעות חיפוש Google.
הצגת הווידג'ט ההקשרי של מפות Google
כדי להשתמש ב-googleMapsWidgetContextToken שמוחזר, צריך לטעון את Google Maps JavaScript API.
תרחישים לדוגמה
ההארקה באמצעות מפות Google תומכת במגוון תרחישים לדוגמה שמתבססים על מיקום. בדוגמאות הבאות מוסבר איך אפשר להשתמש בהנחיות ובפרמטרים שונים כדי להסתמך על נתונים ממפות Google. המידע בתוצאות המבוססות על עובדות במפות Google עשוי להיות שונה מהמצב בפועל.
איך עונים על שאלות ספציפיות לגבי מקום
אפשר לשאול שאלות מפורטות על מקום ספציפי ולקבל תשובות שמבוססות על ביקורות של משתמשים ב-Google ועל נתונים אחרים במפות Google.
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',
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: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}
}
}
}'
התאמה אישית לפי מיקום
קבלת המלצות שמותאמות להעדפות של משתמש ולאזור גיאוגרפי ספציפי.
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: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}
}
}
}'
עזרה בתכנון מסלול
יצירת תוכניות לכמה ימים עם הוראות הגעה ומידע על מיקומים שונים, מושלם לאפליקציות נסיעות.
בדוגמה הזו, הבקשה ל-googleMapsWidgetContextToken נשלחה על ידי הפעלת הווידג'ט בכלי של מפות Google. כשהאפשרות הזו מופעלת, אפשר להשתמש בטוקן שמוחזר כדי להציג ווידג'ט הקשרי של מקומות באמצעות <gmp-places-contextual> component מ-Google Maps JavaScript API.
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: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}
}
}
}'
כשמעבדים את הווידג'ט, הוא נראה בערך כך:
דרישות לשימוש בשירות
בקטע הזה מתוארות דרישות השימוש בשירות Grounding with Google Maps.
הודעה למשתמש על השימוש במקורות של מפות Google
לכל תוצאה מבוססת-קרקע במפות Google, תקבלו מקורות בgroundingChunks
תמיכה בכל תשובה. מוחזרים גם המטא-נתונים הבאים:
- URI במקור
- title
- מזהה
כשמציגים תוצאות מ-Grounding עם מפות Google, צריך לציין את המקורות המשויכים במפות Google ולעדכן את המשתמשים לגבי הדברים הבאים:
- מקורות המידע של מפות Google צריכים להופיע מיד אחרי התוכן שנוצר ושנתמך על ידי המקורות. התוכן שנוצר נקרא גם תוצאה מבוססת-קרקע ב-Google Maps.
- צריך לאפשר למשתמשים לצפות במקורות של מפות Google באינטראקציה אחת.
הצגת מקורות של מפות Google עם קישורים למפות Google
לכל מקור ב-groundingChunks וב-grounding_chunks.maps.placeAnswerSources.reviewSnippets, צריך ליצור תצוגה מקדימה של קישור בהתאם לדרישות הבאות:
- צריך לשייך כל מקור למפות Google בהתאם להנחיות לשיוך טקסט במפות Google.
- הצגת כותרת המקור שסופקה בתשובה.
- אפשר לקשר למקור באמצעות הסמל
uriאוgoogleMapsUriשמופיע בתשובה.
בתמונות האלה מוצגות הדרישות המינימליות להצגת המקורות והקישורים למפות Google.
אפשר לכווץ את תצוגת המקורות.
אופציונלי: אפשר להוסיף לקישור תצוגה מקדימה עם תוכן נוסף, כמו:
- סמל מועדפים של מפות Google מוכנס לפני טקסט השיוך של מפות Google.
- תמונה מכתובת ה-URL של המקור (
og:image).
מידע נוסף על חלק מספקי הנתונים של מפות Google ועל תנאי הרישיון שלהם מופיע בהודעות המשפטיות של מפות Google ו-Google Earth.
הנחיות לציון מקורות במפות Google
כשמייחסים מקורות למפות Google בטקסט, חשוב לפעול לפי ההנחיות הבאות:
- אל תשנו את הטקסט 'מפות Google' בשום צורה:
- אל תשנו את האיות של 'מפות Google'.
- אל תפצלו את כתובת מפות Google לכמה שורות.
- אסור להתאים את מפות Google לשוק המקומי בשפה אחרת.
- כדי למנוע מדפדפנים לתרגם את מפות Google, משתמשים בתכונת ה-HTML translate="no".
- מעצבים את הטקסט במפות Google לפי ההנחיות שבטבלה הבאה:
| נכס | סגנון |
|---|---|
Font family |
Roboto. טעינת הגופן היא אופציונלית. |
Fallback font family |
כל גופן Sans Serif שמשמש כגופן גוף במוצר או Sans-Serif כדי להפעיל את גופן המערכת שמוגדר כברירת מחדל |
Font style |
רגיל |
Font weight |
400 |
Font color |
לבן, שחור (#1F1F1F) או אפור (#5E5E5E). שומרים על ניגודיות נגישה (4.5:1) ביחס לרקע. |
Font size |
|
Spacing |
רגיל |
דוגמה ל-CSS
קוד ה-CSS הבא מעבד את מפות Google עם סגנון הטיפוגרפיה והצבע המתאימים על רקע לבן או בהיר.
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;
}
טוקן הקשר, מזהה המקום ומזהה הביקורת
הנתונים של מפות Google כוללים טוקן הקשר, מזהה מקום ומזהה ביקורת. יכול להיות שתשמרו במטמון, תאחסנו ותייצאו את נתוני התשובות הבאים:
googleMapsWidgetContextTokenplaceIdreviewId
המגבלות נגד שמירה במטמון בתנאים של Grounding עם מפות Google לא חלות.
פעילות אסורה ואזור אסור
כדי לשמור על הבטיחות והאמינות של פלטפורמת מפות Google, יש הגבלות נוספות על תוכן ופעילויות מסוימים שקשורים לקרקוע. בנוסף להגבלות השימוש שמפורטות בתנאים, אסור להשתמש ב-Grounding עם מפות Google לפעילויות בסיכון גבוה, כולל שירותי תגובה למקרי חירום. לא תפיצו או תשווקו את האפליקציה שלכם שמציעה Grounding עם מפות Google באזור אסור. האזורים האסורים כרגע הם:
- סין
- חצי האי קרים
- קובה
- הרפובליקה העממית של דונצק
- איראן
- הרפובליקה העממית של לוהנסק
- קוריאה הצפונית
- סוריה
- וייטנאם
יכול להיות שנעדכן את הרשימה הזו מדי פעם.
שיטות מומלצות
- ציון מיקום המשתמש: כדי לקבל תשובות רלוונטיות ומותאמות אישית, תמיד צריך לכלול את
user_location(קווי רוחב ואורך) בהגדרות שלgoogleMapsGroundingכשמיקום המשתמש ידוע. - הצגת הווידג'ט ההקשרי של מפות Google: הווידג'ט ההקשרי מוצג באמצעות טוקן ההקשר,
googleMapsWidgetContextToken, שמוחזר בתגובת Gemini API. אפשר להשתמש בו כדי להציג תוכן חזותי ממפות Google. מידע נוסף על הווידג'ט ההקשרי זמין במאמר הארקה באמצעות הווידג'ט של מפות Google במדריך למפתחים של Google. - ליידע את משתמשי הקצה: חשוב ליידע את משתמשי הקצה בצורה ברורה שהנתונים של מפות Google משמשים למענה על השאילתות שלהם, במיוחד כשהכלי מופעל.
- מעקב אחרי זמן האחזור: באפליקציות שיש בהן ממשק שיחה, חשוב לוודא שזמן האחזור של תגובות מבוססות-ידע (grounded) בערך P95 נשאר בגבולות הסבירים, כדי לשמור על חוויית משתמש חלקה.
- השבתה כשלא צריך: ההארקה באמצעות מפות Google מושבתת כברירת מחדל. כדי לשפר את הביצועים ולצמצם את העלויות, מפעילים את האפשרות הזו (
"tools": [{"googleMaps": {}}]) רק כשיש שאילתה עם הקשר גיאוגרפי ברור.
מגבלות
- היקף גיאוגרפי: בשלב הזה, ההארקה באמצעות מפות Google זמינה בכל העולם.
- תמיכה במודלים: רק מודלים ספציפיים של Gemini תומכים ב-Grounding עם מפות Google: Gemini 2.5 Flash-Lite, Gemini 2.5 Pro, Gemini 2.5 Flash ו-Gemini 2.0 Flash (אבל לא Gemini 2.0 Flash Lite).
- קלט/פלט מולטימודאלי: בשלב הזה, ההארקה באמצעות מפות Google לא תומכת בקלט או בפלט מולטימודאליים מעבר לטקסט ולרכיבי widget של מפות בהקשר.
- מצב ברירת מחדל: הכלי Grounding with Google Maps מושבת כברירת מחדל. צריך להפעיל אותו במפורש בבקשות ל-API.
תמחור ומגבלות על קצב יצירת הבקשות
ההארקה עם תמחור של מפות Google מבוססת על שאילתות. התעריף הנוכחי הוא 25$ ל-1,000 הנחיות עם הארקה. בנוסף, בתוכנית ללא תשלום אפשר לשלוח עד 500 בקשות ביום. בקשה נספרת רק במסגרת המכסה אם הנחיה מחזירה בהצלחה לפחות תוצאה אחת מבוססת-קרקע של מפות Google (כלומר, תוצאות שמכילות לפחות מקור אחד של מפות Google). אם כמה שאילתות נשלחות אל מפות Google מבקשה אחת, הן נספרות כבקשה אחת במגבלת הקצב.
מידע מפורט על התמחור זמין בדף התמחור של Gemini API.
מודלים נתמכים
אפשר למצוא את היכולות שלהם בדף סקירת המודל.
| דגם | עיגון באמצעות מפות Google |
|---|---|
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
| Gemini 2.0 Flash | ✔️ |
המאמרים הבאים
- כדאי לנסות את העיגון בחיפוש Google ב-Gemini API Cookbook.
- אפשר לקרוא על כלים זמינים אחרים, כמו קריאה לפונקציה.
- כדי לקבל מידע נוסף על שיטות מומלצות לשימוש אחראי ב-AI ועל מסנני הבטיחות של Gemini API, אפשר לעיין במדריך להגדרות הבטיחות.