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

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

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

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

• חיפוש טקסט (חדש) או חיפוש בקרבת מקום (חדש)
• Geocoding API
• Routes API
• API לאימות כתובת
• השלמה אוטומטית למקומות

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

רוצים לנסות?

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

בקשה של פרטי מקום היא בקשת HTTP GET בטופס:

https://places.googleapis.com/v1/places/PLACE_ID

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

תשובות בנושא פרטי מקום (חדש)

השדה 'פרטי מקום (חדש)' מחזיר אובייקט JSON כתגובה. בתשובה:

• התגובה מיוצגת על ידי Place לאובייקט. האובייקט Place מכיל מידע מפורט על במקום.
• השדה FieldMask מועבר בבקשה מציין את רשימת השדות שהוחזר באובייקט Place.

אובייקט ה-JSON המלא מופיע בתבנית:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "displayName": {
    "text": "Trinidad"
  }
  ...
}

פרמטרים נדרשים

• FieldMask

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

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

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

  X-Goog-FieldMask: displayName,formattedAddress

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

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

  X-Goog-FieldMask: *

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

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

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

    attributions, 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, servesBeer, servesBreakfast, servesBrunch, servesCocktails, servesCoffee, servesDessert, servesDinner, servesLunch, servesVegetarianFood, servesWine, takeout
    

• placeId

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

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

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

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

• 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 Explorer מאפשר לכם לשלוח בקשות לדוגמה שתכירו את ה-API ואת האפשרויות של ה-API.

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

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

   places/PLACE_ID

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

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