דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

'חיפוש בקרבת מקום' (חדש) מחזיר אובייקט JSON כתגובה. בתשובה:

המערך places מכיל את כל המקומות התואמים.
כל מקום במערך מיוצג על ידי Place לאובייקט. האובייקט Place מכיל מידע מפורט על במקום.
השדה FieldMask מועבר בבקשה מציין את רשימת השדות שהוחזר באובייקט Place.

אובייקט ה-JSON המלא מופיע בתבנית:

{
  "places": [
    {
      object (Place)
    }
  ]
}

פרמטרים נדרשים

FieldMask

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

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

מציינים רשימה מופרדת בפסיקים של סוגי נתוני המקומות שרוצים להחזיר. לדוגמה, כדי לאחזר את השם המוצג ואת הכתובת של המקום.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
הערה: אי אפשר להשתמש במרחבים משותפים בשום מקום ברשימת השדות.

אפשר להשתמש ב-* כדי לאחזר את כל השדות.
```
X-Goog-FieldMask: *
```
תו כללי לחיפוש "*" בוחר את כל השדות. אבל בעוד אפשר להשתמש בתו כללי לחיפוש בפיתוח, Google לא ממליצה להשתמש אנונימיזציה של שדה התשובה עם תו כללי לחיפוש (*) בסביבת הייצור בגלל הכמות הגדולה של הנתונים שאפשר להחזיר.

הנחיות נוספות לשימוש ב-places.iconMaskBaseUri אפשר למצוא את places.iconBackgroundColor ב הקטע 'סמלי מקום'.

צריך לציין אחד או יותר מהשדות הבאים:
- השדות הבאים מפעילים את המק"ט של התכונה 'חיפוש בקרבת מקום' (בסיסי):
  
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.attributions, 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.types, places.utcOffsetMinutes, places.viewport
  
  ^* השדה places.name מכיל את המקום שם המשאב בפורמט: 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.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
  }
}
```

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

IncludeTypes/excludedTypes, includePrimaryTypes/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, עם כמה יוצאים מן הכלל. לדוגמה, ה-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.

לוחצים על סמל ה-API, , בצד שמאל של הדף.
אפשר להרחיב את הקטע הצגת פרמטרים רגילים ולהגדיר הפרמטר fields ל-field mask.
אפשר לערוך את גוף הבקשה.
לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים להשתמש לצורך שליחת הבקשה.
בחלונית של API Explorer לוחצים על סמל ההרחבה. , כדי להרחיב את החלון של API Explorer.

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

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

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

פרמטרים נדרשים

FieldMask

locationRestriction

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

IncludeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode