GeoGuessr.im

GeoGuessr.im is a web-based geography guessing game that drops you into a random Street View panorama somewhere on Earth and challenges you to pinpoint your location on the map. The closer your guess, the higher your score—making it a fun way to sharpen your geography skills while virtually exploring the planet.

🌐 Play the live game ›

Features

• World-wide exploration – get placed in real Street View scenes from every corner of the globe
• Multiple game modes – ramp up the difficulty or limit movement to test different skills
• Interactive 360° navigation – look around, move, and zoom just like you would in Google Maps
• Scoring & leaderboards – earn points based on distance accuracy and compare with friends
• Educational tips – learn to use language, climate, road signs, and the sun’s position as clues
• Responsive design – optimized for both desktop and mobile play

Tech Stack

| Layer | Technology | |------------------|------------------------------------| | Front-end | React 18 + Vite + TypeScript | | Styling | Tailwind CSS | | Maps & Imagery | Google Maps JavaScript API (Street View + Static Maps) | | State Management | Zustand | | Testing | Vitest & Playwright | | Hosting | Netlify (static SPA deployment) |

Note
If you’re forking the project you’ll need your own Google Maps API key with Street View & Maps JavaScript enabled.

Getting Started

# 1. Clone the repo
git clone https://github.com/your-username/geoguessr.im.git
cd geoguessr.im

# 2. Install dependencies
pnpm install         # or npm install / yarn

# 3. Add env vars
cp .env.example .env         # then edit the file
# VITE_GOOGLE_MAPS_API_KEY=YOUR_KEY_HERE

# 4. Start a dev server
pnpm dev
# open http://localhost:5173

To create a production build:

pnpm build   # outputs to /dist

You can serve the built files locally with:

npx serve -s dist

Roadmap

• [ ] Multiplayer lobbies with real-time chat
• [ ] Daily challenge seed & shareable links
• [ ] Achievements and badges
• [ ] Offline (PWA) support
• [ ] OpenStreetMap / Mapillary fallback for regions without Street View

Contributing

1. Fork the repository and create your branch: git checkout -b feat/my-feature
2. Commit your changes using Conventional Commits
3. Push to the branch: git push origin feat/my-feature
4. Open a Pull Request describing your changes

All contributions—code, bug reports, and feature requests—are welcome!

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgements

• Inspired by the original GeoGuessr game
• World map data © OpenStreetMap contributors
• Icons by Lucide

Made with ❤️ by smallflykoo