אחרי שמקבלים מזהה מקום, אפשר לבקש פרטים נוספים על מוסד או נקודת עניין מסוימים על ידי שליחת בקשה לפרטי מקום (חדש). בקשה לפרטי מקום (חדש) מחזירה מידע מקיף יותר על המקום שצוין, כמו הכתובת המלאה, מספר הטלפון, דירוג המשתמשים וביקורות.
יש הרבה דרכים לקבל מזהה מקום. אתם יכולים להשתמש:
- חיפוש טקסט (חדש) או חיפוש בקרבת מקום (חדש)
- Geocoding API
- Routes API
- Address Validation 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 (חדש) מחזיר אובייקט JSON כתגובה. בתשובה:
- התגובה מיוצגת על ידי אובייקט
Place
. האובייקטPlace
מכיל מידע מפורט על המקום. - השדה FieldMask שהועבר בבקשה מציין את רשימת השדות
שהוחזרו באובייקט
Place
.
אובייקט ה-JSON המלא מופיע בצורה הבאה:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
פרמטרים נדרשים
-
FieldMask
כדי לציין את רשימת השדות שיוחזרו בתגובה, יוצרים אנונימיזציה של שדות התשובה. מעבירים את המסכה של שדה התגובה לשיטה באמצעות הפרמטר של כתובת האתר
$fields
אוfields
, או באמצעות כותרת ה-HTTPX-Goog-FieldMask
. אין בתשובה רשימת ברירת מחדל של שדות שהוחזרו. אם משמיטים את מסכת השדות, השיטה מחזירה שגיאה.מומלץ לבצע אנונימיזציה של שדות כדי שלא תבקשו נתונים מיותרים, וכך להימנע מזמן עיבוד ומחיובים מיותרים.
מציינים רשימה מופרדת בפסיקים של סוגי נתוני מקומות שיש להחזיר. לדוגמה, כדי לאחזר את השם המוצג ואת הכתובת של המקום.
X-Goog-FieldMask: displayName,formattedAddress
כדי לאחזר את כל השדות, צריך להשתמש בפונקציה
*
.X-Goog-FieldMask: *
צריך לציין אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את המק"ט של פרטי מקום (מזהים בלבד):
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
,liveMusic
servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDesserts
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 בתשובה:
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 ואת האפשרויות של API.
כדי לשלוח בקשה:
- לוחצים על סמל ה-API בצד שמאל של הדף.
- אפשר להגדיר את הפרמטר
name
כ-:places/PLACE_ID
- אפשר להרחיב את האפשרות הצג פרמטרים סטנדרטיים ולהגדיר את הפרמטר
fields
כאנונימיזציה של שדות. - לוחצים על הלחצן ביצוע. בחלון הקופץ, בוחרים את החשבון שבאמצעותו רוצים לשלוח את הבקשה.
בחלונית של API Explorer לוחצים על סמל ההרחבה, , כדי להרחיב את החלון של API Explorer.