פרטי מקום (חדש)

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

אחרי שיש לכם מזהה מקום, אתם יכולים לבקש פרטים נוספים על מוסד או נקודת עניין ספציפיים על ידי שליחת בקשה לפרטי מקום (חדש). כשמבקשים את פרטי המקום (חדש) מקבלים מידע מקיף יותר על המקום שצוין, כמו הכתובת המלאה, מספר הטלפון, דירוג המשתמשים והביקורות שלו.

יש הרבה דרכים לקבל מזהה מקום. אתם יכולים להשתמש:

באמצעות 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, או באמצעות כותרת ה-HTTP X-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, reviews, reviews, reviewsservesBeerservesBreakfastservesBrunchservesCocktailsservesCoffeeservesDessertsservesDinnerservesLunchservesVegetarianFoodservesWinetakeout

  • 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.

כדי לשלוח בקשה:

  1. בצד שמאל של הדף, בוחרים בסמל ה-API מרחיבים את API Explorer..
  2. אפשר להגדיר את הפרמטר name לערך: 
    places/PLACE_ID
  3. אפשר להרחיב את הקטע Show advanced parameters ולהגדיר את הפרמטר fields ל-field mask.
  4. לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים לשלוח את הבקשה.

  5. בחלונית של API Explorer, לוחצים על סמל ההרחבה מרחיבים את API Explorer. כדי להרחיב את חלון ה-API Explorer.