本頁面由 Cloud Translation API 翻譯而成。

使用範例地點 ID 驗證 Places 洞察資料

本文將說明如何使用「地點洞察」的範例地點 ID 資料、地點計數函式，以及目標地點詳細資料查詢，建立結果的信賴度。

倫敦地點的密度熱視圖，並疊加個別標記來驗證統計資料。

架構模式

這個架構模式提供可重複的工作流程，有助於縮小高階統計分析與基準真相驗證之間的差距。結合 BigQuery 的規模和 Places API 的精確度，即可放心地驗證分析結果。這項功能特別適合用於選址、競爭對手分析和市場研究，因為這些領域非常重視資料的準確性。

這個模式的核心包含四個重要步驟：

執行大規模分析：在 BigQuery 中使用 Places Insights 的地點計數函式，分析整個城市或區域等廣大地理範圍的地點資料。
分離及擷取樣本：找出感興趣的區域 (例如高密度「熱點」)，並從函式提供的 sample_place_ids 中擷取。
擷取實際詳細資料：使用擷取的地點 ID，對 Place Details API 進行目標式呼叫，擷取每個地點的豐富實際詳細資料。
建立合併的視覺化效果：在初始的高階統計地圖上疊加詳細地點資料，以視覺化方式驗證匯總計數是否反映實際情況。

解決方案工作流程

這個工作流程可協助您縮小巨觀趨勢與微觀事實之間的差距，首先，您會看到廣泛的統計資料，然後有策略地向下鑽研，透過具體的實際案例驗證資料。

使用地點洞察資料大規模分析地點密度

首先，請先瞭解整體情況。不必擷取數千個個別的興趣點 (POI)，只要執行單一查詢，即可取得統計摘要。

Places Insights PLACES_COUNT_PER_H3函式最適合用於此用途。這項工具會將搜尋點數量匯總到六邊形格線系統 (H3)，方便您根據特定條件 (例如營業中且評分高的餐廳)，快速找出密度高或低的區域。

查詢範例如下。請注意，您必須提供搜尋區域的地理位置。您可以透過公開資料集 (例如 Overture Maps 資料 BigQuery 公開資料集)，擷取地理邊界資料。

如要經常使用開放式資料集邊界，建議您將其具體化為自己專案中的資料表。這可大幅降低 BigQuery 成本，並提升查詢效能。

-- This query counts all highly-rated, operational restaurants
-- across a large geography, grouping them into H3 cells.
SELECT *
FROM
  `places_insights___gb.PLACES_COUNT_PER_H3`(
    JSON_OBJECT(
      'geography', your_defined_geography,
      'h3_resolution', 8,
      'types', ['restaurant'],
      'business_status', ['OPERATIONAL'],
      'min_rating', 3.5
    )
  );

這項查詢的輸出內容會提供 H3 格狀單元資料表，以及每個格狀單元內的地點數量，做為密度熱視圖的基礎。

BigQuery 查詢結果的表格，顯示 h3_cell_index、count 和 sample_place_ids 的資料欄。

找出熱點並擷取樣本地點 ID

PLACES_COUNT_PER_H3 函式的結果也會傳回 sample_place_ids 陣列，每個回應元素最多可包含 250 個地點 ID。這些 ID 是從匯總統計資料連結至個別地點的連結，可提供相關資訊。

系統可能會先從初始查詢中找出最相關的儲存格。舉例來說，您可以選取前 20 個計數最高的儲存格。然後，從這些熱點將 sample_place_ids 合併成單一清單。這份清單是精選的範例，包含最相關區域中最有趣的 POI，可協助您準備進行目標驗證。

如果您使用 pandas DataFrame 在 Python 中處理 BigQuery 結果，擷取這些 ID 的邏輯很簡單：

# Assume 'results_df' is a pandas DataFrame from your BigQuery query.

# 1. Identify the 20 busiest H3 cells by sorting and taking the top results.
top_hotspots_df = results_df.sort_values(by='count', ascending=False).head(20)

