‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

חיפוש טקסט (חדש)

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

מפתחים באזור הכלכלי האירופי (EEA)

מבוא

חיפוש טקסט (חדש) מחזירה מידע על קבוצה של מקומות על סמך מחרוזת (לדוגמה, ‫"pizza in New York" או "shoe stores near Ottawa" או "123 Main Street"). השירות מגיב עם רשימת מקומות שתואמים למחרוזת הטקסט ולכל הטיה של מיקום שהוגדרה.

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

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

כדאי לנסות!

בקשות לחיפוש טקסט (חדש)

בקשה לחיפוש טקסט (חדש) היא בקשת HTTP POST מהצורה הבאה:

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

מעבירים את כל הפרמטרים בגוף בקשת ה-JSON או בכותרות כחלק מבקשת ה-POST. לדוגמה:

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.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

תשובות של חיפוש טקסט (חדש)

התגובה של חיפוש טקסט (חדש) היא אובייקט JSON. בתשובה:

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

אובייקט ה-JSON המלא הוא מהצורה:

{
  "places": [
    {
      object (Place)
    }
  ]
}

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

FieldMask

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

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

מציינים רשימה מופרדת בפסיקים של סוגי נתונים של מקומות שיוחזרו. לדוגמה, כדי לאחזר את השם המוצג ואת הכתובת של המקום.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
הערה: אסור להשתמש ברווחים בשום מקום ברשימת השדות.

כדי לאחזר את כל השדות, משתמשים ב-*.
```
X-Goog-FieldMask: *
```
אמנם אפשר להשתמש בתו הכללי (*) בפיתוח, אבל Google לא ממליצה להשתמש במסכת שדות התגובה של התו הכללי בסביבת ייצור, כי אפשר לקבל כמות גדולה של נתונים.

הנחיות נוספות לשימוש ב-places.iconMaskBaseUri וב-places.iconBackgroundColor מופיעות בקטע סמלי מקומות.

מציינים אחד או יותר מהשדות הבאים:
- השדות הבאים מפעילים את מק"ט של Text Search Essentials עם מזהה בלבד:
  places.attributions
  places.id
  places.consumerAlert
  places.name^*
  nextPageToken
  places.movedPlace
  places.movedPlaceId
  ‫^* השדה places.name מכיל את שם המשאב של המקום בפורמט: places/PLACE_ID. משתמשים ב-places.displayName במהדורת Pro כדי לגשת לשם המקום בטקסט.
  
  רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).
- השדות הבאים מפעילים את מק"ט חיפוש טקסט Pro:
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  places.adrFormatAddress
  places.businessStatus
  places.containingPlaces
  places.displayName
  places.formattedAddress
  places.googleMapsLinks
  places.googleMapsTypeLabel
  places.googleMapsUri
  places.iconBackgroundColor
  places.iconMaskBaseUri
  places.location
  places.openingDate
  places.photos
  places.plusCode
  places.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.searchUri
  places.subDestinations
  places.timeZone
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* תיאורי כתובות זמינים בדרך כלל ללקוחות בהודו, ובמקומות אחרים הם ניסיוניים.
  רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).
- השדות הבאים מפעילים את חיפוש טקסט Enterprise SKU:
  places.currentOpeningHours
  places.currentSecondaryOpeningHours
  places.internationalPhoneNumber
  places.nationalPhoneNumber
  places.priceLevel
  places.priceRange
  places.rating
  places.regularOpeningHours
  places.regularSecondaryOpeningHours
  places.transitStation
  places.userRatingCount
  places.websiteUri
  רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).
- השדות הבאים מפעילים את מק"ט חיפוש טקסט Enterprise + Atmosphere:
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  routingSummaries^*
  places.servesBeer
  places.servesBreakfast
  places.servesBrunch
  places.servesCocktails
  places.servesCoffee
  places.servesDessert
  places.servesDinner
  places.servesLunch
  places.servesVegetarianFood
  places.servesWine
  places.takeout
  
  ^* חיפוש טקסט וחיפוש בסביבה בלבד
  רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

textQuery

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

התכונה 'חיפוש טקסט' (חדשה) לא מיועדת לשאילתות דו-משמעיות, כולל:

