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

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

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

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

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

Nearby Search (New) מחזיר אובייקט 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.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, places.subDestinations, places.subDestinations, places.name*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, places.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport

      places/PLACE_ID משתמשים ב-places.displayName כדי לגשת לשם הטקסט של המקום.

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

      places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, 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.reviews, places.reviews, places.reviewsplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout

  • locationRestriction

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

    לדוגמה:

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

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

  • IncludeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

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

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

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

    אם חיפוש מוגדר עם כמה הגבלות סוגים, יוחזרו רק מקומות שעומדים בכל ההגבלות. לדוגמה, אם מציינים את הערך {"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, עם כמה יוצאים מן הכלל. לדוגמה, הדומיין ccTLD של בריטניה הוא '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

רוצה לנסות?

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

  1. בצד שמאל של הדף, בוחרים בסמל ה-API מרחיבים את API Explorer..
  2. אפשר להרחיב את הקטע Show advanced parameters ולהגדיר את הפרמטר fields ל-field mask.
  3. אפשר לערוך את גוף הבקשה.
  4. לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים להשתמש לשליחת הבקשה.

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