🗺️ Google Maps 地點搜尋 Web 服務

原始 Notebook 探索已保留於 maps.ipynb。本專案已升級為具備 Web 介面的地點搜尋服務。

專案架構

Google_maps_API/
├── backend/
│   ├── main.py          # FastAPI 主程式（API 路由）
│   ├── maps_service.py  # Places API (New) 邏輯
│   ├── requirements.txt
│   └── .env.example     # API Key 範本（複製為 .env 後填入金鑰）
├── frontend/
│   ├── index.html       # 搜尋頁面
│   ├── style.css        # 響應式樣式
│   └── app.js           # 搜尋 + 地圖 + Marker + Modal 邏輯
├── maps.ipynb           # 原始 Notebook
├── .gitignore
└── README.md

---

快速啟動

1. 啟用 Google Cloud API

前往 Google Cloud Console 啟用以下 兩個 API：

API	用途
Places API (New)	後端地點搜尋（注意：不是舊版 Places API）
Maps JavaScript API	前端互動地圖顯示

2. 設定 API 金鑰限制（重要）

後端以伺服器身份呼叫 API，不能使用 HTTP 參照位址限制，否則會收到 403 API_KEY_HTTP_REFERRER_BLOCKED 錯誤。

前往 Google Cloud Console → 憑證 → 編輯 API 金鑰：

環境	建議設定
本機 / Codespaces 開發	應用程式限制選「無限制」，或「IP 位址」填入對外 IP（執行 curl -s https://api.ipify.org 取得）
正式部署	建立兩把金鑰：後端用「IP 位址限制」、前端用「HTTP 參照位址限制」

3. 設定環境變數

cp backend/.env.example backend/.env
# 編輯 backend/.env，填入金鑰：
# GOOGLE_MAPS_API_KEY=your_key_here

在 frontend/index.html 第 9 行，將 YOUR_MAPS_JS_API_KEY 替換為你的 Maps JavaScript API 金鑰。

4. 安裝後端套件

cd backend
pip install -r requirements.txt

5. 啟動後端

cd backend
uvicorn main:app --reload

後端將在 http://localhost:8000 啟動。

6. 開啟前端

瀏覽器訪問 http://localhost:8000，即可使用搜尋介面。

---

API 端點

方法	路徑	功能
GET	/	前端首頁（由後端提供靜態檔案）
GET	/search?query=台北咖啡廳	搜尋地點清單
GET	/search?query=...&location=25.03,121.56&radius=1000	指定座標與半徑搜尋
GET	/detail?place_id=...	取得單一地點詳細資訊
GET	/photo?photo_reference=...&max_width=400	取得地點照片 URL（含 API Key）
GET	/docs	FastAPI 互動式 API 文件（Swagger UI）
GET	/redoc	FastAPI API 文件（ReDoc）

---

常見錯誤排解

錯誤訊息	原因	解法
REQUEST_DENIED / LegacyApiNotActivatedMapError	使用了舊版 Places API	在 Cloud Console 啟用 Places API (New)
403 API_KEY_HTTP_REFERRER_BLOCKED	金鑰設了 HTTP 參照限制，後端無 Referer 標頭	改為 IP 位址限制或無限制
GOOGLE_MAPS_API_KEY 未設定	.env 檔案不存在或金鑰欄位為空	執行 cp backend/.env.example backend/.env 並填入金鑰

---

部署

平台	方式
Render / Railway	推送 repo，在平台設定 GOOGLE_MAPS_API_KEY 環境變數，啟動指令：uvicorn main:app --host 0.0.0.0 --port $PORT
Docker	在 backend/ 新增 Dockerfile，COPY . . 後以 uvicorn 啟動

---

原始說明（Notebook 版）

使用 Google Maps API 搜尋附近的飲料店

介紹

這個程式使用Colabn notebook編輯器 與 Google Maps API 搜尋指定位置附近的飲料店。您可以輸入您的位置坐標，設定搜尋半徑和關鍵詞，然後程式將返回附近的飲料店的名稱、地址和評分。

使用前提 需申請google maps api

API 的申請、爬 Google Map 店家資料、搞懂 API 限制

• 在這個實際案例中，我會用 Google Map API 來取得店家資料，並且存成可以分析的資料形式 (csv)
• 首先，在這之前，需要申請 Google Map API，這個過程可以讓你了解 Google 如何把 API 授權給我們
  • 步驟一：申請帳號，付款方式備妥 (不需付費，只是需要填寫付款資訊)
  • 步驟二：申請 Google Map API 金鑰 (或參考以下說明)
  • 這邊有篇文章很仔細，可以參考
• API 限制：這邊可以看到 Google Map API 的限制，我們可以先用免費的方式來使用

安裝必要的套件

請確保您已經安裝了必要的套件，可以使用以下指令安裝：

pip install -U googlemaps
pip install -U pandas

使用說明

1. 首先，請在程式中輸入您的 Google Maps API 金鑰。
2. 設定您的位置坐標 (經度和緯度)，以及搜尋半徑和關鍵詞。
3. 執行程式後，程式將返回附近的飲料店的資訊。
4. 結果將以 CSV 檔案格式下載到您的本地計算機上。

範例結果

以下是搜尋結果的範例：

注意事項

• 請確保您的 Google Maps API 金鑰有效且有足夠的配額。
• 請注意使用 Google Maps API 時的費用和限制。

希望這能幫助到您！如果您有任何問題，請隨時提問。