GeoGuess: a self-hostable Street View geography game with rooms

A guessing game that has to pay for its own map tiles

GeoGuess is an open-source geography game with Google Map StreetView, and the repository description says it can be played solo or with friends simultaneously. The live site is at geoguess.games and a demo instance is at demo.geoguess.games.

The rules are simple. It is a free and lazy geoguess game, and players compete over how close they can guess random locations in five rounds. The location is a random point on a Street View panorama, the player drops a marker, and the score is the distance.

The interesting part is the constraint the project runs into, which the README states plainly. Because of the Google Map API price, the maintainers are not able to deploy a server with unlimited access. The workaround is stated as a feature rather than an apology: you can deploy your own game server and play the game unlimitedly and free.

That is the shape of the project. A hosted demo for evaluation, and a self-hosting path for anyone who needs the game to run without a per-request ceiling on map tiles. Everything else in the repository, the Dockerfile, the compose file and the Netlify and Vercel configuration, supports one or the other of those two uses.

The project is MIT licensed, its primary language is Vue, and the repository is not archived with the last push on 2026-08-03. The release tags are place names, v1.1.0 for Suez in Egypt from 2024-06-28, v1.0.0 for London from 2022-08-01 and v0.7.2 for Suakin in Sudan from 2021-12-29, which is a nice touch for a game about geography.

Rooms instead of accounts

The multiplayer model is the simplest thing in the project and it is worth understanding precisely, because it determines what the game can and cannot do.

You can play multiplayer with your friends, up to five friends. The first player creates a room and decides the room size. Other players type the same room name the first player created, and the game starts. That is the entire room mechanism: a name that players agree on, and a size that the creator sets.

There is no invitation link, no lobby, no persistent identity and no per-player account in the game layer. A player is whoever typed the right room name at the right time.

That has real consequences for how you would use it. A classroom of twenty students needs five rooms, or a room of five at a time. A team workshop works well because everyone is in the same physical or chat space. A public, long-lived game with strangers in it does not fit this model, and that is consistent with the rest of the project, which is aimed at small groups and self-hosted instances rather than at being a service.

The rest of the feature list is short: a multiplayer game, PWA and responsive design, a custom map in geojson format, history, and score. The PWA point matters more than it sounds, since a progressive web app installs on a phone home screen and runs offline for the shell, which is a sensible choice for a game that people play on their own devices.

Vue 2, Vuetify and Firebase underneath

The package manifest describes the stack in detail, and it is a 2021-vintage but complete client application.

The front end is Vue 2.7 with Vue Router 3, Vuex 3 and Vuetify 2 for the component library, plus vue-i18n for translations and vue-axios for HTTP. The map is gmap-vue, and the geometry work, which is what turns a random point into a plausible random point on a map, comes from the turf packages: bbox, boolean-point-in-polygon, distance and helpers, together with a package called random-position-in-polygon that does the actual random placement. axios-cache-adapter is there to cache the tile responses, and register-service-worker handles the PWA behaviour. There is also vue-clipboard2 and vue-country-flag, the latter for showing a country name next to a score.

The backend is Firebase, pinned at version 8.10.1, which is how rooms and scores are synchronised between players.

The build and test tooling is modern for a Vue 2 project. The scripts run vue-cli-service for serve, build and lint, jest with the Vue 2 test utils and vue2-jest for unit tests, and cypress for end to end tests, with the test script running lint, unit and end to end in sequence. Mutation testing with Stryker is there as well, configured through stryker.conf.json, and the README carries a badge for the mutation testing report, which is a level of rigour in a game project that is worth noting.

The repository layout confirms the multi-target approach: a Dockerfile, a docker-compose.yml, a netlify.toml and a vercel.json sit alongside the Vue source in src/, the public assets, the tests and the scripts directory, and a crowdin.yml sits next to a scripts directory for the localisation workflow.

Running your own instance with Docker Compose

The deployment story is the part that matters if you want to run this yourself, and the compose file is short enough to read in full:

version: '2.1'

services:
  geoguess:
    build: .
    # image:
    environment:
      #- VUE_APP_PUBLIC_PATH=/
      - VUE_APP_API_KEY=myapi
      #- VUE_APP_FIREBASE_API_KEY=myapi
      #- VUE_APP_FIREBASE_PROJECT_ID=myid
      #- VUE_APP_FIREBASE_MESSAGING_SENDER_ID=senderid
      #- VUE_APP_FIREBASE_APP_ID=appid
      #- VUE_APP_FIREBASE_MEASUREMENT_ID=measurment
      #- VUE_APP_FIREBASE_AUTH_DOMAIN=auth
      #- VUE_APP_FIREBASE_DATABASE_URL=db
      #- VUE_APP_STORAGE_BUCKET=bucket
    ports:
      - 3000:80

