אחרי שמקבלים מזהה מקום, אפשר לבקש פרטים נוספים על מוסד מסוים, של נקודת עניין באמצעות פרטי מקום (חדש) בקשה. פרטי מקום (חדש) הבקשה מחזירה מידע מקיף יותר על המקום שצוין כגון הכתובת המלאה, מספר הטלפון, דירוגי המשתמשים והביקורות.
יש הרבה דרכים לקבל מזהה מקום. אתם יכולים להשתמש:
- חיפוש טקסט (חדש) או חיפוש בקרבת מקום (חדש)
- Geocoding API
- Routes API
- API לאימות כתובת
- השלמה אוטומטית למקומות
API Explorer מאפשר לכם לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות API:
רוצים לנסות?בקשות לפרטי מקום (חדש)
בקשה של פרטי מקום היא בקשת HTTP GET בטופס:
https://places.googleapis.com/v1/places/PLACE_ID
העברה של כל הפרמטרים כפרמטרים של כתובות אתרים או בכותרות כחלק בקשת 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
תשובות בנושא פרטי מקום (חדש)
השדה 'פרטי מקום (חדש)' מחזיר אובייקט JSON כתגובה. בתשובה:
- התגובה מיוצגת על ידי
Place
לאובייקט. האובייקטPlace
מכיל מידע מפורט על במקום. - השדה FieldMask מועבר בבקשה מציין את רשימת השדות
שהוחזר באובייקט
Place
.
אובייקט ה-JSON המלא מופיע בתבנית:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
פרמטרים נדרשים
-
FieldMask
כדי לציין את רשימת השדות שיוחזרו בתשובה, צריך ליצור response field mask. מעבירים את אנונימיזציה של שדות התגובה ל-method באמצעות הפרמטר של כתובת האתר
$fields
אוfields
, או באמצעות כותרת ה-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
,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
תגובה:
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
- אפשר להרחיב את הקטע הצגת פרמטרים רגילים ולהגדיר
הפרמטר
fields
ל-field mask. - לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שרוצים שבהם נעשה שימוש כדי לשלוח את הבקשה.
בחלונית של API Explorer לוחצים על סמל ההרחבה.
, כדי להרחיב את החלון של API Explorer.