March 14, 2017 · technical gaming

How to create Overviewer maps from Minecraft Realms

Realms is the easiest (if not the cheapest) way to run a Minecraft server. Mojang do all the admin work for you: security, player access, backups, Herobrine protection.

Overviewer is a ridiculously cool project that generates a Google Map of your world, like this:

overviewer map example

At the moment there's no easy way to bring these things together.

This article explains how to download your world using the Realms API, and create an interactive map.

To the command line we go!

As you may know, downloading your world by itself isn't too difficult - you can click around on this screen like some kind of animal:

Minecraft backups screen

We will not stoop to this level since we are Serious Admins With Things To Do. We'll use the Linux command line to automate everything.

I've done the hard work of getting the (undocumented!) Realms API working, and made simple tools to make it easy.

What you need

To get world data and make the map, you need:

Once you have your map, you can zip it and send it to fellow players using cloud storage like Google Drive. Or if you have a webserver, you can host the map like I do at - see below for instructions.

1. Setup: Get the scripts

We need to download the scripts from the github repository.

If you have git, pull them from github:

$ git clone
$ cd minecraft-tools

If you don't have git, download the zip and extract it.

2. Setup: Install tools

We need a tool that sends HTTP requests (httpie), and another that parses JSON documents (jq). Let's install them:

$ sudo apt-get update
$ sudo apt-get install -y httpie jq

Next, we need Overviewer itself:

$ sudo apt-get install -y software-properties-common
$ sudo apt-add-repository 'deb ./'
$ http --body | sudo apt-key add -
$ sudo apt-get update
$ sudo apt-get install -y minecraft-overviewer

Finally, if this computer doesn't have Minecraft installed, you'll need to download the free client jar containing the textures Overviewer needs:

$ sudo apt-get install -y curl
$ overviewer/

3. Get your world data

Now we can log into Minecraft using their authentication API:


Note: We're using the source command to set variables in our environment. These values are picked up by the other tools. You can read about this approach on stackoverflow.

Next, download our world:

$ ./

This downloads the current world data to the current directory as world.tar.gz.

Note: If the Realms API is busy at that moment, you may see a Retry again later message. If this happens, just keep trying until it works.

Last, let's extract our world data:

$ mv world.tar.gz /tmp
$ cd /tmp
$ gunzip world.tar.gz
$ tar xvf world.tar

Now the data's ready to process at /tmp/world.

4. Make the map

We just need to start Overviewer, using the config file I provided in minecraft-tools/overviewer:

$ cd -
$ --config=overviewer/

This will pick up the data in /tmp/world, and create a new map in /tmp/world-map.

5. We're done

Open up /tmp/world-map/index.html in your browser. Amazing!

Making it automatic

Whenever you need to update your map, just repeat steps 3 and 4.

Optional: Host the map on a webserver

To host the map on a webserver, you need an API key from Google. If the key isn't added correctly to the index.html file, the map won't display. Follow the steps on their site to get one.

Then to update your index.html with the new key, use:

$ overviewer/ /tmp/world-map YOUR_API_KEY

Whenever you generate a new map, remember to add the key.


I hope you find this stuff as useful as I do. I would love to see the maps you've created - leave a comment with a link!

If you'd like to contribute to the code, please raise issues or pull requests on Github - or just leave a comment. Thanks!

Appendix of interesting things

Things I didn't realise about Realms

IP blacklisting

It appears that attempts to log in from certain computers are just not allowed by the Minecraft authentication server. For example, I can login from my PC, but not from my DigitalOcean server.

If you can help me understand what's going on here I'd love to know.

Get notified when I post

Comments powered by Disqus