# 2. Extract and flatten the lists of sample_place_ids from these hotspots.
# The .explode() function creates a new row for each ID in the lists.
all_sample_ids = top_hotspots_df['sample_place_ids'].explode()

# 3. Create a final list of unique Place IDs to verify.
place_ids_to_verify = all_sample_ids.unique().tolist()

print(f"Consolidated {len(place_ids_to_verify)} unique Place IDs for spot-checking.")

如果使用其他程式設計語言，也可以套用類似的邏輯。

使用 Places API 擷取真實資料詳細資料

有了整合的地點 ID 清單，您現在可以從大規模分析轉為擷取特定資料。您將使用這些 ID 查詢 Place Details API，取得每個範例地點的詳細資訊。

這是重要的驗證步驟。Places Insights 會告訴您某個區域內有多少餐廳，而 Places API 則會告訴您這些餐廳是哪些，並提供餐廳名稱、確切地址、經緯度、使用者評分，甚至還會直接連結至 Google 地圖上的餐廳位置。這項功能會豐富範例資料，將抽象 ID 轉換為具體可驗證的地點。

如需 Place Details API 提供的完整資料清單，以及擷取資料的相關費用，請參閱 API 說明文件。要求中會設定 FieldMask，以控管 API 傳回的資料。

使用 Python 用戶端程式庫向 Places API 發出特定 ID 的要求，看起來會像這樣：

# A request to fetch details for a single Place ID.
request = {"name": f"places/{place_id}"}

# Define the fields you want returned in the response as a comma-separated string.
fields_to_request = "displayName,formattedAddress,location,googleMapsUri"

# The response contains ground truth data.
response = places_client.get_place(
    request=request,
    metadata=[("x-goog-fieldmask", fields_to_request)]
)

如需更多詳細資料，請參閱 Places API (新版) 用戶端程式庫範例。

建立用於驗證的合併圖表

最後一個步驟是將兩個資料集整合到單一檢視畫面。這項功能提供直覺式方法，可立即檢查初步分析結果。圖表應有兩個圖層：

基礎圖層：根據初始 PLACES_COUNT_PER_H3 結果產生的等值線圖或熱度圖，顯示地理區域內地點的整體密度。
頂層：一組個別標記，代表每個範例搜尋點，使用上一個步驟中從 Places API 擷取的精確座標繪製。

建構這個合併檢視區塊的邏輯會顯示在下列虛擬程式碼範例中：

# Assume 'h3_density_data' is your aggregated data from Step 1.
# Assume 'detailed_places_data' is your list of place objects from Step 3.

# Create the base choropleth map from the H3 density data.
# The 'count' column determines the color of each hexagon.
combined_map = create_choropleth_map(
    data=h3_density_data,
    color_by_column='count'
)

# Iterate through the detailed place data to add individual markers.
for place in detailed_places_data:
    # Construct the popup information with key details and a link.
    popup_html = f"""
    <b>{place.name}</b><br>
    Address: {place.address}<br>
    <a href="{place.google_maps_uri}" target="_blank">View on Maps</a>
    """

    # Add a marker for the current place to the base map.
    combined_map.add_marker(
        location=[place.latitude, place.longitude],
        popup=popup_html,
        tooltip=place.name
    )

# Display the final map with both layers.
display(combined_map)

將特定實況標記疊加在高階密度地圖上，即可立即確認標示為熱點的區域是否確實包含您正在分析的大量地點。這項視覺化確認功能可大幅提升資料導向結論的可信度。

結論

這個架構模式提供強大且有效率的方法，可驗證大規模的地理空間洞察資料。運用 Places Insights 進行大規模分析，並使用 Place Details API 進行有目標的實地驗證，即可建立強大的意見回饋迴路。這可確保您在零售店選址或物流規劃等策略決策時，是根據具有統計顯著性且可驗證準確性的資料。

後續步驟

請參閱其他地點計數函式，瞭解如何回答不同的分析問題。
請參閱 Places API 說明文件，瞭解可要求哪些其他欄位，進一步豐富分析內容。

貢獻者

Henrik Valve | DevX 工程師