מזהי מקומות

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

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

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

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

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

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

סקירה כללית

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

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

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

אפשר להשתמש באותו מזהה מקום ב-Places API ובמספר ממשקי API של הפלטפורמה של מפות Google. לדוגמה, אפשר להשתמש באותו מזהה מקום כדי להפנות למקום ב-Places API, ב-Maps JavaScript API, ב-Geocoding API, ב-Maps Implement API וב-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 מטר מנקודה בסידני, אוסטרליה, והיא מכילה את המילה 'שייט':

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. אחת השיטות היא לאחסן את הבקשה המקורית שהחזירה כל מזהה מקום. אם מזהה מקום הופך ללא תקף, אפשר לשלוח את הבקשה מחדש כדי לקבל תוצאות עדכניות. התוצאות האלה לא תמיד כוללות את המקום המקורי. עם זאת, הבקשה הזו כרוכה בחיוב.

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

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

קוד הסטטוס NOT_FOUND מציין שמזהה המקום שצוין מיושן. אם עסק נסגר או עובר למיקום חדש, מזהה מקום עשוי להפוך למיושן. מזהי המקומות עשויים להשתנות עקב עדכונים בכמות גדולה במסד הנתונים של מפות 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