חיפוש בקרבת מקום (חדש)

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

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

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

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

בקשות של חיפוש בקרבת מקום (חדש)

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

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

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

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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" \
https://places.googleapis.com/v1/places:searchNearby

תשובות לחיפוש בקרבת מקום (חדש)

חיפוש בקרבת מקום (חדש) מחזיר אובייקט 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: *

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

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

      places.accessibilityOptions
      places.addressComponents
      places.adrFormatAddress
      places.attributions
      places.businessStatus
      places.containingPlaces
      places.displayName
      places.formattedAddress
      places.googleMapsLinks*
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.id
      places.location
      places.name**
      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.name מכיל את שם המשאב של המקום בפורמט: places/PLACE_ID. משתמשים ב-places.displayName כדי לגשת לשם הטקסט של המקום.

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

      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

      * חיפוש טקסט וחיפוש בקרבת מקום בלבד

  • locationRestriction

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

    לדוגמה: 

    "locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

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

  • includedTypes/excludedTypes, ‏ includedPrimaryTypes/excludedPrimaryTypes

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

    לכל מקום יכול להיות רק סוג ראשי אחד מהסוגים שמפורטים בטבלה א' שמשויכים אליו. לדוגמה, הסוג הראשי יכול להיות "mexican_restaurant" או "steak_house". אפשר להשתמש ב-includedPrimaryTypes וב-excludedPrimaryTypes כדי לסנן את התוצאות לפי הסוג הראשי של המקום.

    למקום יכולים להיות גם מספר ערכים של סוגים מהסוגים שמפורטים בטבלה א' שמשויכים אליו. לדוגמה, למסעדה יכולים להיות הסוגים הבאים: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". משתמשים במקשות includedTypes ו-excludedTypes כדי לסנן את התוצאות ברשימת הסוגים שמשויכים למיקום.

    כשמציינים סוג ראשי כללי, כמו "restaurant" או "hotel", התשובה יכולה לכלול מקומות עם סוג ראשי ספציפי יותר מהסוג שצוין. לדוגמה, אפשר לציין הכללה של סוג ראשי של "restaurant". לאחר מכן, התשובה יכולה לכלול מקומות עם סוג ראשי של "restaurant", אבל היא יכולה גם לכלול מקומות עם סוג ראשי ספציפי יותר, כמו "chinese_restaurant" או "seafood_restaurant".

    אם מציינים חיפוש עם כמה הגבלות סוג, יוחזרו רק מקומות שעומדים בכל ההגבלות. לדוגמה, אם מציינים את הערך {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, המקומות שחוזרים מספקים שירותים שקשורים ל-"restaurant" אבל לא פועלים בעיקר בתור "steak_house".

    includedTypes

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

    excludedTypes

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

    אם מציינים בבקשה גם את הערך של includedTypes ( למשל "school") וגם את הערך של excludedTypes (למשל "primary_school"), התשובה תכלול מקומות שסווגו כ-"school" אבל לא כ-"primary_school". התשובה כוללת מקומות שתואמים לפחות לאחד מה-includedTypes ולאף אחד מה-excludedTypes.

    אם יש סוגי נתונים מתנגשים, למשל סוג שמופיע גם ב-includedTypes וגם ב-excludedTypes, תוחזר שגיאת INVALID_REQUEST.

    includedPrimaryTypes

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

    excludedPrimaryTypes

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

    אם יש סוגים ראשיים סותרים, למשל סוג שמופיע גם ב-includedPrimaryTypes וגם ב-excludedPrimaryTypes, תוחזר שגיאה מסוג INVALID_ARGUMENT.

  • languageCode

    השפה שבה יוצגו התוצאות.

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

  • maxResultCount

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

  • rankPreference

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

    • POPULARITY (ברירת מחדל) מיון התוצאות לפי הפופולריות שלהן.
    • DISTANCE מיון התוצאות בסדר עולה לפי המרחק שלהן מהמיקום שצוין.

  • regionCode

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

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

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

דוגמאות לחיפוש בקרבת מקום (חדש)

חיפוש מקומות מסוג אחד

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

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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" \
https://places.googleapis.com/v1/places:searchNearby

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

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

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

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

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

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

חיפוש מקומות מסוגים שונים

בדוגמה הבאה מוצגת בקשה לחיפוש בקרבת מקום (חדש) של שמות התצוגה של כל חנויות הנוחות והחנויות לממכר משקאות ברדיוס של 1,000 מטר מה-circle שצוין:

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby
בדוגמה הזו מוסיפים את השדות places.primaryType ו-places.types למסכת השדה, כדי שהתגובה תכלול את סוג המקום בכל אחד מהם. כך קל יותר לבחור את המקום המתאים מהתוצאות.

בדוגמה הבאה מוצגת בקשה לחיפוש בקרבת מקום (חדש) לכל המקומות מסוג "school", לא כולל כל המקומות מסוג "primary_school", והתוצאות מדורגות לפי מרחק:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

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

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

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

נסה בעצמך!

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

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

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

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

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