Note what the file does and does not set. The service builds from the local Dockerfile, publishes port 3000 on the host mapped to port 80 in the container, and the only environment variable that is actually set is VUE_APP_API_KEY with a placeholder value of myapi. Every Firebase variable is present but commented out.

That is not an oversight, it is a prompt to you. The Firebase configuration is what a deployment needs, and the placeholders are there to show the names. The build image is a node lts alpine builder that installs the project and runs the build, with the environment variables rewritten at build time so the compiled bundle carries the right configuration, and the runtime image is an nginx alpine server serving the built dist directory with the project's own nginx.conf, started through the entrypoint.sh script.

The one line you must change before anything works is the API key. A literal myapi will not authenticate against Google Maps, and the failure will look like a blank map rather than a configuration error.

What the project owes its fork and its community

The README says the game was forked from GeoGuess Master Web by spider-hand, and that is the honest starting point for anyone evaluating the codebase.

It is a Vue application with a map, a random point generator, a Firebase room synchronisation layer and a distance-based scoring rule, and the parts that are specific to this project are the room flow with a creator choosing the size, the five-round structure, the custom geojson map option, the history and score features, and the PWA packaging.

The contributors list in the README is long and the roles are broken out by contribution type, with separate entries for code, design, translation, bug reports and review. The translation entries in particular point to a Crowdin setup, with crowdin.yml in the repository root and a Crowdin badge for the localised project, and the site carries a vue-i18n dependency. A game about guessing places is a reasonable thing to want in many languages, and the localisation effort is one of the more visible signs that the project is used by more than its authors.

The project also maintains a Discord server, and the README points to a deployment guide hosted on the project site rather than duplicating it in the repository. The changelog lives in CHANGELOG.md, and there is a CODE_OF_CONDUCT.md and a CONTRIBUTING.md.

One inconsistency is worth flagging for anyone checking the licence. The GitHub licence badge in the README links to a repository path that names a different project, BilelJegham/Geoguess-2, rather than the GeoGuess organisation, and the repository itself has a LICENSE file. The project is described as MIT licensed, and the licence file is the authority, but a badge pointing at another repository is a small sign that the project was forked and renamed, which is consistent with the stated origin.

Where GeoGuess is the wrong choice

The first limitation is the cost model, and it is the project's own stated reason for the self-hosting path. The hosted demo cannot offer unlimited access because of the Google Maps API price, and a classroom of thirty students guessing five hundred locations is exactly the workload that a pay per load API punishes. Anyone planning serious use is deploying their own instance, which means a Google Maps API key of their own, a server, and the fact that the bill still exists, just on their account.

The second limitation is the room model. A named room of up to five players with no accounts is the right design for a group of friends in a chat and the wrong design for anything public. There is no moderation layer, no reporting, no way to see who was in the room last week, and no protection against someone guessing a room name and joining a game in progress. If you want to run this for strangers, you are building that yourself on top of a Firebase project.

The third limitation is the stack's age. Vue 2.7 with Vuetify 2 and Vue Router 3 is in maintenance mode in the wider ecosystem, and the Firebase client is pinned to version 8.10.1, which predates the current Firebase SDK line. The project still builds and ships a test suite, but a fork that intends to live for years will be working with a stack that its ecosystem has moved past.

The real alternative for a classroom is a purpose-built quiz platform, and the difference in approach is instructive. A quiz platform gives you the question set, the scoring, the leaderboard and the analytics, and it runs on infrastructure someone else maintains. GeoGuess gives you something a quiz platform will not: a game, built on real Street View imagery, where the guessing is the point rather than a delivery mechanism for a multiple choice. The second is more work to run, and the first is a better tool if your goal is a quiz rather than a game. For a team that wants the game and has an API key and a Docker host, GeoGuess is the smaller project by a wide margin.

Editorial conclusion

Adopt GeoGuess if you want a browser geography game to run in a classroom, a team workshop or a LAN event, since the Docker image and the compose file are enough to stand up your own instance with no Google Maps API cap. Do not adopt it if you need a production multiplayer service, because the rooms are a lightweight mechanism with no accounts beyond Firebase, and do not assume the hosted demo will be reliable, since it exists under a stated API budget constraint. Before you deploy, put a real key in the environment file rather than the placeholder, and read the deployment guide the README points at, since the compose file ships with the Firebase variables commented out.

Frequently asked questions

Official sources

1. GeoGuess/GeoGuess on GitHub
2. License: MIT
3. Project website
4. README
5. Releases