GeoGuessr API Guide

To work on GeoGuessr maps, I created an app that would pull in data from the game using the game’s API. I had to use my browser’s console to find out what API calls the website actually makes as there is no publically accessible documentation on it.

So here’s my unofficial guide for those who wish to use the GeoGuessr API.

Notes: Most calls start with “geoguessr.com/api/” unless specified. For some of the calls, you need to be logged in, for others you don’t. The latter are indicated with italics. As I understand, there’re 2 versions of the API currently in use, 3 and 4. It is possible that in the near future a complete transition to v4 will happen and the old calls will be deprecated.

  1. v4/feed/private – entries from the “Activities” page of your profile, including game tokens. Variables: count, page.
  2. v3/profiles – info of the currently logged-in user.
  3. v4/notifications – notifications of the currently logged-in user. Returns an empty array if all the notifications have been read. Variables: count, page.
  4. v3/social/friends – friends of the currently logged-in user. Presumably, returns an empty array if the user doesn’t have friends. Variables: count, page.
  5. v3/social/friendships – shorter information on the friends of the currently logged-in user.
  6. v3/profiles/achievements – achievements of the currently logged-in user.
  7. v4/objectives – objectives of the currently logged-in user. You can also add the /unclaimed endpoint to this address.
  8. v3/social/maps/browse/personalized – personalised map for the currently logged-in user.
  9. v3/social/badges/unclaimed – unclaimed badges of the currently logged-in user.
  10. v3/social/events/unfinishedgames – unfinished games of the currently logged-in user, including the guesses, but not the rounds themselves.
  11. v3/profiles/maps – maps of the currently logged-in user (“My Maps” page).
  12. v3/likes – liked maps of the currently logged-in user (“Liked Maps” page). Variables: count, page.
  13. v4/stats/me – stats of the currently logged-in user but not what you see on your profile page.
  14. v3/profiles/stats – stats of the currently logged-in user which are displayed on the profile page.
  15. v3/subscriptions – subscriptions of the currently logged-in user.
  16. v3/accounts/signin – signs you in, your credentials must be attached as a JSON payload in the format {email: “XXXXXX@blah.com”, password: “XXXXXX”}. You might need to properly serialise JSON with your credentials, a simple string that looked like JSON didn’t do it for me.
  17. v3/accounts/signout – signs you out. Be careful, no payload is required for this operation so it signs you out as soon as you reach the endpoint.
  18. v4/trophies/<user_ID_here> – trophies of any user. If you add /case at the end, it will show only the trophies you selected for your trophy case.
  19. v3/games/<game_token_here> – insert a game token instead of the X’s to gather the information about a certain game, including its type, rounds, score, etc. Any game ever played by whatever user can be accessed with this call, provided you have the token.
  20. v3/social/maps/browse/popular/random – a random popular map.
  21. v3/challenges/daily-challenges/today OR v3/challenges/daily-challenges/previous – today’s or previous daily challenges info.
  22. v3/challenges/<challenge_token_here> – insert a challenge token instead of the X’s to gather the information about a certain challenge.
  23. v4/seasons/active/stats – stats of the current season.
  24. v3/experiments – list of GeoGuessr experiments.
  25. v3/competitions – list of GeoGuessr competitions.
  26. maps/(map name or map id) – info on maps, works with map names for official maps like “world” or “famous-places”.
  27. https://game-server.geoguessr.com/api/battle-royale/<game_ID_here> – allows seeing the stats of any BR game, provided you have the game ID.
  28. https://game-server.geoguessr.com/api/lobby/<game_ID_here> – lobby of the game, including users (even their ids and stats), type of the game, etc.
  29. https://www.geoguessr.com/api/v4/seasons/game/BattleRoyaleCountries – info valid for the current season. “BattleRoyaleCountries” can be substituted with “BattleRoyalDistance” or “BattleRoyaleDuels” to get the exact same result.
  30. https://game-server.geoguessr.com/api/duels/<duel_game_ID_here>- info on your duel game.

For some of the calls, I’m not entirely certain what the response should be as in my case they return an empty array. Additionally, I haven’t played most of the game modes yet because I mostly play country streak so my expertise might not be so deep and some of my comments might not be as extensive.

Enjoy the guide and if in the future you create anything using Geoguessr API, feel free to share your work! I’ll be sharing my app as soon as I build a decent GUI.

BONUS SOUND EFFECTS:

  1. New game
  2. Countdown
  3. Division upgrade
  4. Division downgrade
  5. Round 1
  6. Round 2
  7. Round 3
  8. Round 4
  9. Multiple damage
  10. Healing round
  11. Churchbell
  12. Game lost
  13. Game won
  14. Healing up
  15. Count healing
  16. Loadig round
  17. Loading duel round
  18. Loading duel healing round
  19. Score tie
  20. Damage up
  21. Damage crush
  22. Counting damage
  23. Slide in rows
  24. Slide in