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

מבוא

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

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

• חיפוש טקסט (חדש) או חיפוש בסביבה (חדש)
• Geocoding API
• Routes API
• ‫Address Validation API
• השלמה אוטומטית (חדש)

‫APIs Explorer מאפשר לכם לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת האפשרויות שלו:

בקשות Place Details (New)

בקשה של פרטי מקום (חדש) היא בקשת 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

  כדי לציין את רשימת השדות שיוחזרו בתגובה, יוצרים מסכת שדות של תגובה. מעבירים את מסכת שדות התגובה לשיטה באמצעות פרמטר כתובת ה-URL‏ $fields או fields, או באמצעות כותרת ה-HTTP‏ X-Goog-FieldMask. אין רשימת ברירת מחדל של שדות שמוחזרים בתגובה. אם לא מציינים את מסכת השדה, השיטה מחזירה שגיאה.

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

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

  X-Goog-FieldMask: displayName,formattedAddress

  כדי לאחזר את כל השדות, משתמשים ב-*.

  ‫

  X-Goog-FieldMask: *

  מציינים אחד או יותר מהשדות הבאים:

  • השדות הבאים מפעילים את מזהה המק"ט Place Details Essentials IDs Only:

    attributions
id
name^*
    photos
    

    ‫^* השדה name מכיל את שם המשאב של המקום בפורמט: places/PLACE_ID. כדי לקבל את שם המקום בטקסט, צריך לבקש את השדה displayName במק"ט Pro.

  • השדות הבאים מפעילים את מק"ט Place Details Essentials:

    addressComponents
addressDescriptor^*
    adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
    
    ^* תיאורי כתובות זמינים בדרך כלל ללקוחות בהודו, ובמקומות אחרים הם בשלב ניסיוני.
    
    

  • השדות הבאים מפעילים את מזהה המק"ט של Place Details Pro:

    accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
utcOffsetMinutes
    
    

  • השדות הבאים מפעילים את מזהה המק"ט של Place Details Enterprise:

    currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
userRatingCount
websiteUri

  • השדות הבאים מפעילים את מזהה המק"ט של Place Details Enterprise + Atmosphere:

    allowsDogs
curbsidePickup
delivery
dineIn
editorialSummary
evChargeAmenitySummary
evChargeOptions
fuelOptions
generativeSummary
goodForChildren
goodForGroups
goodForWatchingSports
liveMusic
menuForChildren
neighborhoodSummary
parkingOptions
paymentOptions
outdoorSeating
reservable
restroom
reviews
reviewSummary
routingSummaries^*
    servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
    
    ^* חיפוש טקסט וחיפוש בקרבת מקום בלבד

• placeId

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

  המחרוזת places/PLACE_ID נקראת גם שם המשאב של המקום. בתשובה לבקשה של Place Details (New),‏ Nearby Search (New) ו-Text Search (New), המחרוזת הזו מופיעה בשדה 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

  אסימוני סשן הם מחרוזות שנוצרות על ידי המשתמש ועוקבות אחרי קריאות ל'השלמה אוטומטית (חדשה)' כ'סשנים'. ההשלמה האוטומטית (חדש) משתמשת באסימוני סשן כדי לקבץ את שאילתת החיפוש ואת שלבי הבחירה של חיפוש השלמה אוטומטית של משתמש בסשן נפרד למטרות חיוב. טוקנים של סשנים מועברים לקריאות של Place Details (New) אחרי קריאות של Autocomplete (New). מידע נוסף זמין במאמר בנושא אסימוני סשן.

דוגמה ל-Place Details (חדש)

בדוגמה הבאה מוצגת בקשה לקבלת פרטים על מקום מסוים באמצעות 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 כדי לכלול את הכתובת ואת קוד ה-OLC בתגובה:

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"
  }
}

קבלת תיאורים של כתובות

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

בדוגמה הבאה מוצגת בקשה של Place Details (New) לגבי חנות כלבו בקניון בסן חוזה. בדוגמה הזו, כוללים את addressDescriptors במסכת השדה:

  curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  -H "X-Goog-FieldMask: name,displayName,addressDescriptor"

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

  {
    "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
    "displayName": {
      "text": "Macy's",
      "languageCode": "en"
    },
    "addressDescriptor": {
      "landmarks": [
        {
          "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "food",
            "movie_theater",
            "point_of_interest",
            "restaurant",
            "shoe_store",
            "shopping_mall",
            "store"
          ],
          "spatialRelationship": "WITHIN",
          "straightLineDistanceMeters": 220.29175
        },
        {
          "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
          "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
          "displayName": {
            "text": "Nordstrom",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "point_of_interest",
            "shoe_store",
            "store"
          ],
          "straightLineDistanceMeters": 329.45178
        },
        {
          "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "displayName": {
            "text": "Monroe Parking Garage",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "parking",
            "point_of_interest"
          ],
          "straightLineDistanceMeters": 227.05153
        },
        {
          "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "displayName": {
            "text": "Studios Inn by Daiwa Living California Inc.",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "lodging",
            "point_of_interest",
            "real_estate_agency"
          ],
          "straightLineDistanceMeters": 299.9955
        },
        {
          "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "displayName": {
            "text": "Din Tai Fung",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "food",
            "point_of_interest",
            "restaurant"
          ],
          "straightLineDistanceMeters": 157.70943
        }
      ],
      "areas": [
        {
          "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
          "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        },
        {
          "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
          "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
          "displayName": {
            "text": "Valley Fair",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        },
        {
          "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
          "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
          "displayName": {
            "text": "Central San Jose",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        }
      ]
    }
  }

רוצה לנסות?

באמצעות APIs Explorer אפשר לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת האפשרויות שלו.

1. לוחצים על סמל ה-API api בצד שמאל של הדף.

2. אפשר לערוך את פרמטרים הבקשה.

3. לוחצים על הלחצן Execute (הפעלה). בתיבת הדו-שיח, בוחרים את החשבון שרוצים להשתמש בו כדי לשלוח את הבקשה.

4. בחלונית APIs Explorer, בוחרים בסמל המסך המלא מסך מלא כדי להרחיב את החלון של APIs Explorer.