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

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

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

מבוא

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

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

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

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

‫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'

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

התגובה של Text Search (חדש) היא אובייקט 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: *

    מציינים אחד או יותר מהשדות הבאים:

    • השדות הבאים מפעילים את Text Search Essentials ID Only SKU:

      places.attributions
      places.id
      places.name*
      nextPageToken

      ‫* השדה places.name מכיל את שם המשאב של המקום בפורמט: places/PLACE_ID. משתמשים ב-places.displayName במהדורת Pro כדי לגשת לשם הטקסט של המקום.

    • השדות הבאים מפעילים את מק"ט Text Search Pro:

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      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.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

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

      ** השדה places.googleMapsLinks נמצא בשלב טרום-GA Preview ולא חל תשלום על השימוש בו במהלך תקופת ה-Preview, כלומר החיוב הוא 0$.

    • השדות הבאים מפעילים את מק"ט Text Search Enterprise:

      places.currentOpeningHours
      places.currentSecondaryOpeningHours
      places.internationalPhoneNumber
      places.nationalPhoneNumber
      places.priceLevel
      places.priceRange
      places.rating
      places.regularOpeningHours
      places.regularSecondaryOpeningHours
      places.userRatingCount
      places.websiteUri

    • השדות הבאים מפעילים את מק"ט Text Search 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
      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"

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

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

  • includePureServiceAreaBusinesses

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

  • languageCode

    השפה שבה יוחזרו התוצאות.

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

  • locationBias

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

    אפשר לציין locationRestriction או locationBias, אבל לא את שניהם. אפשר לחשוב על locationRestriction כהגדרה של האזור שבו התוצאות צריכות להיות, ועל 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

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

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

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

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

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

  • evOptions

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

    • connectorTypes

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

      • כדי לסנן את התוצאות לפי מחבר ספציפי נתמך, מגדירים את connectorTypes לערך הזה. לדוגמה, כדי למצוא מחברים מסוג J1772 type 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) שיוצגו בכל דף. לדוגמה, אם מגדירים את הערך pageSize ל-5, יוחזרו עד 5 תוצאות בדף הראשון. אם יש עוד תוצאות שאפשר להחזיר מהשאילתה, התשובה כוללת nextPageToken שאפשר להעביר לבקשה הבאה כדי לגשת לדף הבא.

  • pageToken

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

  • priceLevels

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

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

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

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

    לדוגמה:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • 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, מוחזרים רק מקומות שתואמים לסוגים שצוינו ב-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

אפשר להשתמש בפרמטר 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 קילוואט ב-Mountain View, קליפורניה. רק ארבע תוצאות מוחזרות.

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 במסכת השדות:

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"
          }
        ]
      }
    },
    /.../
  ]
}

נסה בעצמך!

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

  1. לוחצים על סמל ה-API api בצד שמאל של הדף.

  2. אפשר לערוך את פרמטרים הבקשה.

  3. לוחצים על הלחצן Execute (הפעלה). בתיבת הדו-שיח, בוחרים את החשבון שרוצים להשתמש בו כדי לשלוח את הבקשה.

  4. בחלונית APIs Explorer, בוחרים בסמל המסך המלא מסך מלא כדי להרחיב את החלון של APIs Explorer.