Load Google Maps API key from a .env file

- Add python-dotenv and call load_dotenv() in traveltimes.py before reading
  GOOGLE_MAPS_API_KEY (exported env vars still take precedence).
- Add .env.example template; the real .env stays gitignored.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -0,0 +1,3 @@
+# Copy this file to `.env` and fill in your real key. `.env` is gitignored.
+# Required: Google Maps API key with the Routes API enabled.
+GOOGLE_MAPS_API_KEY=your-api-key-here

pyproject.toml

@@ -8,6 +8,7 @@ dependencies = [
     "numpy>=2.2.4",
     "pandas>=2.2.3",
     "pandas-stubs>=2.2.3.250308",
+    "python-dotenv>=1.2.2",
     "requests>=2.32.3",
     "tqdm>=4.67.1",
     "types-requests>=2.32.0.20250328",

src/tatami/traveltimes.py

@@ -1,9 +1,14 @@
 import pandas as pd
 import requests
 import os
+from dotenv import load_dotenv
 from tatami.classes import Participant, Group
 
 
+# Load secrets from a local .env file if present. Existing environment variables
+# take precedence (override=False), so an exported GOOGLE_MAPS_API_KEY still wins.
+load_dotenv()
+
 GOOGLE_MAPS_API_URL = (
     "https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix"
 )

uv.lock

@@ -211,6 +211,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" },
 ]
 
+[[package]]
+name = "python-dotenv"
+version = "1.2.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/ed/0301aeeac3e5353ef3d94b6ec08bbcabd04a72018415dcb29e588514bba8/python_dotenv-1.2.2.tar.gz", hash = "sha256:2c371a91fbd7ba082c2c1dc1f8bf89ca22564a087c2c287cd9b662adde799cf3", size = 50135, upload-time = "2026-03-01T16:00:26.196Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" },
+]
+
 [[package]]
 name = "pytz"
 version = "2025.2"
@@ -277,6 +286,7 @@ dependencies = [
     { name = "numpy" },
     { name = "pandas" },
     { name = "pandas-stubs" },
+    { name = "python-dotenv" },
     { name = "requests" },
     { name = "tqdm" },
     { name = "types-requests" },
@@ -295,6 +305,7 @@ requires-dist = [
     { name = "numpy", specifier = ">=2.2.4" },
     { name = "pandas", specifier = ">=2.2.3" },
     { name = "pandas-stubs", specifier = ">=2.2.3.250308" },
+    { name = "python-dotenv", specifier = ">=1.2.2" },
     { name = "requests", specifier = ">=2.32.3" },
     { name = "tqdm", specifier = ">=4.67.1" },
     { name = "types-requests", specifier = ">=2.32.0.20250328" },