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

בחירת פלטפורמה: Android iOS JavaScript Web Service

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

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

באמצעות API Explorer תוכלו ליצור בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות ה-API:

רוצים לנסות?

בקשות של Place Details (חדש)

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

הקריאה Place Details (חדש) מחזירה אובייקט 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: *

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

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

      attributions, id, name*, photos

      * השדה name מכיל את שם המשאב של המקום בפורמט: places/PLACE_ID. משתמשים ב-displayName כדי לגשת לשם הטקסט של המקום.

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

      addressComponents, adrFormatAddress, formattedAddress, location, plusCode, shortFormattedAddress, types, viewport

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

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

      * השדה googleMapsLinks נמצא בשלב התצוגה המקדימה לפני GA, ואין חיוב על השימוש במהלך התצוגה המקדימה, כלומר החיוב הוא 0$.

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

      currentOpeningHours, currentSecondaryOpeningHours, internationalPhoneNumber, nationalPhoneNumber, priceLevel, priceRange, rating, regularOpeningHours, regularSecondaryOpeningHours, userRatingCount, websiteUri

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

      allowsDogs, curbsidePickup, delivery, dineIn, editorialSummary, evChargeOptions, fuelOptions, goodForChildren, goodForGroups, goodForWatchingSports, liveMusic, menuForChildren, parkingOptions, paymentOptions, outdoorSeating, reservable, restroom, reviews, routingSummaries,* 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 בוחר להחזיר ועל הסדר שבו הן מוחזרות. המערכת למיפוי גיאוגרפי מפענחת קיצורים באופן שונה בהתאם לשפה, למשל קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת.

  • regionCode

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

    אם שם המדינה בשדה formattedAddress בתגובה תואם ל-regionCode, קידומת המדינה לא תופיע ב-formattedAddress. הפרמטר הזה לא משפיע על adrFormatAddress, שתמיד כולל את שם המדינה, או על shortFormattedAddress, שמעולם לא כולל אותו.

    רוב קודי CLDR זהים לקודי ISO 3166-1, מלבד כמה חריגים בולטים. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא ‎"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 ובאפשרויות שלו.

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

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

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