סוג השאילתה	דוגמה
יותר מדי מושגים או אילוצים, כמו שמות של כמה מקומות, כבישים או ערים בשאילתה אחת	"Market Street San Francisco San Jose Airport"
רכיבים של כתובת למשלוח דואר שלא מיוצגים במפות Google	"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco"
שמות של עסקים, רשתות או קטגוריות בשילוב עם מיקומים שבהם הישויות האלה לא זמינות	‫"Tesco near Dallas, Texas"
שאילתות דו-משמעיות עם כמה פרשנויות	"Charger drop-off"
שמות היסטוריים שכבר לא נמצאים בשימוש	"Middlesex United Kingdom"
רכיבים או כוונות לא גיאוספציאליים	"כמה סירות יש בנמל ונטורה?"
שמות לא רשמיים או שמות מותאמים אישית	"The Jenga" "The Helter Skelter"
קואורדינטות של אורך ורוחב	‎"37.422131,-122.084801"‎

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

includeFutureOpeningBusinesses

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

כדי לאחזר את הסטטוס של העסק, צריך לכלול את places.businessStatus במסכת השדות של הבקשה. כדי לאחזר את תאריך הפתיחה הצפוי של העסק, צריך לכלול את places.openingDate במסכת השדות של הבקשה.
includedType

התוצאות מוטות למקומות שתואמים לסוג שצוין, כפי שמוגדר בטבלה א'. אפשר לציין רק סוג אחד. לדוגמה:
- "includedType":"bar"
- "includedType":"pharmacy"
הערה: הערכים בטבלה ב' מוחזרים רק בתגובה. אי אפשר להשתמש בערכים בטבלה ב' כמסנן.

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

כדי להחיל סינון לפי סוג על כל השאילתות, מגדירים את strictTypeFiltering לערך true.

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

אם הערך הוא true, התשובה כוללת עסקים שמגיעים אל הלקוחות או מספקים להם משלוחים באופן ישיר, אבל אין להם מיקום פיזי. אם הערך מוגדר ל-false, ה-API מחזיר רק עסקים עם מיקום פיזי.
languageCode

השפה שבה יוחזרו התוצאות.
- כאן אפשר לעיין ברשימת השפות הנתמכות. ‫Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
- אם לא מציינים את הערך languageCode, ברירת המחדל של ה-API היא en. אם מציינים קוד שפה לא תקין, ה-API מחזיר שגיאת INVALID_ARGUMENT.
- ה-API עושה כמיטב יכולתו כדי לספק כתובת רחוב שגם המשתמש וגם המקומיים יוכלו לקרוא. כדי להשיג את המטרה הזו, היא מחזירה כתובות רחוב בשפה המקומית, בתעתיק לכתב שניתן לקריאה על ידי המשתמש אם יש צורך בכך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מתוך הרכיב הראשון.
- אם השם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הכי קרובה.
- לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שממשק ה-API בוחר להחזיר, ועל הסדר שבו הן מוחזרות. הגיאוקודר מפרש קיצורים בצורה שונה בהתאם לשפה, למשל קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת.
locationBias

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

אפשר לציין locationRestriction או locationBias, אבל לא את שניהם. אפשר לחשוב על locationRestriction כהגדרת האזור שבו התוצאות חייבות להיות, ועל locationBias כהגדרת האזור שבו התוצאות כנראה יהיו, אבל הן יכולות להיות גם מחוץ לאזור.

הערה: אם לא מציינים את הערכים locationBias ו-locationRestriction, ה-API משתמש בהטיה לפי כתובת IP כברירת מחדל. בשיטת ההטיה לפי כתובת IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות.

הערה: אפשר לבטל את הפרמטר locationBias אם הפרמטר textQuery מכיל מיקום מפורש כמו Market in Barcelona. במקרה כזה, המערכת מתעלמת מהמדיניות locationBias.

