Merge pull request #7 from YuWei-CH/GMAP-Support

Use GMAP as map and routing

Author: YuWei-CH

.env.example

@@ -0,0 +1,32 @@
+# EasyRelocate (repo root) — unified env file
+#
+# Copy this file to `.env` and fill in your own keys.
+# Never commit `.env` (it contains secrets).
+
+###############################################################################
+# Frontend (Vite / browser)
+###############################################################################
+# Required: Browser API key (HTTP referrer-restricted)
+VITE_GOOGLE_MAPS_API_KEY="YOUR_BROWSER_KEY"
+
+# Optional: Backend API base URL (defaults to http://localhost:8000)
+VITE_API_BASE_URL="http://localhost:8000"
+
+# Optional: Disable Google Maps loading (useful for CI)
+# VITE_DISABLE_GOOGLE_MAPS="1"
+
+###############################################################################
+# Backend (FastAPI / server)
+###############################################################################
+# Optional: Server API key (for Geocoding API server-to-server calls)
+# If you don't set this, the backend will fall back to Nominatim (OSM) for geocoding.
+GOOGLE_MAPS_API_KEY="YOUR_SERVER_KEY"
+
+# Optional: Force geocoding provider (google or nominatim)
+GEOCODING_PROVIDER="google"
+
+# Optional: Enable/disable all geocoding calls
+ENABLE_GEOCODING="1"
+
+# Optional: Database URL (default is an auto-created SQLite DB under backend/)
+# DATABASE_URL="sqlite+pysqlite:////absolute/path/to/easyrelocate.db"

.github/workflows/ci.yml

@@ -48,4 +48,7 @@ jobs:
       - name: Install dependencies
         run: npm ci
       - name: Build
+        env:
+          # CI doesn't have real Google API keys. Build should still validate typecheck + bundle.
+          VITE_DISABLE_GOOGLE_MAPS: "1"
         run: npm run build

.gitignore

@@ -19,6 +19,18 @@ node_modules/
 dist/
 .vite/
 
+# Env files (do not commit secrets)
+.env
+.env.local
+.env.*.local
+frontend/.env
+frontend/.env.local
+frontend/.env.*.local
+backend/.env
+backend/.env.local
+backend/.env.*.local
+!.env.example
+
 # Extension build artifacts
 extension/dist/
 

README.md

@@ -9,9 +9,48 @@ EasyRelocate does not scrape platforms server-side, host listings, process payme
 
 ## Repo structure
 - `backend/`: FastAPI + SQLite API
-- `frontend/`: React (Vite) web app (MapLibre + OpenStreetMap map, US-only for now)
+- `frontend/`: React (Vite) web app (Google Maps JS map + routing, US-only for now)
 - `extension/`: Chrome extension (Manifest V3) for user-side extraction
 
+## Configuration (API keys & env vars)
+EasyRelocate uses a single repo-root `.env` file for both frontend + backend.
+
+1. Copy the example:
+```bash
+cp .env.example .env
+```
+
+2. Edit `.env` and set your keys.
+
+### Frontend (Vite / browser)
+Frontend variables must start with `VITE_`:
+```bash
+# Required (browser key)
+VITE_GOOGLE_MAPS_API_KEY="YOUR_BROWSER_KEY"
+
+# Optional (defaults to http://localhost:8000)
+VITE_API_BASE_URL="http://localhost:8000"
+
+# Optional (useful for CI / keyless dev)
+# VITE_DISABLE_GOOGLE_MAPS="1"
+```
+
+### Backend (FastAPI / server)
+Backend reads standard env vars (auto-loads repo-root `.env` on startup):
+```bash
+# Optional (server key; used for /api/geocode and /api/reverse_geocode)
+GOOGLE_MAPS_API_KEY="YOUR_SERVER_KEY"
+GEOCODING_PROVIDER="google"
+
+# Optional
+ENABLE_GEOCODING="1"
+DATABASE_URL="sqlite:///easyrelocate.db"
+```
+
+### Extension (Chrome)
+The extension does not read `.env` files. Configure its API base URL in Chrome:
+Extension → **Details** → **Extension options** → “API base URL” (default: `http://localhost:8000`).
+
 ## Local dev (MVP)
 
 ### 1) Backend API
