Golf Map Research

# GreenSide — Golf Map Options Research
Date: April 18, 2026

---

## Current Implementation
**ArcGIS Satellite tiles** via Leaflet (react-leaflet)
- Good satellite imagery
- No golf-specific overlays (no fairways, greens, or bunkers drawn on the map)

---

## Options Evaluated

### ✅ Option 1: OpenStreetMap + Overpass API (RECOMMENDED — Implemented)
Many golf courses worldwide are mapped in OSM with tagged features:
fairways, greens, bunkers, tee boxes, water hazards.
The Overpass API lets you query these as GeoJSON polygons and overlay
them on Leaflet with color-coded fills.

- ✅ Completely free, no API key required
- ✅ Works with existing react-leaflet setup — no new dependencies
- ✅ Auto-fetches when user is near a course (uses current GPS position)
- ✅ Color-coded overlays: fairways (light green), greens (dark green),
     bunkers (sand/yellow), water hazards (blue), tee boxes (lime)
- ⚠️ Coverage varies — major US courses are well-mapped, smaller ones may be missing
- ℹ️  Same data source used by Golfshot and 18Birdies as a base layer

Implementation: Overpass API query within ~500m radius of player GPS position,
renders golf:* tagged OSM features as GeoJSON polygons on the satellite map.
Toggle button added to map controls (layers icon).

---

### Option 2: GolfCourseAPI.com
Provides hole-by-hole data (par, yardage, descriptions) for ~30,000 courses.

- ✅ Free tier: 300 requests/day
- ✅ Structured hole data (par, yardage, handicap)
- ⚠️ No visual map overlays or polygons — data only
- 💰 Pro: $6.99/month (10,000 req/day), Enterprise: $19.99/month
- 🔗 https://golfcourseapi.com/

Best used for: enriching hole detail cards alongside the map.

---

### Option 3: Mapbox
Custom styled maps with sharper satellite imagery than ArcGIS.

- ✅ Beautiful, crisp satellite imagery
- ✅ Custom map styles possible
- ⚠️ Requires API key and account setup
- 💰 Free tier: 50,000 map loads/month, then pay-as-you-go
- ℹ️  Would still need OSM/Overpass data for golf-specific overlays
- 🔗 https://mapbox.com/

Best used for: premium visual quality upgrade if the app scales.

---

### Option 4: Google Maps Platform
The sharpest satellite imagery available. Used by premium golf apps.

- ✅ Best satellite image quality overall
- ✅ Familiar UI to most users
- ⚠️ Requires API key and billing account
- 💰 Expensive at scale — ~$7 per 1,000 map loads after free credits
- ℹ️  Would still need separate golf overlay data source
- 🔗 https://developers.google.com/maps

Best used for: if budget allows and image quality is top priority.

---

## Decision

Implemented **Option 1 (OSM + Overpass API)** because:
1. Zero cost — no API keys, no billing
2. No new npm dependencies needed
3. Integrates seamlessly with existing react-leaflet map
4. Provides genuine golf-specific visual overlays (fairways, greens, bunkers)
5. Same data used by top golf GPS apps

---

## Future Considerations

- Combine Option 1 (OSM overlays) with Option 2 (GolfCourseAPI) for hole data cards
- Upgrade satellite layer to Mapbox if image quality becomes a concern
- Cache Overpass API results to reduce repeat queries on the same course
- Add hole number labels to fairway overlays using OSM ref tags

---

*Document generated from GreenSide app — Admin reference only*