מגדירים את האזור כתצוגת חלון מלבנית או כעיגול.
- מעגל מוגדר על ידי נקודת מרכז ורדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50000.0, כולל. רדיוס ברירת המחדל הוא 0.0. לדוגמה:
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- מלבן הוא אזור תצוגה של קווי רוחב ואורך, שמיוצג על ידי שתי נקודות נמוכות וגבוהות שממוקמות באלכסון אחת מול השנייה. הנקודה הנמוכה מסמנת את הפינה הדרום-מערבית של המלבן, והנקודה הגבוהה מייצגת את הפינה הצפון-מזרחית של המלבן.
  
  אזור התצוגה נחשב לאזור סגור, כלומר הוא כולל את הגבול שלו. הגבולות של קו הרוחב צריכים להיות בין ‎-90 ל-90 מעלות, כולל, והגבולות של קו האורך צריכים להיות בין ‎-180 ל-180 מעלות, כולל:
  - אם low = high, אזור התצוגה מורכב מהנקודה היחידה הזו.
  - אם low.longitude > high.longitude, טווח קווי האורך הפוך (אזור התצוגה חוצה את קו האורך 180 מעלות).
  - אם low.longitude = ‎-180 מעלות ו-high.longitude = ‎180 מעלות, אז אזור התצוגה כולל את כל קווי האורך.
  - אם low.longitude = 180 מעלות ו-high.longitude = ‎-180 מעלות, טווח קווי האורך ריק.
  - אם low.latitude > high.latitude, טווח קווי הרוחב ריק.
  חובה למלא את הערכים הנמוך והגבוה, והתיבה שמייצגת את הטווח לא יכולה להיות ריקה. אם אזור התצוגה ריק, תופיע שגיאה.
  
  לדוגמה, אזור התצוגה הזה כולל את כל העיר ניו יורק:
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
locationRestriction

מציינת אזור לחיפוש שאילתות קטגוריות בלבד, שיכולות להחזיר כמה מקומות (לדוגמה, "Restaurants in New York" או "Shopping malls"). לא מוחזרות תוצאות מחוץ לאזור שצוין.

מגדירים את האזור כאזור תצוגה מלבני. דוגמה להגדרת אזור התצוגה מופיעה בתיאור של locationBias.

אפשר לציין locationRestriction או locationBias, אבל לא את שניהם. אפשר לחשוב על locationRestriction כהגדרת האזור שבו התוצאות חייבות להיות, ועל locationBias כהגדרת האזור שבו התוצאות כנראה יהיו, אבל הן יכולות להיות גם מחוץ לאזור.

הערה: אם לא מציינים את locationBias ואת locationRestriction, המערכת משתמשת בהטיה לפי כתובת IP כברירת מחדל. בשיטת ההטיה לפי כתובת IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות.
maxResultCount (הוצא משימוש)

הוצא משימוש: השדה הזה הוצא משימוש לטובת pageSize. אם מציינים גם את maxResultCount וגם את pageSize, המערכת תשתמש ב-pageSize ותתעלם מ-maxResultCount.

מציין את מספר התוצאות (בין 1 ל-20) שיוצגו בכל דף. לדוגמה, אם מגדירים ערך של 5 לפרמטר maxResultCount, יוחזרו עד 5 תוצאות בדף הראשון. אם יש עוד תוצאות שאפשר להחזיר מהשאילתה, התשובה כוללת nextPageToken שאפשר להעביר לבקשה הבאה כדי לגשת לדף הבא.

הערה: אם הערך של maxResultCount הוא 0 או לא מצוין, ה-API יחזיר כברירת מחדל 20 תוצאות לכל דף. אם הערך של maxResultCount גדול מ-20, ה-API יחזיר עד 20 תוצאות לכל דף.
evOptions

המדיניות קובעת פרמטרים לזיהוי של מתקני טעינה זמינים לרכב חשמלי (EV) ושל קצבי טעינה.
- connectorTypes
  
  סינון לפי סוג המחבר לטעינת רכב חשמלי שזמין במקום. מקום שלא תומך באף אחד מסוגי מתקני הטעינה יסונן. סוגי המחברים הנתמכים לטעינת רכבים חשמליים כוללים מטענים משולבים (AC ו-DC), מטעני Tesla, מטענים שתואמים לתקן GB/T (לטעינה מהירה של רכבים חשמליים בסין) ומטענים לשקע בקיר. מידע נוסף מופיע במאמרי העזרה.
  - כדי לסנן את התוצאות לפי מחבר ספציפי נתמך, מגדירים את connectorTypes לערך הזה. לדוגמה, כדי למצוא מחברי J1772 מסוג 1, מגדירים את connectorTypes ל-EV_CONNECTOR_TYPE_J1772.
  - כדי לסנן תוצאות של מחברים לא נתמכים, מגדירים את connectorTypes לערך EV_CONNECTOR_TYPE_OTHER.
  - כדי לסנן תוצאות של כל סוג מחבר שהוא שקע בקיר, מגדירים את connectorTypes לערך EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET.
  - כדי לסנן את התוצאות לפי סוג מחבר, צריך להגדיר את connectorTypes ל-EV_CONNECTOR_TYPE_UNSPECIFIED או לא להגדיר ערך ל-connectorTypes.
