מדריך מקוצר ל-Places API (חדש)

‫Places API (החדש) הוא שירות אינטרנט שמחזיר נתוני מיקום בפורמט JSON לגבי בתי עסק, מיקומים גיאוגרפיים ונקודות עניין. הוא תומך בחיפוש טקסט (חדש), בחיפוש בסביבה (חדש), בהשלמה אוטומטית (חדש), ב-Place Details (חדש) וב-Place Photos (חדש).

‫Places API (חדש): עובדות חשובות

  • מוצר: Places API (חדש)
  • נקרא גם: Places API
  • קטגוריה: מקומות
  • פלטפורמה: שירות אינטרנט (REST)
  • פועל ב: שרת (קוד לקצה העורפי)
  • שלב ההשקה: GA
  • מחזור חיים: פעיל
  • סקירה כללית: סקירה כללית על Places API (חדש)
  • זמינות אזורית: גלובלית. בפרויקטים עם כתובות לחיוב ב-EEA, חלים התנאים וההגבלות של Google Maps Platform ל-EEA (החל מ-8 ביולי 2025). לפי התנאים האלה, אי אפשר להשתמש בתוכן של Places API, מלבד קווי רוחב, קווי אורך ומזהי מקומות, באף מפה, אלא באמצעות Places UI Kit. סיכומי מקומות, ביקורות ואזורים מבוססי-AI זמינים רק בשפות ובאזורים נתמכים.

‫Places API (חדש): מתי כדאי להשתמש בו

מתי כדאי להשתמש ב-Places API (חדש):

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

מתי לא כדאי להשתמש ב-Places API (החדש):

  • אתם מפתחים אפליקציה מקורית ל-Android. במקום זאת, השתמשו ב-Places SDK ל-Android.
  • אתם מפתחים אפליקציה מקורית ל-iOS. במקום זאת, השתמשו ב-Places SDK ל-iOS.
  • אתם מפתחים אפליקציית אינטרנט לדפדפן ורוצים לטעון את ספריית המקומות ב-JavaScript. במקום זאת, צריך להשתמש ב-Maps JavaScript API.

‫Places API (חדש): הגדרה

חבילות רשמיות של Places API (חדש):

  • ‫npm: ‏@googlemaps/places
  • pypi: google-maps-places
  • go:‏ cloud.google.com/go/maps

‫Places API (חדש): טעויות נפוצות

  • הבעיה: ל-Place Details (חדש), לחיפוש בסביבה (חדש) ולחיפוש טקסט (חדש) אין רשימת ברירת מחדל של שדות שמוחזרים. בקשות בלי מסכת שדות מחזירות שגיאה. הפתרון: מעבירים מסכת שדות תגובה עם הפרמטר fields או $fields, או עם הכותרת X-Goog-FieldMask. מידע נוסף זמין בכתובת /maps/documentation/places/web-service/choose-fields.
  • הבעיה: אם משמיטים את הטוקן לסשן של ההשלמה האוטומטית (חדש) או משתמשים בו שוב אחרי שהסשן מסתיים, כל בקשה מחויבת בנפרד לפי המק"ט: Autocomplete Requests. הפתרון: יוצרים טוקן לסשן חדש (מומלץ להשתמש ב-UUID v4) לכל סשן, ומסיימים אותו בבקשה ל-Place Details (New) או ל-Address Validation. מידע נוסף זמין בכתובת /maps/documentation/places/web-service/place-session-tokens.
  • הבעיה: קוד קיים או קוד שנוצר על ידי AI שולח קריאה ל-Places API (דור קודם) או ל-Maps JavaScript API PlacesService בפרויקט שבו ה-API הקודם לא מופעל, והקריאה נכשלת עם השגיאה LegacyApiNotActivatedMapError. הפתרון: מעבירים את הקריאות ל-Places API (החדש) וכוללים את מסכת השדות הנדרשת. מידע נוסף זמין בכתובת /maps/legacy#LegacyApiNotActivatedMapError.
  • הבעיה: מזהי מקומות ששמורים במערכת יכולים להתיישן. במקרה כזה, Place Details (חדש) מחזיר את הערך NOT_FOUND (HTTP 404), ומזהים קטועים או בפורמט שגוי מחזירים את הערך HTTP 400 INVALID_ARGUMENT. תיקון: מרעננים את מזהי המקומות ששמורים יותר מ-12 חודשים באמצעות בקשה ל-Place Details (חדש) שכוללת רק את השדה id (ללא חיוב). מידע נוסף זמין בכתובת /maps/documentation/places/web-service/place-id#refresh-id.

מה אפשר לעשות עם Places API (חדש)

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

‫Places API (חדש): בינה מלאכותית גנרטיבית

‫Places API (חדש): מקומות