דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

"10 High Street, UK" או "123 Main Street, US"	רחובות רבים שנקראים 'High Street' בבריטניה, רחובות רבים שנקראים 'Main Street' בארצות הברית. השאילתה לא מחזירה תוצאות רצויות, אלא אם מגדירים הגבלת מיקום.
'ChainRestaurant New York'	כמה מיקומים של 'ChainRestaurant' בניו יורק, ללא רחוב או שם רחוב.
"10 High Street, Escher UK" או "123 Main Street, Pleasanton US"	יש רק רחוב אחד בשם 'High Street' בעיר Escher בבריטניה, ורק רחוב אחד בשם 'Main Street' בעיר Pleasanton בקליפורניה, ארה"ב.
"UniqueRestaurantName New York"	יש רק מוסד אחד בשם הזה בניו יורק, ולכן אין צורך בכתובת רחוב כדי להבדיל בינו לבין מוסדות אחרים.
"pizza restaurants in New York"	השאילתה הזו מכילה את הגבלת המיקום שלה, ו'פיצריות' הוא סוג מקום מוגדר היטב. הפונקציה מחזירה כמה תוצאות.
‎+1 514-670-8700‎	השאילתה הזו מכילה מספר טלפון. הפונקציה מחזירה כמה תוצאות של מקומות שמשויכים למספר הטלפון הזה. הערה: כדי לקבל את התוצאות הטובות ביותר בחיפוש לפי מספר טלפון, צריך לכלול את קוד המדינה ואחריו רווח, ולהגדיר את הפרמטר `regionCode` כך שיתאים לקוד המדינה.

ב-API 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: *
```
סמל הפלאי "*" בוחר את כל השדות. עם זאת, אפשר להשתמש בתווית ה-wildcard הזו בפיתוח, אבל Google ממליצה לא להשתמש במסכת השדה של התגובה עם תו ה-wildcard (*) בסביבת הייצור בגלל כמות הנתונים הגדולה שיכולה להוחזר.

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

מציינים אחד או יותר מהשדות הבאים:
- השדות הבאים מפעילים את מק"ט לחיפוש טקסט (מזהה בלבד):
  places.attributions, places.id, places.name^*, nextPageToken
  
  ^* השדה places.name מכיל את שם המשאב של המקום בפורמט: places/PLACE_ID. משתמשים ב-places.displayName כדי לגשת לשם הטקסט של המקום.
- השדות הבאים מפעילים את מק"ט של חיפוש טקסט (בסיסי):
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks^*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.location, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport
  
  ^* השדה places.googleMapsLinks נמצא בשלב התצוגה המקדימה לפני GA, והוא לא כרוך בתשלום, כלומר החיוב הוא 0 $על השימוש במהלך התצוגה המקדימה.
- השדות הבאים מפעילים את מק"ט של חיפוש טקסט (מתקדם):
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.priceRange, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri
- השדות הבאים מפעילים את מק"ט החיפוש בטקסט (מועדף):
  places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, places.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 מחזיר התאמות של מועמדים על סמך המחרוזת הזו ומסדר את התוצאות לפי מידת הרלוונטיות המשוערת שלהן.

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

includedType

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

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

השפה שבה יוצגו התוצאות.
- כאן אפשר לעיין ברשימת השפות הנתמכות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא תהיה מקיפה.
- אם לא מציינים את הערך של languageCode, ברירת המחדל של ה-API היא en. אם מציינים קוד שפה לא תקין, ה-API מחזיר את השגיאה INVALID_ARGUMENT.
- ה-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, טווח קו הרוחב ריק.
  צריך לאכלס את הערכים של low ו-high, והתיבה המיוצגת לא יכולה להיות ריקה. תצוגת חלון ריקה גורמת לשגיאה.
  
  לדוגמה, חלון התצוגה הזה כולל את ניו יורק במלואה:
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
locationRestriction

מציין אזור לחיפוש. לא יוצגו תוצאות מחוץ לאזור שצוין.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הערה: PRICE_LEVEL_FREE אסור להשתמש בו בבקשה. הוא משמש רק לאכלוס התשובה.

לדוגמה:
```
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
```
rankPreference

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

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

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

רוב קודי CLDR זהים לקודי ISO 3166-1, מלבד כמה חריגים בולטים. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא ‎"uk" (‎.co.uk), והקוד שלו לפי תקן ISO 3166-1 הוא ‎"gb" (טכנית, הישות היא ‎"The United Kingdom of Great Britain and Northern Ireland"). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.
strictTypeFiltering

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

חיפוש עמדות טעינה לרכב חשמלי (EV) עם קצב טעינה מינימלי

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

בדוגמה הבאה מוצגת בקשה למחברים לטעינה של רכבים חשמליים מסוג Tesla ו-J1772 מסוג 1, עם קצב טעינה מינימלי של 10kW ב-Mountain View,‏ CA. רק ארבע תוצאות יחזרו.

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"
}

נסה בעצמך!

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

בוחרים בסמל ה-API, , בצד שמאל של הדף.
אפשר גם להרחיב את האפשרות Show standard parameters ולהגדיר את הפרמטר fields למסכת השדה.
אם רוצים, עורכים את גוף הבקשה.
לוחצים על הלחצן Execute. בתיבת הדו-שיח הקופצת, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.
בחלונית של API Explorer, בוחרים בסמל ההרחבה כדי להרחיב את החלון של API Explorer.

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

בקשות לחיפוש טקסט

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

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

FieldMask

textQuery

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

includedType

includePureServiceAreaBusinesses

languageCode

locationBias

locationRestriction

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

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering