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

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

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

• חיפוש טקסט (חדש) או חיפוש בקרבת מקום (חדש)
• 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, או באמצעות כותרת ה-HTTP X-Goog-FieldMask. אין בתשובה רשימת ברירת מחדל של שדות שהוחזרו. אם משמיטים את מסכת השדות, השיטה מחזירה שגיאה.

  מומלץ לבצע אנונימיזציה של שדות כדי שלא תבקשו נתונים מיותרים, וכך להימנע מזמן עיבוד ומחיובים מיותרים.

  מציינים רשימה מופרדת בפסיקים של סוגי נתוני מקומות שיש להחזיר. לדוגמה, כדי לאחזר את השם המוצג ואת הכתובת של המקום.

  X-Goog-FieldMask: displayName,formattedAddress

  הערה: אסור להשתמש ברווחים באף מקום ברשימת השדות.

  כדי לאחזר את כל השדות, צריך להשתמש בפונקציה *.

  X-Goog-FieldMask: *

  התו הכללי לחיפוש '*' בוחר את כל השדות. עם זאת, למרות שמותר להשתמש בתו הכללי הזה בפיתוח, Google לא ממליצה להשתמש במסכה של שדה התגובה עם התו הכללי לחיפוש (*) בסביבת הייצור, בגלל הכמות הגדולה של הנתונים שאפשר להחזיר.
  הנחיות נוספות לשימוש ב-iconMaskBaseUri וב-iconBackgroundColor זמינות בקטע סמלי מקומות.

  צריך לציין אחד או יותר מהשדות הבאים:

  • השדות הבאים מפעילים את המק"ט של פרטי מקום (מזהים בלבד):

    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, liveMusicservesBeerservesBreakfastservesBrunchservesCocktailsservesCoffeeservesDessertsservesDinnerservesLunchservesVegetarianFoodservesWinetakeout
    

• placeId

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

  המחרוזת places/PLACE_ID נקראת גם שם המשאב של המקום. בתגובה מבקשה של פרטי מקום (חדש), חיפוש בקרבת מקום (חדש) וחיפוש טקסט (חדש), המחרוזת הזו כלולה בשדה name של התשובה. מזהה המקום העצמאי נמצא בשדה id של התשובה.

  הערה: בשדה הקיים פרטי מקום, בשדה name של התשובה נכלל שם המקום שקריא לבני-אדם. השדה הזה נקרא עכשיו displayName בממשק ה-API החדש.

פרמטרים אופציונליים

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

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

1. לוחצים על סמל ה-API בצד שמאל של הדף.
2. אפשר להגדיר את הפרמטר name כ-:

   places/PLACE_ID

3. אפשר להרחיב את האפשרות הצג פרמטרים סטנדרטיים ולהגדיר את הפרמטר fields כאנונימיזציה של שדות.
4. לוחצים על הלחצן ביצוע. בחלון הקופץ, בוחרים את החשבון שבאמצעותו רוצים לשלוח את הבקשה.

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