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

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

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

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

ב-API Explorer אפשר לשלוח בקשות בזמן אמת כדי להכיר את ה-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" (טכנית, הישות היא ‎"The United Kingdom of Great Britain and Northern Ireland"). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

  • 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 כדי לכלול את הכתובת ואת קוד ה-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"
  }
}

נסה בעצמך!

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

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

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

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