- minimumChargingRateKw
  
  מסננים מקומות לפי קצב טעינה מינימלי לרכבים חשמליים בקילוואט (kW). כל המקומות שבהם הטעינה מתבצעת בתעריף נמוך מתעריף הטעינה המינימלי מסוננים. לדוגמה, כדי למצוא מטענים לרכב חשמלי עם מהירויות טעינה של 10 קילוואט לפחות, אפשר להגדיר את הפרמטר הזה לערך '10'.
minRating

התוצאות יוגבלו רק לאלה שדירוג המשתמשים הממוצע שלהן גדול מהמגבלה הזו או שווה לה. הערכים צריכים להיות בין 0.0 ל-5.0 (כולל), במרווחים של 0.5. לדוגמה: 0, ‏ 0.5, ‏ 1.0,‏ ... , ‏ 5.0 כולל. הערכים מעוגלים כלפי מעלה ל-0.5 הקרוב ביותר. לדוגמה, ערך של 0.6 יסנן את כל התוצאות עם דירוג נמוך מ-1.0.

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

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

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

מציין את מספר התוצאות (בין 1 ל-20) שיוצגו בכל דף. לדוגמה, אם מגדירים ערך של 5 לפרמטר pageSize, יוחזרו עד 5 תוצאות בדף הראשון. אם יש עוד תוצאות שאפשר להחזיר מהשאילתה, התשובה כוללת nextPageToken שאפשר להעביר לבקשה הבאה כדי לגשת לדף הבא.

הערה: אם הערך של pageSize הוא 0 או לא מצוין, ה-API יחזיר כברירת מחדל 20 תוצאות לכל דף. אם הערך של pageSize גדול מ-20, ה-API יחזיר עד 20 תוצאות לכל דף.
pageToken

מציין את nextPageToken מגוף התגובה של הדף הקודם.
priceLevels

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

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

מציינים מערך של ערך אחד או יותר שמוגדרים על ידי PriceLevel.

לדוגמה:
```
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
```
הערה: אסור להשתמש ב-PRICE_LEVEL_FREE בבקשה. הוא משמש רק כדי לאכלס את התשובה.

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

מציין איך התוצאות מדורגות בתשובה על סמך סוג השאילתה:
- בשביל שאילתה קטגורית כמו 'מסעדות בניו יורק', ההגדרה שמוגדרת כברירת מחדל היא RELEVANCE (דירוג התוצאות לפי רלוונטיות לחיפוש). אפשר להגדיר את rankPreference ל-RELEVANCE או ל-DISTANCE (דירוג התוצאות לפי מרחק).
- לשאילתה לא קטגורית כמו 'מאונטיין ויו, קליפורניה', מומלץ להשאיר את rankPreference ללא הגדרה.
הפרמטר הזה לא חל על שאילתות לגבי מלונות או על שאילתות גיאופוליטיות (לדוגמה, שאילתות שקשורות לאזורים אדמיניסטרטיביים, ליישובים, למיקודים, למחוזות בתי ספר או למדינות).
regionCode

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

אם שם המדינה בשדה formattedAddress בתגובה זהה לערך regionCode, קוד המדינה לא יופיע בשדה formattedAddress. לפרמטר הזה אין השפעה על adrFormatAddress, שתמיד כולל את שם המדינה אם הוא זמין, או על shortFormattedAddress, שאף פעם לא כולל אותו.