@@ -49,6 +88,14 @@ Set your workplace target by:
 
 Then open an Airbnb listing detail page (`/rooms/...`) and click “Add to Compare”.
 
+## Google Maps setup (required)
+EasyRelocate uses Google Maps Platform for:
+- **Maps JavaScript API** (frontend map)
+- **Directions API** (routing: Drive/Bus/Walk/Bike)
+- **Geocoding API** (backend address lookup; optional but recommended)
+
+See: `docs/GOOGLE_MAPS_APPROX_LOCATION.md`
+
 ## Docs
 - Platform organization: `docs/PLATFORM_ORGANIZATION.md`
 - Google maps “approx street”: `docs/GOOGLE_MAPS_APPROX_LOCATION.md`

backend/README.md

@@ -15,6 +15,14 @@ pip install -r requirements.txt
 uvicorn app.main:app --reload --port 8000
 ```
 
+### Env vars (where to put them)
+The backend reads configuration from process environment variables.
+
+EasyRelocate auto-loads a repo-root `.env` file (recommended). Copy `.env.example` → `.env`
+in the repo root and put backend env vars there.
+
+You can still override via shell exports if needed.
+
 API docs:
 - Swagger UI: `http://localhost:8000/docs`
 - OpenAPI: `http://localhost:8000/openapi.json`
@@ -37,6 +45,7 @@ Env vars:
 - `GEOCODING_USER_AGENT` (default `EasyRelocate/0.1 (local dev)`)
 - `NOMINATIM_BASE_URL` (default `https://nominatim.openstreetmap.org`)
 - `GEOCODING_TIMEOUT_S` (default `6`)
+ - `DATABASE_URL` (optional; defaults to `backend/easyrelocate.db`)
 
 ### Google setup requirements
 If you use Google geocoding (`GEOCODING_PROVIDER=google` or `GOOGLE_MAPS_API_KEY` is set):

backend/app/__init__.py

@@ -1 +1,17 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+def _load_repo_root_dotenv() -> None:
+    # backend/app/__init__.py -> backend/app -> backend -> repo root
+    repo_root = Path(__file__).resolve().parents[2]
+    env_path = repo_root / ".env"
+    if env_path.exists():
+        load_dotenv(env_path, override=False)
+
+
+_load_repo_root_dotenv()
 

backend/requirements.txt

@@ -2,3 +2,4 @@ fastapi>=0.115
 uvicorn>=0.30
 sqlalchemy>=2.0
 httpx>=0.27
+python-dotenv>=1.0

docs/GOOGLE_MAPS_APPROX_LOCATION.md

@@ -15,6 +15,31 @@ So any street-level result we show is:
 3. **Frontend** (when a listing is selected) calls reverse geocoding to display:
    - `Approx street: <road>` (clearly labeled approximate).
 
+## Where to put API keys / env vars
+### Frontend (browser) key
+Put your browser key in the repo-root `.env` file:
+```bash
+VITE_GOOGLE_MAPS_API_KEY="YOUR_BROWSER_KEY"
+```
+
+This key is used in the browser for:
+- **Maps JavaScript API** (render the map)
+- **Directions API** (routing: Drive / Bus(Transit) / Walk / Bike)
+
+### Backend (server) key
+Put your server key in the repo-root `.env` file:
+```bash
+GOOGLE_MAPS_API_KEY="YOUR_SERVER_KEY"
+GEOCODING_PROVIDER="google"
+```
+
+This key is used server-to-server for:
+- **Geocoding API** (address → lat/lng)
+- reverse geocoding lat/lng → rough location / street name
+
+### Extension
+The extension does not read `.env` files. Set its API base URL in Chrome Extension options.
+
 ## How we extract the map pin coordinates
 File: `extension/platforms/airbnb/content.js`
 
