https://github.com/codergautam/worldguessr
Free & Open source version of Geoguessr
https://github.com/codergautam/worldguessr
educational-game game geography geoguess geoguessr google-maps googlemaps-api multiplayer-game streetview web-game web-games webgame
Last synced: about 1 month ago
JSON representation
Free & Open source version of Geoguessr
- Host: GitHub
- URL: https://github.com/codergautam/worldguessr
- Owner: codergautam
- License: mit
- Created: 2024-04-14T19:46:53.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2026-01-19T06:18:48.000Z (about 1 month ago)
- Last Synced: 2026-01-19T14:32:54.344Z (about 1 month ago)
- Topics: educational-game, game, geography, geoguess, geoguessr, google-maps, googlemaps-api, multiplayer-game, streetview, web-game, web-games, webgame
- Language: JavaScript
- Homepage: https://worldguessr.com
- Size: 92.7 MB
- Stars: 405
- Watchers: 2
- Forks: 124
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-starts - codergautam/worldguessr - Free & Open source version of Geoguessr (game)
README
A free and open-source version of the popular geography game inspired by GeoGuessr. This React based project aims to provide a fun and educational way to explore the world through Google Street View imagery.
### Play now [here](https://worldguessr.com)!
#### [Join the Discord community](https://discord.gg/yenVspFmkB)
## Features
- **Random Street Views:** Experience a new location anywhere in the world on each game.
- **Multiplayer Mode:** Challenge your friends or play against random opponents in real-time.
- **Country Streaks:** Test your knowledge and see how many countries you can guess in a row.
- **Free to run:** The project is open-source and free to run on your own server. Uses the [Google Maps Streetview Embed API](https://developers.google.com/streetview/web), which is completely free compared to the costly SDK used by GeoGuessr.
## Acknowledgements
- [Leaflet](https://leafletjs.com/) for the minimap display.
- [Google Maps API](https://developers.google.com/maps) for the generous free-tier on street view imagery.
- [Vali](https://github.com/slashP/Vali) by @SlashP for generating balanced locations distributions for all countries.
- [Next.js](https://nextjs.org/) for the web application.
- All contributors who helped bring this project to life!
## Running Locally
### Prerequisites
Before you start, ensure you have the following installed:
- [Node.js](https://nodejs.org/en/) (v12.x or later)
- [npm](https://www.npmjs.com/) (v6.x or later)
- [pnpm](https://pnpm.io/) (v8.x or later)
### Installation
1. Clone the repository:
```bash
git clone https://github.com/codergautam/worldguessr.git
cd worldguessr
```
2. Install dependencies:
```bash
pnpm install
```
3. Run the development server:
```bash
pnpm run dev
```
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
## Deploying to a VPS / External Server
If you're deploying WorldGuessr on a VPS or any server with an external IP (not localhost), you **must** configure these environment variables in your `.env` file:
```bash
# Replace YOUR_IP with your server's IP address or domain
NEXT_PUBLIC_API_URL=YOUR_IP:3001
NEXT_PUBLIC_WS_HOST=YOUR_IP:3002
```
**Example with IP:**
```bash
NEXT_PUBLIC_API_URL=123.45.67.89:3001
NEXT_PUBLIC_WS_HOST=123.45.67.89:3002
```
**Example with domain (after setting up nginx):**
```bash
NEXT_PUBLIC_API_URL=api.yourdomain.com
NEXT_PUBLIC_WS_HOST=ws.yourdomain.com
```
### Quick Setup Checklist
1. **MongoDB** - Create a cluster on [MongoDB Atlas](https://www.mongodb.com/atlas) (free tier available) and add the connection string:
```bash
MONGODB=mongodb+srv://username:password@cluster.mongodb.net/worldguessr
```
2. **Google OAuth** - Create credentials at [Google Cloud Console](https://console.cloud.google.com/):
```bash
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret
```
3. **API/WS URLs** - Point to your external IP or domain (see above)
For detailed environment variable documentation, see [docs/environment-variables.md](docs/environment-variables.md).
## Contributing
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Don't forget to give the project a star! Thanks again!
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
Distributed under the MIT License. You are free to use, modify, and distribute this project for personal or commercial use. See `LICENSE.md` for more information.
## Community
Join the Discord community [here](https://discord.gg/yenVspFmkB) to discuss new features, report bugs, talk to the developers and connect with other players.
You can email me privately at gautam@worldguessr.com