רוב הקודים של CLDR זהים לקודים של ISO 3166-1, עם כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא uk (‎.co.uk), אבל קוד ISO 3166-1 שלה הוא gb (טכנית, עבור הישות 'ממלכת בריטניה הגדולה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.
strictTypeFiltering

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

דוגמאות לחיפוש טקסט (חדש)

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

בדוגמה הבאה מוצגת בקשה לחיפוש טקסט (חדש) של 'אוכל צמחוני חריף בסידני, אוסטרליה':

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.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

שימו לב שהכותרת X-Goog-FieldMask מציינת שהתגובה מכילה את שדות הנתונים הבאים: places.displayName,places.formattedAddress. התשובה תהיה בפורמט הבא:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

כדי להחזיר מידע נוסף, מוסיפים עוד סוגי נתונים למסכת השדות. לדוגמה, מוסיפים places.types,places.websiteUri כדי לכלול את סוג המסעדה ואת כתובת האינטרנט בתשובה:

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.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'

התשובה תהיה בפורמט הבא:

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

סינון מקומות לפי רמת מחיר

אפשר להשתמש באפשרות priceLevel כדי לסנן את התוצאות לפי מסעדות שהוגדרו כזולות או במחיר בינוני:

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

בדוגמה הזו נעשה שימוש גם בכותרת X-Goog-FieldMask כדי להוסיף את שדה הנתונים places.priceLevel אל התגובה, כך שהיא תהיה בפורמט:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

מוסיפים אפשרויות נוספות כדי לצמצם את החיפוש, כמו includedType, minRating,‏ rankPreference,‏ openNow ופרמטרים אחרים שמתוארים במאמר בנושא פרמטרים אופציונליים.

הגבלת החיפוש לאזור מסוים

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

הערה: כשמשתמשים ב-locationRestriction, אפשר לציין את האזור רק כחלון תצוגה מלבני. כשמשתמשים ב-locationBias, אפשר לציין את האזור כתיבת תצוגה מלבנית או כעיגול.

הגבלת אזור באמצעות locationRestriction

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

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

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

הטיה לאזור מסוים באמצעות locationBias

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

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 10,
  "locationBias": {
    "circle": {
      "center": {"latitude": 37.7937, "longitude": -122.3965},
      "radius": 500.0
    }
  },
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

חיפוש מטענים לרכב חשמלי עם קצב טעינה מינימלי

משתמשים בלחצנים minimumChargingRateKw ו-connectorTypes כדי לחפש מקומות עם מטענים זמינים שמתאימים לרכב החשמלי שלכם.

בדוגמה הבאה מוצגת בקשה למחברי טעינה של רכב חשמלי מסוג Tesla ו-J1772 type 1 עם קצב טעינה מינימלי של 10 קילוואט במאונטיין ויו, קליפורניה. רק ארבע תוצאות מוחזרות.

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

התגובה לבקשה תהיה:

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

חיפוש עסקים שנותנים שירות באזור מוגדר

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

בדוגמה הבאה מוצגת בקשה לשרברבים בסן פרנסיסקו:

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

בתשובה, עסקים ללא כתובת למקרי חירום לא כוללים את השדה formattedAddress:

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

ציון מספר התוצאות שיוחזרו בכל דף

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

בדוגמה הבאה מוצגת בקשה לחיפוש 'פיצה בניו יורק' עם הגבלה של 5 תוצאות בכל דף:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

כדי לגשת לדף הבא של התוצאות, משתמשים ב-pageToken כדי להעביר את nextPageToken בגוף הבקשה:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

קבלת תיאורים של כתובות

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

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

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

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

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "displayName": {
              "text": "Central San Jose",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          }
        ]
      }
    },
    /.../
  ]
}

חיפוש עסקים שייפתחו בעתיד

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

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
  "textQuery": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "maxResultCount": 20,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchText"

התשובה כוללת עסקים שעתידים להיפתח, יחד עם הסטטוס של העסק ותאריך הפתיחה הצפוי:

{
  "places": [
    {
      "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
      "businessStatus": "FUTURE_OPENING",
      "displayName": {
        "text": "Roberts Greenhouse and Tree Farm",
        "languageCode": "en"
      },
      "openingDate": {
        "year": 2026,
        "month": 4,
        "day": 15
      }
    }
  ]
}

קבלת מידע על תחנות של תחבורה ציבורית

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

בדוגמה הבאה מוצגת בקשה לחיפוש של 'תחנת גרנד סנטרל':

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
  "textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"

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

