Where in the World?

Santa had a problem, and the problem was kids. Not that he didn’t love the children – far from it, their happiness was why he did what he did after all – but now there were more than ever of them. World population had grown to the point where there were 2.2 billion children that potentially wanted a gift, and that was a lot of mince pies to get through in one night!

To ensure that he’d have time to make all the deliveries, he’d taken the unprecedented step of installing agents in homes around the world – elves that sat on shelves – who were able to report on any problem, from waking children to adverse weather conditions, that might slow him down. Traditionally, a Shelf Elf would report by flying home each night leading up to Christmas, but on the big night itself the elf would have to report back in real time. Luckily for Santa, so many houses had internet connections that the Elf could use to report issues via a simple web form the Wise Old Elf had set up on the North Pole extranet.

This is where our hero Candy Cane comes in. Candy Cane sighed as he read the story in the latest Elf development sprint: “A proof of concept exists that displays the Shelf Elf reports on a map so that Central Elf Command can coordinate them as Santa moves around the world”. 2 points.

Should be straightforward, thought Candy Cane to himself, We agreed in estimation that all I have to do is take the location from each report and feed it to the MapBox JavaScript library, and we’ll have a nice map. Easy peasy. With Elf joy in his heart from working on something he loved, he opened up the database schema to see how to get the location from the reports table.

The joy was short lived. With a sinking heart Candy realized that the reports didn’t actually contain a location. They just contained the child’s name the Elf was responsible for: fine for giving to the magical reindeer who instinctively knew the way to every chimney top, but useless for plotting on a map.

The elf cast his gaze over the other columns, trying to figure out what to do, when his eyes settled on the IP address that the report was submitted from. Hmmm, he thought, just maybe…


GeoIP2 is the Perl interface to the MaxMind geolocation services, providing a way to map an IP address to, amongst other things, a physical location in the world – perfect for plotting Elf reports on a map based on an IP address alone. MaxMind offer the GeoLite2 databases which anyone can periodically download for free from their website to do offline geolocation.

From Perl this is relatively straightforward to use. First create the reader with the database:

Then do a lookup on an IP address:

From this model you can ask for various things, for example the location of the IP:

Or information on the nearest city:

All kinds of things that you can render on a map.


Once the hard work is out of the way, Candy Cane had the relatively simple job of rendering the reports on a map. While a complicated version would come later, Candy decided for the proof of concept a simple Mojolicious::Lite application that used the MapBox API would be sufficient:

Wait till Santa sees this thought Candy, laughing to himself how he’d managed to get the map working despite not having what anyone would have traditionally thought of as location data. Santa wouldn’t be asking where in the world? the problems were anymore, but he probably would be asking where in the world? had Candy got the brilliant idea to use IP Geolocation.

About The Author

Mark Fowler is a Senior Software Engineer at MaxMind. He first picked up his favorite programming language, Perl, while completing his BSc in Computer Science from the University of Bath around the turn of the millennium; In the years since he’s become a regular speaker at Perl conferences and open sourced many well used Perl modules, some of which ship with perl itself. On a whim he started an advent calendar that features a different Perl module each day, and — fifteen years later — having having written over a hundred advent articles like this blog post, he serves as the editor for a team of volunteers that produces the calendar each year.

See Also

  1. The GeoIP2::Database::Reader on the CPAN
  2. The MaxMind dev site provides download of the GeoLite2 databases
This guest blog entry is a crosspost from the Perl Advent Calendar featuring a new Perl Module tutorial each day of advent