@@ -44,15 +69,15 @@ If you see an error like:
 `Google Geocoding failed with status REQUEST_DENIED: This API is not activated on your API project`
 it means the **Geocoding API is not enabled** (or billing/key restrictions are blocking it).
 
-Set these env vars before starting the backend:
+Set these env vars in the repo-root `.env` (recommended) or your shell before starting the backend:
 ```bash
-export GOOGLE_MAPS_API_KEY="YOUR_KEY"
-export GEOCODING_PROVIDER="google"
+GOOGLE_MAPS_API_KEY="YOUR_KEY"
+GEOCODING_PROVIDER="google"
 ```
 
 Optional:
 ```bash
-export GEOCODING_COUNTRY_CODES="us"
+GEOCODING_COUNTRY_CODES="us"
 ```
 
 Then run:
@@ -67,6 +92,23 @@ uvicorn app.main:app --reload --port 8000
   - Restrict by **API**: allow only **Geocoding API**
   - Optionally restrict by **IP address** (for local dev, this can be inconvenient)
 
+## Google Maps UI + routing (frontend)
+EasyRelocate’s compare page uses Google Maps Platform in the browser for:
+- **Maps JavaScript API** (render the map)
+- **Directions API** (routing: Drive / Bus(Transit) / Walk / Bike)
+
+### Frontend env var
+Add this to the repo-root `.env`:
+```bash
+VITE_GOOGLE_MAPS_API_KEY="YOUR_KEY"
+```
+
+### API requirements
+If routing fails with errors like `Route failed: REQUEST_DENIED`, ensure in Google Cloud Console:
+- Billing is enabled
+- “Maps JavaScript API” is enabled
+- “Directions API” is enabled
+
 ## Local dev env vars
 Backend env vars:
 - `GOOGLE_MAPS_API_KEY` (enables Google geocoding)

extension/README.md

@@ -11,6 +11,9 @@
 2. Click **Extension options**
 3. Set the API base URL (default: `http://localhost:8000`)
 
+Note: the extension does **not** read `.env` files. Its API base URL is stored in Chrome sync storage
+and can differ from the frontend’s `VITE_API_BASE_URL` if needed.
+
 ## Notes on Airbnb location
 Airbnb typically does **not** show precise street addresses. The extension tries to capture:
 - Lat/lng (when available in structured data / meta tags)

extension/api.js

@@ -0,0 +1,50 @@
+const DEFAULT_API_BASE_URL = 'http://localhost:8000'
+
+function storageGet(keysWithDefaults) {
+  return new Promise((resolve) => {
+    chrome.storage.sync.get(keysWithDefaults, (items) => resolve(items))
+  })
+}
+
+function storageSet(items) {
+  return new Promise((resolve) => {
+    chrome.storage.sync.set(items, () => resolve())
+  })
+}
+
+function normalizeBaseUrl(v) {
+  const raw = String(v || '').trim()
+  if (!raw) return DEFAULT_API_BASE_URL
+  return raw.replace(/\/$/, '')
+}
+
+async function getApiBaseUrl() {
+  const items = await storageGet({ apiBaseUrl: DEFAULT_API_BASE_URL })
+  return normalizeBaseUrl(items.apiBaseUrl)
+}
+
+async function setApiBaseUrl(v) {
+  const next = normalizeBaseUrl(v)
+  await storageSet({ apiBaseUrl: next })
+  return next
+}
+
+async function postJson(url, payload) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  })
+  const text = await res.text()
+  if (!res.ok) {
+    throw new Error(`${res.status} ${res.statusText}${text ? ` — ${text}` : ''}`)
+  }
+  return text ? JSON.parse(text) : null
+}
+
+async function postToApi(path, payload) {
+  const base = await getApiBaseUrl()
+  const full = `${base}${path.startsWith('/') ? '' : '/'}${path}`
+  return postJson(full, payload)
+}
+