אחרי שיש לכם מזהה מקום, אתם יכולים לבקש פרטים נוספים על מוסד או נקודת עניין ספציפיים על ידי שליחת בקשה לפרטי מקום (חדש). כשמבקשים את פרטי המקום (חדש) מקבלים מידע מקיף יותר על המקום שצוין, כמו הכתובת המלאה, מספר הטלפון, דירוג המשתמשים והביקורות שלו.
יש הרבה דרכים לקבל מזהה מקום. אתם יכולים להשתמש:
- חיפוש טקסט (חדש) או חיפוש בקרבת מקום (חדש)
- Geocoding API
- Routes API
- API לאימות כתובת
- השלמה אוטומטית למקומות
באמצעות API Explorer תוכלו ליצור בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות ה-API:
רוצים לנסות?בקשות לפרטי מקום (חדש)
בקשה של פרטי מקום היא בקשת HTTP GET בטופס:
https://places.googleapis.com/v1/places/PLACE_ID
מעבירים את כל הפרמטרים כפרמטרים של כתובות URL או ככותרות כחלק מבקשת ה-GET. למשל:
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY
או בפקודת cURL:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
תשובות בנושא פרטי מקום (חדש)
Place Details (New) מחזירה אובייקט JSON כתגובה. בתשובה:
- התגובה מיוצגת על ידי אובייקט
Place
. האובייקטPlace
מכיל מידע מפורט על המקום. - השדה FieldMask שמועבר בבקשה מציין את רשימת השדות שמוחזרים באובייקט
Place
.
אובייקט ה-JSON המלא מופיע בתבנית:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
פרמטרים נדרשים
-
FieldMask
מציינים את רשימת השדות שיוחזרו בתשובה על ידי יצירת אנונימיזציה של שדות בתשובה. מעבירים את המסכה של שדות התשובה ל-method באמצעות הפרמטר
$fields
אוfields
של כתובת ה-URL, או באמצעות כותרת ה-HTTPX-Goog-FieldMask
. אין רשימת ברירת מחדל של השדות שהוחזרו בתשובה. אם משמיטים את מסיכת השדות, השיטה מחזירה שגיאה.כדאי לבצע אנונימיזציה של שדות כדי לוודא שלא מבקשים נתונים מיותרים, וכך חוסכים זמן עיבוד וחיובים מיותרים.
מציינים רשימה מופרדת בפסיקים של סוגי נתוני המקומות שרוצים להחזיר. לדוגמה, כדי לאחזר את השם המוצג ואת הכתובת של המקום.
X-Goog-FieldMask: displayName,formattedAddress
אפשר להשתמש ב-
*
כדי לאחזר את כל השדות.X-Goog-FieldMask: *
צריך לציין אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את המק"ט של פרטי המקום (מזהים בלבד):
attributions
,id
,name
*,photos
* השדהname
מכיל את שם המשאב בפורמט הבא:places/PLACE_ID
. משתמשים ב-displayName
כדי לגשת לשם הטקסט של המקום.השדות הבאים מפעילים את המק"ט של פרטי המקום (מיקום בלבד):
addressComponents
,adrFormatAddress
,formattedAddress
,location
,plusCode
,shortFormattedAddress
,types
,viewport
השדות הבאים מפעילים את המק"ט של פרטי המקום (בסיסי):
accessibilityOptions
,businessStatus
,displayName
,googleMapsUri
,iconBackgroundColor
,iconMaskBaseUri
,primaryType
,primaryTypeDisplayName
,subDestinations
,utcOffsetMinutes
השדות הבאים מפעילים את המק"ט של פרטי המקום (מתקדם):
currentOpeningHours
,currentSecondaryOpeningHours
,internationalPhoneNumber
,nationalPhoneNumber
,priceLevel
,rating
,regularOpeningHours
,regularSecondaryOpeningHours
,userRatingCount
,websiteUri
השדות הבאים מפעילים את המק"ט של פרטי המקום (מועדף):
allowsDogs
,curbsidePickup
,delivery
,dineIn
,editorialSummary
,evChargeOptions
,fuelOptions
,goodForChildren
,goodForGroups
,goodForWatchingSports
,liveMusic
,menuForChildren
,parkingOptions
,paymentOptions
,outdoorSeating
,reservable
,restroom
,reviews
,reviews
,reviews
,reviews
servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
-
placeId
מזהה טקסטואלי שמזהה מקום באופן ייחודי, שהוחזר באמצעות חיפוש טקסט (חדש) או חיפוש בקרבת מקום (חדש). למידע נוסף על מזהי מקומות, ראו סקירה כללית על מזהי מקומות.
המחרוזת
places/PLACE_ID
נקראת גם שם המשאב של המקום. בתשובה מבקשה של 'פרטי מקום' (חדש), 'חיפוש בקרבת מקום' (חדש) ו'חיפוש טקסט (חדש)', המחרוזת הזו תיכלל בשדהname
של התשובה. מזהה המקום העצמאי מופיע בשדהid
של התשובה.
פרמטרים אופציונליים
languageCode
השפה שבה יוחזרו תוצאות.
- לרשימת השפות הנתמכות Google מעדכנת את השפות הנתמכות לעיתים קרובות, ולכן יכול להיות שזו רשימה חלקית בלבד.
-
אם לא מזינים
languageCode
, ברירת המחדל של ה-API היאen
. אם מציינים קוד שפה לא תקין, ה-API יחזיר שגיאתINVALID_ARGUMENT
. - ממשק ה-API עושה כמיטב יכולתו כדי לספק כתובת רחוב שניתנת לקריאה גם למשתמשים וגם לתושבים המקומיים. כדי להשיג את המטרה הזו, המערכת מחזירה כתובות של רחובות בשפה המקומית, מתועתקות לסקריפט שהמשתמש יכול לקרוא במקרה הצורך, תוך שמירה על השפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרה מהרכיב הראשון.
- אם שם מסוים לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.
- לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שה-API בוחר להחזיר, ועל הסדר שבו הן מוחזרות. הקואורדינטות מפרשות קיצורים באופן שונה בהתאם לשפה, כמו הקיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת.
regionCode
קוד האזור שמשמש לעיצוב התשובה, מוגדר כערך של קוד CLDR בן שני תווים. אין ערך ברירת מחדל.
אם שם המדינה בשדה
formattedAddress
בתשובה תואם ל-regionCode
, קוד המדינה לא יופיע ב-formattedAddress
. לפרמטר הזה אין השפעה עלadrFormatAddress
, שתמיד כולל את שם המדינה, או עלshortFormattedAddress
, שהוא אף פעם לא כולל אותו.רוב קודי ה-CLDR זהים לקודי ISO 3166-1, עם כמה יוצאים מן הכלל. לדוגמה, הדומיין ccTLD של בריטניה הוא 'uk' (.co.uk) ואילו קוד ISO 3166-1 הוא 'gb' (טכנית לישות 'בריטניה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לחוק הרלוונטי.
-
sessionToken
אסימוני סשן הם מחרוזות שנוצרות על ידי משתמשים ועוקבות אחרי הפעלות של השלמה אוטומטית (חדש) בתור 'סשנים'. השלמה אוטומטית (חדש) משתמשת באסימוני סשן כדי לקבץ את שלבי השאילתה ואת שלבי הבחירה של החיפוש בהשלמה האוטומטית של המשתמש לסשן נפרד למטרות חיוב. אסימוני הסשן מועברים לקריאות של פרטי המקום (חדש) שמגיעות לאחר הפעלות של השלמה אוטומטית (חדש). מידע נוסף זמין במאמר אסימונים של סשן.
דוגמה לפרטי מקום
בדוגמה הבאה מוצגת בקשה לפרטים של מקום לפי placeId
:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
שימו לב שהכותרת X-Goog-FieldMask
מציינת שהתגובה מכילה את שדות הנתונים הבאים: id,displayName
.
לאחר מכן, התגובה תהיה בצורת:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" } }
כדי להחזיר מידע נוסף, צריך להוסיף עוד סוגי נתונים למסכת השדות.
לדוגמה, מוסיפים את formattedAddress,plusCode
כדי לכלול את הכתובת ואת Plus Code ב-response:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
עכשיו התגובה תופיע בפורמט:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "plusCode": { "globalCode": "849VCWC7+RW", "compoundCode": "CWC7+RW Mountain View, CA, USA" }, "displayName": { "text": "Googleplex", "languageCode": "en" } }
רוצה לנסות?
באמצעות API Explorer תוכלו לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת אפשרויות ה-API.
כדי לשלוח בקשה:
- בצד שמאל של הדף, בוחרים בסמל ה-API .
- אפשר להגדיר את הפרמטר
name
לערך:places/PLACE_ID
- אפשר להרחיב את הקטע Show advanced parameters ולהגדיר את הפרמטר
fields
ל-field mask. - לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים לשלוח את הבקשה.
בחלונית של API Explorer, לוחצים על סמל ההרחבה כדי להרחיב את חלון ה-API Explorer.