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

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

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

ב-API 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: *

  סמל הוויילדקארד '*' בוחר את כל השדות. עם זאת, אפשר להשתמש בתווית ה-wildcard הזו בפיתוח, אבל Google ממליצה לא להשתמש במסכת השדה של התגובה עם תו ה-wildcard (*) בסביבת הייצור בגלל כמות הנתונים הגדולה שיכולה להוחזר.
  הנחיות נוספות לשימוש ב-places.iconMaskBaseUri וב-places.iconBackgroundColor מפורטות בקטע סמלי מקומות.

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

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

    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,‏ includedPrimaryTypes ו-excludedPrimaryTypes מהבקשה, החיפוש מחזיר מקומות מכל הסוגים בתוך גבולות הגבלת המיקום.

  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" (טכנית, הישות היא ‎"The United Kingdom of Great Britain and Northern Ireland"). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

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

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

בדוגמה הבאה מוצגת בקשה לחיפוש בקרבת מקום (חדשה) של השמות המוצגים של כל המסעדות ברדיוס של 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 ובאפשרויות שלו.

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

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