שירות ההשלמה האוטומטית (חדש) הוא שירות אינטרנט שמחזיר מקום חיזויים וחיזויים של שאילתות בתגובה לבקשת HTTP. בבקשה, מציינים טקסט מחרוזת חיפוש וגבולות גיאוגרפיים ששולטים באזור החיפוש.
שירות ההשלמה האוטומטית (חדש) יכול להתאים למילים שלמות וגם מחרוזות משנה של הקלט, לפתרון שמות של מקומות, כתובות קודי OLC. לכן האפליקציות יכולות לשלוח בזמן שהמשתמש מקליד, כדי לספק תחזיות לגבי מקום בזמן אמת ושאילתות.
התגובה מ-API להשלמה אוטומטית (חדש) יכולה להכיל שני סוגים של החיזויים:
- חיזויים של מקומות: מקומות כמו עסקים, כתובות ונקודות של על סמך מחרוזת טקסט הקלט ואזור החיפוש שצוינו. חיזויים לגבי מקומות מוחזרים כברירת מחדל.
- חיזויים של שאילתות: מחרוזות שאילתה שתואמות למחרוזת טקסט הקלט וגם
אזור החיפוש. כברירת מחדל, שאילתות החיפוש החזויות לא מוחזרות. משתמשים ב
של הפרמטר
includeQueryPredictions
של הבקשה להוסיף חיזויים של שאילתות אל תשובה.
לדוגמה, אפשר לקרוא ל-API על ידי שימוש במחרוזת שמכילה קלט חלקי של משתמש, "פיצה סיציליאנית", כשאזור החיפוש מוגבל לסן פרנסיסקו, קליפורניה. התשובה תכיל רשימה של חיזויים של מקומות שתואמים למחרוזת החיפוש ולאזור החיפוש, כמו מסעדה בשם "Sicilian Pizza Kitchen", עם פרטים על המקום.
חיזויים של מקומות שמוחזרים נועדו להציג למשתמש כדי לסייע כשהם בוחרים את המקום הרצוי. אפשר ליצור פרטי מקום (חדש) בקשה לקבל מידע נוסף על כל החיזויים של המקומות שהוחזרו.
התגובה יכולה גם להכיל רשימה של חיזויים של שאילתות שתואמים ל-
מחרוזת חיפוש ואזור חיפוש, כגון "פיצה סיציליאנית לפסטה". כל חיזוי של שאילתה
התגובה כוללת את השדה text
שמכיל מחרוזת מומלצת של חיפוש טקסט. שימוש בטיוטה הזו
בתור קלט,
חיפוש טקסט (חדש)
כדי לבצע חיפוש מפורט יותר.
API Explorer מאפשר לכם לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות API:
רוצים לנסות?בקשות להשלמה אוטומטית (חדש)
בקשת השלמה אוטומטית (חדש) היא בקשת HTTP POST לכתובת URL ב- הטופס:
https://places.googleapis.com/v1/places:autocomplete
העברה של כל הפרמטרים בגוף הבקשה של JSON או בכותרות כחלק מבקשת ה-POST. לדוגמה:
curl -X POST -d '{ "input": "pizza", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
מידע על התשובה
השלמה אוטומטית (חדש) מחזירה אובייקט JSON כתגובה. בתשובה:
- מערך
suggestions
מכיל את כל המקומות והשאילתות החזויים לפי הסדר על סמך מידת הרלוונטיות שבה הם נתפסו. כל מקום מיוצג על ידי השדהplacePrediction
וכל שאילתה מיוצגת בשדהqueryPrediction
. - שדה
placePrediction
מכיל מידע מפורט על חיזוי של מקום, כולל מזהה המקום ותיאור טקסט. - שדה
queryPrediction
מכיל מידע מפורט על נוכל לחזות את השאילתה.
אובייקט ה-JSON המלא מופיע בתבנית:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 }] }, ... }, { "queryPrediction": { "text": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 }] }, ... } ...] }
פרמטרים נדרשים
-
קלט
מחרוזת הטקסט שבה יש לחפש. לציין מילים מלאות ומחרוזות משנה, שמות של מקומות, כתובות וקודי OLC. שירות ההשלמה האוטומטית (חדש) מחזירה התאמות מועמדים על סמך המחרוזת הזו והתוצאות מסודרות לפי הרלוונטיות המשמעותית שלהם.
פרמטרים אופציונליים
-
includedPrimaryTypes
למקום יכול להיות רק סוג ראשי יחיד מהסוגים המפורטים טבלה א' או טבלה ב'. לדוגמה, הסוג הראשי יכול להיות
"mexican_restaurant"
או"steak_house"
.כברירת מחדל, ה-API מחזיר את כל המקומות על סמך הפרמטר
input
, בלי קשר של ערך הסוג הראשי שמשויך למקום. הגבלת התוצאות לערך מסוים הסוג הראשי או הסוגים הראשיים, על ידי העברת הפרמטרincludedPrimaryTypes
.משתמשים בפרמטר הזה כדי לציין עד חמישה סוגי ערכים מטבלה א' או טבלה ב'. המקום תואם לאחד מערכי הסוג הראשי שצוינו שייכללו בתשובה.
במקום זאת, הפרמטר הזה יכול לכלול אחד מהערכים
(regions)
או(cities)
. סוג האוסף(regions)
מסננים לפי אזורים או מחלקות, כמו שכונות ואזורי מיקוד. באוסף 'סוג(cities)
' מתבצע סינון לפי מקומות ש-Google מזהה כעיר.הבקשה נדחית ותוצג השגיאה
INVALID_REQUEST
אם:- ציינת יותר מחמישה סוגים.
- כל סוג מצוין בנוסף ל-
(cities)
או ל-(regions)
. - כל הסוגים לא מזוהים.
-
includeQueryPredictions
אם הערך שלו הוא
true
, התשובה תכלול גם חיזויים של מקומות וגם של שאילתות. ברירת המחדל הואfalse
, כלומר התשובה כוללת רק חיזויים לגבי מקומות. -
includedRegionCodes
כלול רק תוצאות מרשימת האזורים שצוינו, המצוינת כמערך של עד 15 ccTLD ('דומיין ברמה העליונה') בשני תווים. אם לא מזינים, לא חלות הגבלות על התשובה. לדוגמה, כדי להגביל את האזורים לגרמניה ולצרפת:
"includedRegionCodes": ["de", "fr"]
אם מציינים גם
locationRestriction
וגםincludedRegionCodes
, התוצאות ממוקמות באזור החיתוך של שתי ההגדרות. -
inputOffset
היסט של תווים ב-Unicode שמבוסס על אפס, שמציין את מיקום הסמן ב-
input
. מיקום הסמן יכול להשפיע על החיזויים שיוחזרו. אם השדה ריק, ברירת המחדל היא באורך שלinput
. -
languageCode
השפה המועדפת שבה יוחזרו תוצאות. התוצאות עשויות להיות בשפות שונות אם השפה ב-
input
שונה מהערך שצוין על ידיlanguageCode
, או אם המקום שהוחזר לא כולל תרגום השפה המקומית לlanguageCode
.- צריך להשתמש ב-IETF קודי שפה מסוג BCP-47 כדי לציין את השפה המועדפת.
-
אם לא תספקו את
languageCode
, ה-API ישתמש בערך שצוין הכותרתAccept-Language
. אם לא צוין אף אחד מהם, ברירת המחדל היאen
אם מציינים קוד שפה לא חוקי, ה-API יחזיר קוד שפה לא חוקי. שגיאה אחת (INVALID_ARGUMENT
). - לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות ה-API בוחר להחזיר, ואת הסדר שבו הן מוחזרות. תהיה לכך גם השפעה על היכולת של ה-API לתקן שגיאות איות.
-
ממשק ה-API מנסה לספק כתובת רחוב שניתנת לקריאה גם עבור המשתמש וגם עבור
האוכלוסייה המקומית, ובמקביל לשקף את הקלט של המשתמשים. חיזויים לגבי מקומות
בפורמט שונה בהתאם לקלט של המשתמשים בכל בקשה.
-
קודם כל צריך לבחור מונחים תואמים בפרמטר
input
, כשהשמות יהיו מיושרים עם העדפת השפה שצוינה בפרמטרlanguageCode
, זמין, ובמקרים אחרים משתמשים בשמות שהכי מתאימים לקלט של המשתמש. -
כתובות של רחובות מעוצבות בשפה המקומית, בסקריפט שהמשתמש יכול לקרוא
כשהדבר אפשרי, רק לאחר שנבחרו המונחים התואמים את המונחים
הפרמטר
input
. -
כל שאר הכתובות מוחזרות בשפה המועדפת, לאחר שהמונחים התואמים
נבחר להתאים למונחים בפרמטר
input
. אם אין שם בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.
-
קודם כל צריך לבחור מונחים תואמים בפרמטר
טירגוט לפי מיקום או הגבלת מיקום
אפשר לציין
locationBias
אוlocationRestriction
, אבל לא את שניהם, כדי להגדיר את אזור החיפוש. יש להתייחס אלlocationRestriction
כאל מידע ספציפי האזור שבו התוצאות צריכות להופיע,locationBias
ציון האזור שהתוצאות חייבות להיות קרובות אליו, אבל יכולות להיות מחוץ לו את האזור.locationBias
מציין את האזור לחיפוש. המיקום הזה משמש כהטיה כלומר ניתן להחזיר תוצאות סביב המיקום שצוין, כולל תוצאות מחוץ לאזור שצוין.
locationRestriction
מציין את האזור לחיפוש. אין תוצאות מחוץ לאזור שצוין הוחזרו.
צריך לציין את האזור
locationBias
אוlocationRestriction
בתור נקודת מבט מלבנית או כעיגול.מעגל מוגדר לפי נקודת המרכז והרדיוס במטרים. הרדיוס חייב להיות בין 0.0 ו-50000.0, כולל. ערך ברירת המחדל הוא 0.0. של
locationRestriction
, חובה להגדיר את הרדיוס לערך גדול מ-0.0. אחרת, הבקשה תחזיר אין תוצאות.לדוגמה:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
מלבן הוא אזור תצוגה של קו רוחב, המיוצג כשני באלכסון מול
low
עם נקודות גבוהות. אזור תצוגה נחשב אזור סגור, כלומר כולל את הגבולות שלו. גבולות קו הרוחב חייב להיות בטווח של 90- עד 90 מעלות כולל, וגבולות קו האורך חייב להיות בטווח של -180 עד 180 מעלות, כולל:- אם
low
=high
, אזור התצוגה מורכב מנקודה אחת בלבד. - אם
low.longitude
>high.longitude
, טווח קו האורך הפוך (אזור התצוגה חוצה את קו האורך 180 מעלות). - אם הערך של
low.longitude
= -180 מעלות ו-high.longitude
= 180 מעלות, אזור התצוגה כולל את כל קווי האורך - אם הטמפרטורה
low.longitude
= 180 מעלות ו-high.longitude
= -180 מעלות, טווח קו האורך ריק.
יש לאכלס גם את
low
וגם אתhigh
, ואת התיבה המיוצגת השדה לא יכול להישאר ריק. אזור תצוגה ריק יגרום לשגיאה.לדוגמה, אזור התצוגה הזה כולל את כל העיר תל אביב:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- אם
-
מקור
נקודת המוצא שממנה יש לחשב את המרחק של הקו הישר היעד (מוחזר כ-
distanceMeters
). אם הערך הזה הוא שהושמט, לא יוחזר מרחק של קו ישר. יש לציין בתור קואורדינטות של קו רוחב וקו אורך:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
קוד האזור שמשמש לעיצוב התשובה, מצוין בתור ccTLD ('דומיין ברמה העליונה') בשני תווים. רוב קודי ה-ccTLD זהים לקודי ISO 3166-1, עם כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא "uk" (.co.uk) כשקוד ISO 3166-1 הוא "gb" (טכנית עבור ישות "בריטניה וצפון אירלנד").
אם מציינים קוד אזור לא תקין, ה-API יחזיר
INVALID_ARGUMENT
שגיאה. הפרמטר יכול להשפיע על התוצאות בהתאם לחוק הרלוונטי. -
sessionToken
אסימוני סשן הם מחרוזות שנוצרו על ידי משתמשים ועוקבות אחרי ההשלמה האוטומטית (חדש) שיחות כ'סשנים'. השלמה אוטומטית (חדש) משתמשת באסימוני הפעלה כדי לקבץ את שלבי השאילתה והבחירה של ההשלמה האוטומטית של החיפוש על ידי המשתמש לסשן נפרד עבור למטרות חיוב. מידע נוסף זמין במאמר הבא: אסימונים של סשן.
דוגמאות להשלמה אוטומטית (חדש)
שימוש בהגבלת מיקום וב-locationBias
ה-API משתמש בהטיה של כתובות IP כברירת מחדל כדי לשלוט באזור החיפוש. עם הטיה של כתובת IP, ה-API משתמש
כתובת ה-IP של המכשיר כדי להטות את התוצאות. אפשר להשתמש גם
locationRestriction
או locationBias
, אבל לא את שניהם, כדי לציין אזור לחיפוש.
locationRestriction
מציין את האזור לחיפוש. תוצאות מחוץ לאזור שצוין
לא מוחזרים. בדוגמה הבאה משתמשים ב-locationRestriction
כדי להגביל את
בקשה למעגל שברדיוס של 5,000 מטר במרכז סן פרנסיסקו:
curl -X POST -d '{ "input": "Amoeba", "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
כל התוצאות מתוך האזורים שצוינו כלולות במערך suggestions
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "store", "point_of_interest", "electronics_store" ] } } ] }
ב-locationBias
, המיקום משמש כהטיה שפירושה תוצאות סביב
מיקום שצוין, כולל תוצאות מחוץ לאזור שצוין. ב
לדוגמה, משנים את הבקשה לשימוש ב-locationBias
:
curl -X POST -d '{ "input": "Amoeba", "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
התוצאות מכילות עכשיו הרבה יותר פריטים, כולל תוצאות מחוץ לרדיוס של 5,000 מטר:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
שימוש ב-includePrimaryTypes
אפשר להשתמש בפרמטר includedPrimaryTypes
כדי לציין עד חמישה סוגי ערכים מ-
טבלה א',
טבלה ב',
או רק (regions)
, או רק (cities)
. מקום חייב להתאים לאחד מהמקומות שצוינו
הערכים של הסוג הראשי שייכללו בתשובה.
בדוגמה הבאה מציינים את המחרוזת input
של
'כדורגל' ולהשתמש בפרמטר includedPrimaryTypes
כדי להגביל את התוצאות ל-
מוסדות מסוג "sporting_goods_store"
:
curl -X POST -d '{ "input": "Soccer", "includedPrimaryTypes": ["sporting_goods_store"], "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
אם משמיטים את הפרמטר includedPrimaryTypes
, התוצאות עשויות לכלול
מוסדות מסוג לא רצויים, כמו "athletic_field"
.
בקשת חיזויים של שאילתות
כברירת מחדל, שאילתות החיפוש החזויות לא מוחזרות. שימוש בincludeQueryPredictions
של הבקשה להוסיף חיזויים של שאילתות לתשובה. לדוגמה:
curl -X POST -d '{ "input": "Amoeba", "includeQueryPredictions": true, "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
המערך suggestions
מכיל עכשיו גם חיזויים של מקומות וגם חיזויים של שאילתות
כמו שאפשר לראות למעלה בקטע מידע על התשובה. כל חיזוי של שאילתה
כוללת את השדה text
שמכיל מחרוזת מומלצת של חיפוש טקסט. אפשר ליצור
חיפוש טקסט (חדש)
בקשה לקבלת מידע נוסף על כל חיזויים של שאילתות שהוחזרו.
שימוש במקור
בדוגמה הזו, יש לכלול את origin
בבקשה כקואורדינטות של קו אורך וקו רוחב.
כשכוללים את origin
, ה-API כולל את השדה distanceMeters
תגובה שמכילה את המרחק של הקו הישר מהorigin
ליעד.
בדוגמה הזו מגדירים את נקודת המוצא כמרכז סן פרנסיסקו:
curl -X POST -d '{ "input": "Amoeba", "origin": { "latitude": 37.7749, "longitude": -122.4194 }, "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
התגובה כוללת עכשיו distanceMeters
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
נסה בעצמך!
API Explorer מאפשר לכם לשלוח בקשות לדוגמה שתכירו את ה-API ואת האפשרויות של ה-API.
- לוחצים על סמל ה-API,
, בצד שמאל של הדף.
- אפשר להרחיב את הקטע הצגת פרמטרים רגילים ולהגדיר
הפרמטר
fields
ל-field mask. - אפשר לערוך את גוף הבקשה.
- לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים להשתמש לשליחת הבקשה.
בחלונית של API Explorer לוחצים על סמל ההרחבה.
, כדי להרחיב את החלון של API Explorer.