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

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

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

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

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

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

באמצעות API Explorer תוכלו ליצור בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות ה-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

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

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

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

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    משתמשים ב-* כדי לאחזר את כל השדות.

    X-Goog-FieldMask: *

    צריך לציין אחד או יותר מהשדות הבאים:

    • השדות הבאים מפעילים את מק"ט לחיפוש טקסט (מזהה בלבד):

      places.attributions, places.id, places.name*, nextPageToken

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

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

      ה {10/ places.googleMapsUri} היא places.googleMapsLinks.places.accessibilityOptionsplaces.addressComponentsplaces.adrFormatAddressplaces.businessStatusplaces.containingPlacesplaces.displayNameplaces.formattedAddressplaces.googleMapsLinksplaces.iconBackgroundColorplaces.iconMaskBaseUriplaces.locationplaces.photosplaces.plusCodeplaces.primaryTypeplaces.primaryTypeDisplayNameplaces.pureServiceAreaBusinessplaces.shortFormattedAddressplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport

    • השדות הבאים מפעילים את מק"ט של חיפוש טקסט (מתקדם):

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

    מציינים את האזור כחלון תצוגה מלבני או כמעגל.

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

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

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

  • evOptions

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

    • connectorTypes

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

  • pageToken

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

  • 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 בתור ציון האזור שבו התוצאות חייבות להיות בסביבה, אבל יכולות להיות מחוץ לאזור.

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

curl -X POST -d '{
  "textQuery" : "Spicy 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 ובאפשרויות שלו.

  1. בצד שמאל של הדף, בוחרים בסמל ה-API מרחיבים את API Explorer..

  2. אפשר גם להרחיב את האפשרות Show standard parameters ולהגדיר את הפרמטר fields למסכת השדה.

  3. אם רוצים, עורכים את גוף הבקשה.

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

  5. בחלונית של API Explorer, לוחצים על סמל ההרחבה מרחיבים את API Explorer. כדי להרחיב את חלון ה-API Explorer.