搜尋附近地點 (新)

搜尋附近 (新版) 要求會採用一或多個地點類型,然後傳回 指定區域。指定一或多個資料類型的欄位遮罩 必填。Nearby Search (新版) 僅支援 POST 要求。

API Explorer 可讓您發出即時要求,以便熟悉 API 以及 API 選項:

試試看!

嘗試互動式 示範,查看地圖上的「附近地點搜尋」(新版) 結果。

Nearby Search (新版) 要求

Nearby Search (新版) 要求是 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 (新版) 的回應

Nearby Search (新版) 會傳回 做為回應的 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 (基本) SKU

      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」 存取地點的文字名稱。

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

      places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri

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

      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

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

    一個地點只能有單一主要類型類型 與表 A 相關聯的 基礎架構舉例來說,主要類型可能是 "mexican_restaurant""steak_house"。使用 includedPrimaryTypesexcludedPrimaryTypes可篩選以下項目的結果 地點的主要類型

    一個地點也可以有類型及多個類型值 表 A 相關聯的資源例如,餐廳可能會有下列類型: "seafood_restaurant""restaurant""food""point_of_interest""establishment"。使用「includedTypes」 和 excludedTypes,篩選與指定類別相關聯的類型清單結果 特定地點。

    指定一般主要類型時,例如 "restaurant""hotel",回應可以包含比主要類型更明確的地點 以及指定的 IP 位址舉例來說,您指定納入了主要類型 "restaurant"。接著,回應就能包含主要類型為 "restaurant",但回應中也可以包含更具體的地點 主要類型,例如 "chinese_restaurant""seafood_restaurant"

    如果搜尋同時指定了多種類型限制,則只有地點 符合所有限制的條件都會傳回。舉例來說,假設您指定 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, 傳回的地點提供 "restaurant" 相關服務,但主要並非營運 做為 "steak_house"

    includedTypes

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

    excludedTypes

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

    如果您同時指定 includedTypes ( 例如 "school") 和 excludedTypes (例如 "primary_school"),那麼 回應包含歸類為 "school" 但不接受的地點 "primary_school"。回應包含符合至少一個 includedTypes excludedTypes

    出現任何衝突的類型時,例如兩種類型都出現在 includedTypes 中 和 excludedTypes,會傳回 INVALID_REQUEST 錯誤。

    includedPrimaryTypes

    以逗號分隔的表 A 要加入的主要地點類型清單 搜尋內容

    excludedPrimaryTypes

    要排除的主要地點類型清單 (以半形逗號分隔) 特定內容

    如果主要類型有相衝突的主要類型, includedPrimaryTypesexcludedPrimaryTypes, 傳回 INVALID_ARGUMENT 錯誤。

  • languageCode

    傳回結果時使用的語言。

    • 查看支援的語言清單。Google 經常 更新支援的語言,因此這份清單可能不完整。
    • 如未提供 languageCode,API 會預設為 en。如果 如果指定的語言代碼無效,API 就會傳回 INVALID_ARGUMENT 錯誤。
    • API 會盡可能提供使用者和易讀的街道地址 當地人。為達成這個目標,系統會使用以當地語言傳回街道地址 視需要轉成指令碼,以便使用者閱讀,藉此觀察慣用版本 語言。系統會以偏好語言傳回所有其他地址。地址元件為 從第一個元件中選擇,並以相同語言傳回。
    • 如果名稱未提供偏好語言,API 會使用最接近的項目。
    • 偏好語言不太會影響 API 選擇的結果集 傳回的項目和傳回順序。地理編碼器會解讀縮寫 視語言而定,例如街道類型的縮寫或同義詞 在某一種語言中可能有效,但在另一種語言則無效。
  • maxResultCount

    指定要傳回的地點結果數量上限。必須介於 1 至 20 (預設) 值,含首尾。

  • rankPreference

    要使用的排名類型。如果省略這個參數,結果會按照熱門程度排名。 可以是下列其中一項:

    • POPULARITY (預設) 依據熱門程度將結果排序。
    • DISTANCE 依地點與 指定位置。
  • regionCode

    用於設定回應格式的區碼,以 雙字元 CLDR 代碼值。沒有預設值。

    如果回應中 formattedAddress 欄位的國家/地區名稱與 regionCodeformattedAddress 中省略了國家/地區代碼。 這個參數不會影響 adrFormatAddress,一律包含國家/地區 名稱或 shortFormattedAddress 上 (絕不會包含此項目)。

    大多數 CLDR 代碼 ISO 3166-1 代碼 有一些值得注意的例外情況舉例來說,英國的 ccTLD 是 「uk」(.co.uk),但 ISO 3166-1 代碼卻是「gb」(技術上來說 「大不列顛暨北愛爾蘭聯合王國」)。 這個參數會根據適用法律影響結果。

Nearby Search (新版) 範例

尋找特定類型的地點

以下範例顯示,對螢幕執行的 Nearby Search (新版) 要求。 這個方圓 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"
      }
    },
...
}

尋找多種類型的地點

以下範例顯示針對 所有便利商店和酒類商店的顯示名稱,半徑 1000 公尺以內 指定的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.primaryTypeplaces.types 新增至欄位遮罩 ,就能在回應中納入每個地點的類型資訊,方便使用者選取 找出適合的地點

以下範例顯示所有地點的 Nearby Search (新版) 要求 類型為 "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

搜尋某地區附近的所有地點 (依距離排名)

以下範例顯示地點搜尋 (新版) 的 Nearby Search (新版) 要求 靠近舊金山的某個點。在這個範例中,您要在當中加入 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. 視需要展開「顯示標準參數」並進行設定 fields 參數 欄位遮罩
  3. 視需要編輯「要求主體」
  4. 選取「執行」按鈕。在彈出式視窗中,選擇要用來提出請求的帳戶。
  5. 在 API Explorer 面板中,選取展開圖示 展開 API Explorer。,展開「API Explorer」視窗。