Live McDonald's Globe

An interactive 3D globe that plots every McDonald's restaurant on Earth, powered by live OpenStreetMap data.

• Live data — queries the public Overpass API for every OSM node/way/relation tagged as a McDonald's (brand:wikidata=Q38076).
• Always renders — if Overpass is unreachable or slow, the app transparently falls back to a curated dataset bundled with the app so the globe is never empty.
• Snappy — the API response is edge-cached for 6 hours (configurable), and the UI has a search-as-you-type filter, top-country stats, and deep links to OSM and Google Maps.
• 3D — built on react-globe.gl + Three.js with auto-rotate, damped orbit controls, atmosphere glow, and click-to-zoom.
• Deployable in one click on Vercel.

McDonald's, the Golden Arches, and related trademarks are property of McDonald's Corporation. This project is an independent, non-commercial visualization of publicly-available OpenStreetMap data.

---

One-click deploy

No environment variables are required. You can optionally set:

Variable	Default	Purpose
OVERPASS_URL	https://overpass-api.de/api/interpreter	Primary Overpass mirror. The app also rotates through overpass.kumi.systems and overpass.private.coffee on failure.
MCD_CACHE_SECONDS	21600 (6 hours)	How long Vercel's edge should cache /api/mcd responses.
NEXT_PUBLIC_SITE_URL	unset	Public URL used for social previews.

---

Local development

Requires Node.js 18.17+.

git clone https://github.com/dpk-jr/live-mcd-globe.git
cd live-mcd-globe
npm install
npm run dev

Open http://localhost:3000.

Useful scripts:

npm run dev         # start the dev server
npm run build       # production build
npm run start       # run the production build
npm run lint        # eslint
npm run typecheck   # tsc --noEmit

Forcing the fallback dataset

Handy while working on the UI without hammering the live API:

http://localhost:3000/api/mcd?fallback=1

---

How it works

┌─────────────┐       ┌──────────────────────┐       ┌───────────────────┐
│  Browser    │ ──▶   │  /api/mcd (Next.js)  │ ──▶   │  Overpass API     │
│  react-globe│       │  - 3 mirror rotation │       │  (OpenStreetMap)  │
│  .gl        │ ◀──   │  - 25s timeout       │ ◀──   │                   │
└─────────────┘       │  - fallback dataset  │       └───────────────────┘
                      │  - edge cache 6h     │
                      └──────────────────────┘

Overpass query

[out:json][timeout:50];
(
  nwr["amenity"="fast_food"]["brand:wikidata"="Q38076"];
  nwr["amenity"="fast_food"]["brand"~"McDonald",i];
);
out center tags 40000;

• Uses the canonical McDonald's Wikidata ID (Q38076) as the primary signal.
• nwr matches nodes, ways, and relations (some stores are mapped as building footprints).
• out center returns a single lat/lng for non-point features.

File layout

live-mcd-globe/
├─ app/
│  ├─ api/mcd/route.ts        # Overpass proxy + fallback
│  ├─ globals.css             # Tailwind + HUD styles
│  ├─ icon.svg                # Favicon
│  ├─ layout.tsx
│  └─ page.tsx                # Client page, wires Globe + HUD
├─ components/
│  ├─ Globe.tsx               # react-globe.gl wrapper
│  └─ Hud.tsx                 # Overlay (stats, search, info card)
├─ lib/
│  ├─ fallback-locations.ts   # Curated offline dataset
│  ├─ overpass.ts             # Overpass QL + parser
│  ├─ types.ts
│  └─ useLocations.ts         # Client-side fetch hook
├─ next.config.mjs
├─ tailwind.config.ts
├─ vercel.json
└─ package.json

---

Tuning

• Globe textures are loaded from unpkg.com/three-globe/example/img/. Swap the URLs in components/Globe.tsx to use your own textures.
• Auto-rotate speed and camera bounds live in Globe.tsx (see the controls block).
• Point styling (color, altitude, radius) are controlled on the <GlobeGL> props.

---

Attribution

• Live location data © OpenStreetMap contributors, available under the ODbL.
• Night-earth and topology textures ship with three-globe by Vasco Asturiano.

---

License

MIT. McDonald's trademarks are not covered by this license.