搜尋附近地點 (新)

Nearby Search (New) 要求會接受一或多個地點類型,並傳回指定區域內相符地點的清單。必須提供指定一或多個資料類型的欄位遮罩。Nearby Search (新推出) 僅支援 POST 要求。

您可以透過 API Explorer 發出即時要求,熟悉 API 和 API 選項:

試試看!

Nearby Search (新) 要求

「搜尋附近」(New) 要求是對網址採用 HTTP POST 要求,格式為:

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

    建立回應欄位遮罩,指定要在回應中傳回的欄位清單。使用網址參數 $fieldsfields,或使用 HTTP 標頭 X-Goog-FieldMask,將回應欄位遮罩傳遞至方法。回應中沒有預設的傳回欄位清單。如果省略欄位遮罩,此方法會傳回錯誤。

    欄位遮蓋是不錯的設計做法,可確保您不會要求不必要的資料,避免不必要的處理時間和帳單費用。

    指定要傳回的地點資料類型,並以半形逗號分隔。例如擷取地點的顯示名稱和地址。

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

    使用 * 擷取所有欄位。

    X-Goog-FieldMask: *

    請指定下列一或多個欄位:

    • 下列欄位會觸發 Nearby Search (Basic) SKU

      places.accessibilityOptionsplaces.addressComponentsplaces.adrFormatAddressplaces.businessStatusplaces.displayNameplaces.formattedAddressplaces.googleMapsUriplaces.iconBackgroundColorplaces.iconMaskBaseUriplaces.idplaces.locationplaces.name*places.photosplaces.plusCodeplaces.primaryTypeplaces.primaryTypeDisplayNameplaces.shortFormattedAddressplaces.primaryTypeDisplayNameplaces.nameplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport

      places/PLACE_ID使用 places.displayName 存取地點的文字名稱。

    • 下列欄位會觸發 Nearby Search (Advanced) SKU

      places.currentOpeningHoursplaces.currentSecondaryOpeningHoursplaces.internationalPhoneNumberplaces.nationalPhoneNumberplaces.priceLevelplaces.ratingplaces.regularOpeningHoursplaces.regularSecondaryOpeningHoursplaces.userRatingCountplaces.websiteUri

    • 下列欄位會觸發 Nearby Search (Preferred) SKU

      places.allowsDogsplaces.curbsidePickupplaces.deliveryplaces.dineInplaces.editorialSummaryplaces.evChargeOptionsplaces.fuelOptionsplaces.goodForChildrenplaces.goodForGroupsplaces.goodForWatchingSportsplaces.liveMusicplaces.menuForChildrenplaces.parkingOptionsplaces.paymentOptionsplaces.outdoorSeatingplaces.reservableplaces.restroomplaces.reviews、 /places.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
      }
    }

自選參數

  • includeType/excludedTypes、includePrimaryTypes/excludedPrimaryType

    可讓您從表 A 類型中指定類型清單,用來篩選搜尋結果。每個類型限制類別中最多可指定 50 種類型。

    地點只能擁有相關聯表 A 類型的單一主要類型。舉例來說,主要類型可能是 "mexican_restaurant""steak_house"。使用 includedPrimaryTypesexcludedPrimaryTypes 即可依據地點的主要類型篩選結果。

    地點也可以擁有相關聯表 A 類型的多個類型值。舉例來說,餐廳可能會有下列類型:"seafood_restaurant""restaurant""food""point_of_interest""establishment"。使用 includedTypesexcludedTypes 即可篩選地點相關類型清單的結果。

    如果指定搜尋時設有多種類型限制,系統只會傳回符合所有限制的地點。舉例來說,如果您指定 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]},系統傳回的地點會提供 "restaurant" 相關服務,但並非主要以 "steak_house" 形式運作。

    includedTypes

    表 A 搜尋的地點類型清單 (以半形逗號分隔)。如果省略這個參數,系統會傳回所有類型的地點。

    excludedTypes

    表 A 中排除的地點類型清單 (以半形逗號分隔)。

    如果您在要求中同時指定 includedTypes ( 例如 "school") 和 excludedTypes (例如 "primary_school"),則回應會包含分類為 "school",但不歸為 "primary_school" 的地點。回應會包含至少與 includedTypes 一個和「無」相符的地點。excludedTypes

    如果出現任何相衝突的類型 (例如同時出現在 includedTypesexcludedTypes 中),系統會傳回 INVALID_REQUEST 錯誤。

    includedPrimaryTypes

    表 A 納入的主要地點類型清單 (以半形逗號分隔)。

    excludedPrimaryTypes

    表 A 排除的主要地點類型清單 (以半形逗號分隔)。

    如果出現任何相衝突的主要類型 (例如同時出現在 includedPrimaryTypesexcludedPrimaryTypes 中),系統會傳回 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」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。根據適用法律,這個參數可能會影響結果。

Nearby Search (新) 範例

尋找同類型的地點

以下範例顯示針對 500 公尺半徑範圍內所有餐廳的 Nearby Search (New) 要求 (由 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"
      }
    },
...
}

尋找多種類型的地點

以下範例顯示針對指定 circle 半徑 1000 公尺範圍內的所有便利商店和酒類商店顯示名稱的 Nearby Search (New) 要求:

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.primaryTypeplaces.types 新增至欄位遮罩中,讓回應包含每個地點的類型資訊,讓使用者更容易從結果中選取合適的地點。

下例是針對 "school" 類型的所有地點發出 Nearby Search (新) 要求,但排除 "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

搜尋某個區域附近的所有地點,依距離排名

以下範例顯示針對舊金山市中心某個點附近地點的 Nearby Search (New) 要求。在此範例中,您可以加入 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. 視需要展開「顯示標準參數」,並將 fields 參數設為欄位遮罩
  2. 視需要編輯要求主體
  3. 選取「執行」按鈕。在彈出式視窗中,選擇要用來提出要求的帳戶。