{
  "places": [
    {
      "id": "ChIJhRwB-yFawokRi0AhGH87UTc",
      "displayName": {
        "text": "Grand Central",
        "languageCode": "en"
      },
      "transitStation": {
        "displayName": {
          "text": "Grand Central",
          "languageCode": "en"
        },
        "agencies": [
          {
            "displayName": {
              "text": "Metro-North Railroad",
              "languageCode": "en"
            },
            "url": "http://www.mta.info/mnr",
            "lines": [
              {
                "id": "ChIJOXpD29y2wokRryDO0CocwK0",
                "vehicleType": "HEAVY_RAIL",
                "displayName": {
                  "text": "Harlem",
                  "languageCode": "en"
                },
                "textColor": "#FFFFFF",
                "backgroundColor": "#0061AA",
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
                },
                "alerts": [
                  {
                    "effect": "OTHER",
                    "texts": [
                      {
                        "headline": {
                          "text": "Information",
                          "languageCode": "en"
                        },
                        "summary": {
                          "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.",
                          "languageCode": "en"
                        },
                        "fullDescription": {
                          "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.",
                          "languageCode": "en"
                        }
                      }
                    ],
                    "detailsUrls": [
                      {
                        "url": "https://new.mta.info/"
                      }
                    ],
                    "cause": "OTHER_CAUSE",
                    "startTime": "2026-04-16T04:00:00Z",
                    "endTime": "2026-12-01T04:45:00Z",
                    "attribution": {
                      "link": {
                        "text": "new.mta.info",
                        "url": "https://new.mta.info/"
                      }
                    },
                    "createTime": "2026-05-15T22:39:30Z",
                    "severityLevel": "INFO"
                  }
                ]
              },
              ...
            ]
          },
          ...
        ]
        "stops": [
          {
            "id": "ChIJOfdrigFZwokRJPllLwfPrJY",
            "location": {
              "latitude": 40.752823,
              "longitude": -73.977195999999992
            },
            "wheelchairAccessibleEntrance": true
          }
        ],
        "departureBoards": [
          {
            "displayType": "TIME_CENTRIC",
            "rows": [
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:42:00Z",
                      "timingType": "SCHEDULED",
                      "predictedTime": "2026-05-15T22:42:00Z",
                      "updateTime": "2026-05-15T22:38:50Z"
                    },
                    "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY",
                    "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM"
                  }
                ]
              },
              ...
            ]
          }
        ]
      }
    },
    {
      "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc",
      "displayName": {
        "text": "Grand Central Station",
        "languageCode": "en"
      }
    }
  ]
}

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

נקודות ניווט מחזירות navigationPointToken. אפשר להעביר את האסימון הזה אל Navigation SDK (זמין ל-Android או ל-iOS) או אל Routes API כדי להנחות את הנהגים אל המיקום הספציפי הזה. מידע נוסף זמין במאמר בנושא אסימונים של נקודות ניווט.

בדוגמה הבאה מוצגת בקשה לחיפוש טקסט (חדש) של 'נמל התעופה הבינלאומי של סן פרנסיסקו' שכוללת את entrances ואת navigationPoints במסכת השדות:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
  "textQuery": "San Francisco International Airport",
  "pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"

התשובה כוללת את הכניסות ואת נקודות הניווט של המקום:

{
  "places": [
    {
      "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
      "displayName": {
        "text": "San Francisco International Airport",
        "languageCode": "en"
      },
      "entrances": [
        {
          "location": {
            "latitude": 37.6172154,
            "longitude": -122.3839724
          }
        },
        {
          "location": {
            "latitude": 37.6174073,
            "longitude": -122.384196
          }
        },
        ...
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
          "displayName": {
            "text": "International Terminal Departures Level",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6153121,
            "longitude": -122.3900833
          },
          "travelModes": ["WALK"]
        },
        {
          "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
          "displayName": {
            "text": "Domestic Garage - SFO Short Term Parking",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6157153,
            "longitude": -122.3885012
          },
          "travelModes": ["DRIVE", "WALK"],
          "usages": ["PARKING"]
        },
        ...
      ]
    }
  ]
}

רוצה לנסות?

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

בצד שמאל של הדף, לוחצים על סמל ה-API‏ api.
אפשר לערוך את פרמטרים של הבקשה.
לוחצים על הכפתור Execute (הפעלה). בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.
בחלונית APIs Explorer, לוחצים על סמל המסך המלא מסך מלא כדי להרחיב את החלון של APIs Explorer.

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

מבוא

בקשות לחיפוש טקסט (חדש)

תשובות של חיפוש טקסט (חדש)

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

FieldMask

textQuery

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

includeFutureOpeningBusinesses

includedType

includePureServiceAreaBusinesses

languageCode

locationBias

locationRestriction

maxResultCount (הוצא משימוש)

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering