מזהי מקומות

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

המזהה הייחודי של מקום במסד הנתונים של כתובות ב-Google ובמפות Google. מזהי מקומות מאושרות בבקשות לממשקי ה-API הבאים של מפות Google:

  • אחזור כתובת למזהה מקום בשירות האינטרנט Geocoding API שירות המרת כתובות לקואורדינטות (geocoding) , Maps JavaScript API.
  • ציון נקודות מוצא, יעד וציוני דרך ברמת הביניים Routes API ו-Directions API שירות אינטרנט ו-Directions Service (שירות מסלולים), Maps JavaScript API.
  • ציון מקורות ויעדים ב-Routes API וגם שירות האינטרנט של Distance Matrix API וגם שירות מטריצת מרחק, Maps JavaScript API.
  • אחזור פרטי מקום בשירות האינטרנט של Places API, SDK של מקומות ל-Android, SDK של מקומות ל-iOS וספריית מקומות.
  • שימוש בפרמטרים של מזהה מקום ב-Maps Embed API.
  • אחזור שאילתות חיפוש בכתובות URL של מפות Google.
  • הצגת מגבלות מהירות ב-Roads API.
  • איתור ועיצוב של פוליגונים של גבולות בסגנון מבוסס-נתונים לצורך קביעת גבולות.

איך למצוא את המזהה של מקום ספציפי

רוצה למצוא את מזהה המקום של מקום ספציפי? שימוש במזהה המקום כדי לחפש מקום ולקבל את המזהה שלו:

לחלופין, אפשר צפייה מאתר מזהי המקומות באמצעות הקוד שלו ב-Maps JavaScript API. התיעוד.

סקירה כללית

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

  • ChIJgUbEo8cfqokR5lP9_Wh_DaM
  • GhIJQWDl0CIeQUARxks3icF8U8A
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
  • IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

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

אפשר להשתמש באותו מזהה מקום ב-Places API וב מספר ממשקי ה-API של הפלטפורמה של מפות Google. לדוגמה, אפשר להשתמש באותו מזהה מקום כדי להתייחס למקום Places API, API JavaScript של מפות Google, Geocoding API, API להטמעה של מפות Google ואת Roads API.

אחזור פרטי מקום באמצעות מזהה המקום

אחת הדרכים הנפוצות לשימוש במזהי מקומות היא לחפש מקום (באמצעות Places API) או מקומות ב-Maps JavaScript API, למשל). החזירו מזהה מקום כדי לאחזר את פרטי המקום. אפשר לשמור את מזהה המקום להשתמש בו כדי לאחזר את אותם פרטי מקום מאוחר יותר. מידע על לשמירה של מזהי המקומות שבהמשך.

הדוגמאות הבאות מראות איך לבקש כתובת URL של סמל עבור Places API (חדש) וגם Places API.

Places API (חדש)

בעזרת Places API אפשר למצוא מזהה מקום חיפוש טקסט (חדש) בקשה.

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

התגובה כוללת מזהה מקום בשדה id, כפי שמוצג בהמשך:

{
  "places": [
    {
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
  ...
}

עכשיו אפשר ליצור פרטי מקום (חדש) על ידי הכללת מזהה המקום בכתובת ה-URL של הבקשה:

https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY

Places API

בעזרת Places API אפשר למצוא מזהה מקום בקשת חיפוש מקום.

הדוגמה הבאה היא בקשת חיפוש מקומות מסוג 'מסעדה' ברדיוס של 1,500 מטר מנקודה בסידני, אוסטרליה, המכילה את המילה 'cruise':

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

התגובה כוללת מזהה מקום בשדה place_id, כך: שמוצגת בקטע הקוד הזה:

{
  "html_attributions" : [],
  "results" : [
    {
      "geometry" : {
        "location" : {
          "lat" : -33.870775,
          "lng" : 151.199025
        }
      },
      ...
      "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
      ...
    }
  ],
  "status" : "OK"
}

עכשיו אפשר לשלוח בקשה לפרטי מקום, הוספת מזהה המקום בפרמטר place_id:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEY

שמירת מזהי מקומות לשימוש במועד מאוחר יותר

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

רענון של מזהי מקומות שמורים

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

Places API (חדש)

לדוגמה, שימוש בפרטי מקום (חדש):

https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY

Places API

לדוגמה, באמצעות ה-API הקודם של Place Details: 

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY

השיחה הזו מפעילה את פרטי מקום חדשים (מזהים בלבד) או פרטי מקומות – רענון מזהה מק"ט.

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

קודי שגיאה לשימוש במזהי מקומות

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

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

באופן ספציפי, סוגים מסוימים של מזהי מקומות עלולים לגרום תשובה NOT_FOUND, או שה-API עשוי להחזיר מזהה מקום אחר את התשובה. דוגמאות למזהי מקומות:

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

המזהים האלה בדרך כלל מופיעים כמחרוזת ארוכה (אין אורך מקסימלי למזהי מקומות). לדוגמה:

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4