Tag: geolocation

Roadtrip Companion

~ Sean Nolan

TLDR: Check out my cool roadtrip app; it’s perfect for a Memorial Day road trip!

A truism of the startup world is that there are no new ideas; everything you have ever thought of has been tried before. If you’re lucky, your timing is right, or you’ve figured out that one insight that gets it over the hump, or you just have more money — but you ain’t the first. Which is why I’ve always been surprised that, twenty-plus years after first thinking about this roadtrip companion app, nobody has made it happen. But then again I didn’t build it either, because the confluence of tech was never quite right for a side project. Until now!

Roadtrip Companion

Here’s the pitch. When you’re on a long drive — even on our supposedly personality-free interstate highway system — you’re driving through amazing history and culture and science. What’s growing on that field? What’s with the big tower over there? How did that mountain get its weird shape? Who plays at that baseball field? What’s with the big canal next to the road? Why is this town here, in the middle of nowhere? It never ends and the answers are awesome.

For years, I’ve wanted to have an app — not a routing tool or something to help me find a bathroom (both important things) — that continuously feeds me fun facts about wherever I am. And it has to work without a bunch of interaction, because my Rivian already bitches like a backseat driver, constantly nagging me to “look at the road.” So judgy.

Map of the Redmond area featuring Larsen Lake, accompanied by a photo of the lake showing surrounding greenery and a cloudy sky.
Map of Bellevue, Washington, highlighting the location of the Rosalie Whyel Museum of Doll Art, with a photo of the museum building on the right.
Map showing Kelsey Creek's location with a highlighted red marker and a close-up of the creek surrounded by greenery.
Map showing Microsoft Redmond Campus location with a photo of the building and logo.

Try it yourself at https://seanno.github.io/points/ … or maybe more interestingly, these simulated (as the crow flies) trips from Blaine, WA to Vancouver, BC or Bath, ME to East Boothbay, ME. it’s optimized for a mobile device in landscape mode, but it’s just a web app, so your desktop browser is fine too.

A quick feature tour

When you open the app, it requests location permission and plots that on top of a road map, courtesy of OpenStreetMap and Leaflet — more amazing open source technology that generous people have caused to exist in the world. Standard zoom and pan stuff works as you’d expect; use the “Recenter” button to focus the map back on you.

As your location updates, it keeps track of speed and heading, and queries (the grand-daddy of open source information) Wikidata to identify points of interest near and ideally in front of you. Every minute, a new point is plotted on the map and shown on the right-side pane, with a picture and (very) short description if available. As an aid to keeping your eyes on the road, clicking the “bell” enables a chime each time a new one is shown. Click the “FS” button to enter full-screen mode which looks way better, and if you want to advance through points more quickly, use the “Next” button.

This is neat, but the really cool part is hiding behind the “More” button. This prompts Claude AI to act as a local tour guide, giving you a couple of quick paragraphs about that location. It’s shown on screen and, much better for driving, is read aloud automatically.

One caveat on the AI integration — the app runs entirely client-side including the calls to Claude. This is great for lots of reasons but does mean that if I included my own Claude API key, anyone could grab it and use it for anything. Since this app was just for entertainment purposes, I avoid this by prompting for a key the first time the “More” button is clicked, and persisting it in browser local storage. You can get one at https://platform.claude.com and the cost is truly trivial, pennies per day of active use. If you just want to give it a try and aren’t a jerk, let me know and I can hook you up temporarily; drop me a note.

That’s it — simple, single purpose, and at least IMNSHO incredibly rewarding. I’ve spent drives the last few months fine-tuning the behavior, and it seems pretty dialed in.

Some interesting implementation details

Most of the interesting things about this app come down to managing the queue of locations so that things stay interesting and available.

Querying “ahead”

First of all, Wikidata is a truly huge RDF data store, and it responds to potentially really expensive SPARQL queries, including geolocation, for free. Not surprisingly, it can be a bit slow to respond and nobody damn well better complain about that. But it does require some care and feeding — the site makes its queries on a background thread, and tries to identify key points at which you’re almost out of good stuff so there’s time to find new ones, i.e.:

  • When the queue length gets too small (duh),
  • When you’ve travelled a certain distance, or
  • When all the remaining points are behind your direction of travel.

The app also tries to look “ahead” in space — using your heading and speed to target searches not just where you are right now, but where you’ll be over the next few minutes. There’s a lot of angular math going on here, and I’m thankful to have had Claude Code helping me out with all that. Yeesh.

What is “interesting” anyways?

I could keep tweaking this forever. RDF is really powerful, but it’s also kind of a pain in my a**. Everything is very general and hierarchical, without a lot of defined structure. You can see the basic query in the code; pretty much put together by trial and error.

The points returned are filtered and sorted using a few different heuristics:

This trickiest part of all this is the failure case. We prefer all of these rules, but the bottom line is that we always want to show something, so the code has to fall back if necessary.

The local tour guide

It is truly amazing how good Claude is at generating fun facts about just about any random location I’ve happened to drive by. We’re talking really obscure stuff, like drainage ditches and little pocket parks way out in the boonies.  My prompt isn’t even very sophisticated; it’s just magic.

But it does have a style, and that style can become really grating over time. “If you’re the kind of person who enjoys the history of community water systems” … “It’s the kind of place most people just drive by” … you’ll see what I mean.

My first idea for fixing this was to add more context — feed the model its last X descriptions and say “make it sound different.” But Claude itself came up with a better idea — we created a set of “prompt angles” that emphasize different approaches or styles, and randomly pick a new one with each request. A much cheaper option, and one that works very well. Nice.

Testing is hard

I have to admit that, especially in retirement, I’m pretty lazy about automated testing. At the risk of seeming (and maybe being) a bit arrogant, I’m just a pretty good coder. I walk through my code by hand, implement failure cases the first time, and am not afraid to throw away spaghetti and start over. Especially for projects where I’m a solo developer, the cost of a bunch of automation rarely pencils out.

In most ways, this holds true for this app as well. But the tough thing is — you can’t really see how all of these heuristics perform without actually getting in the car and driving around a lot, in a lot of places. And while I adore a good trip, it’s sadly not realistic to hit the road every time I tweak this code.

The obvious fix was to create a mock geolocation service that exposes the same basic geolocation API as the browser but using a synthetic route. This not only proves to be incredibly useful but also quite entertaining. I linked a few mock routes at the top of this piece; here are a few more just for kicks:

I’m looking forward to giving this a try next month when we’re on our amazing narrowboat canal trip in the UK. And as always, I’d love to hear your ideas and critiques — or just steal the code for your own purposes, it’s license-free!

Image of Government House in Saint John's, Antigua, showcasing a colonial-style building with a green roof surrounded by tropical landscaping.

RuBy – Blocking Russia and Belarus

~ Sean Nolan

The Internet is a funny place. At the exact same moment that Russian troops are committing war crimes in the real world, Russian users online are just bopping around as if everything is cool. ShutdownHook is anything but a large-scale website, but it does get enough traffic to provide interesting insights in the form of global usage maps. And pretty much every day, browsers from Russia (and very occasionally Belarus) are stopping by to visit.

Well, at least they were until this afternoon. My love for free speech does not extend to aiding and abetting my enemies — and until the people of Russia and Belarus abandon their attacks on Ukraine, I’m afraid that is the best term for what they are. And before you spin up the de rigueur argument about not punishing people for the acts of their government, please just save it. I get the point, but there is nobody on earth that can fix these countries other than their citizens. They do bear responsibility — just as I and my fellow Americans did when we granted a cowardly, bullying toddler the United States’ nuclear codes for four years. Regardless of our individual votes.

Anyways, while I’m certainly not changing the world with my amateur postings here on ShutdownHook, I am trying in a very small way to share ideas and experience that will make folks better engineers and more creative and eclectic individuals. And I just don’t want to share that stuff with people who are, you know, helping to kill families and steal or destroy their homes. Weird, I know.

Enter RuBy — a tiny little web service that detects browsers from these two countries and replaces site content with a static Ukrainian Flag. You can add it to your web site too, and I hope you will. All it takes is one line anywhere on your site:

 <script src="https://shutdownapps.duckdns.org:7076/ruby.js" type="text/javascript" defer></script>

It’s not perfect — the same VPN functionality that folks use to stream The Great Pottery Throw Down before it’s available in the States will foil my script. But that’s fine — the point is to send a general message that these users are not welcome to participate in civilized company, and I think it does the trick.

If you’d rather not use the script from my server, the code is freely-available on github — go nuts. I’ll cover all the details in this post, so keep on reading.

Geolocation Basics

Image credit Wikipedia

Geolocation is a general term for a bunch of different ways to figure out where a particular device exists in the real world. The most precise of these is embedded GPS. Pretty much all of our phones can receive signals from the GPS satellite network and use that information to understand where they are — it’s how Google Maps shows your position as you sit in traffic during your daily commute. It’s amazing technology, and the speed with which we’ve become dependent on it is stunning.

Most other approaches to positioning are similar; they rely on databases that map some type of identifiable signal to known locations. For your phone that might be cell towers, each of which broadcasts a unique identifier. Combining this data (e.g., from opencellid.org) with real-time signal strength can give some pretty accurate results. You can do the same thing with a location-aware database of wifi networks like the one at wigle.net (the nostalgia behind “wardriving” is strong for this nerd). Even the old WWII-era LORAN system basically worked this way.

But the grand-daddy of location techniques on the Internet is IP-based geolocation, and it remains the most common for locating far-away clients without access to signal-based data. Each device on the Internet has an “IP Address” used to route messages — you can see yours at https://whatsmyip.com/ (ok technically that’s probably your router’s address, but close enough). This address is visible to both sides of a TCP/IP exchange (like a browser making a request to a web server), so if the server has access to a location-aware database of IP addresses, it can estimate the browser’s real-world location. The good folks at ip2location.com have been maintaining exactly this database for years, and insanely they still make a version available for free at https://lite.ip2location.com/.

The good news for IP-based geolocation is that it’s hard to technically spoof an IP address. The bad news is that it’s easy to insert devices between your browser and a server, so spoofing isn’t really even required to hide yourself. The most common approach is to use a virtual private network (“VPN”). With a VPN your browser doesn’t directly connect to the web server at all — instead, it connects to a VPN server and asks it to talk to the real server on your behalf. As far as the server is concerned, you live wherever your VPN server lives.

There are whole companies like NordVPN that deliver VPN services. They maintain thousands of VPN servers — one click makes your browser appear to be anywhere in the world. Great for getting around regional streaming restrictions! And to be fair, a really good way to increase your privacy profile on the Internet. But still, just a teeny bit shady.

Geo-Blocking

There are a few ways to use IP-based location data to restrict who is allowed to visit a website. Most commercial or high-traffic sites sit behind some kind of a firewall, gateway or proxy, and most of these can automatically block traffic using location-based rules. This is actually pretty common, in particular to protect against countries (you know who you are) that tend to be havens for bad actors. Cloud providers like Azure and AWS are making this kind of protection more and more accessible, which is a great thing.

Another approach is to implement blocking at the application level, which is what I’ve done with RuBy. In theory this is super-simple, but there are some interesting quirks of the IP addressing landscape that make it worth some explanation.

But first a quick side note — there are no new ideas, and it turns out that I’m not the only person to have come up with this one. The folks over at redirectrussia.org have a script as well — it’s a little more complicated than mine, and a bit smarter — e.g., they limit web service calls by doing a first check on the browser’s timezone setting. They also allow the site owner to redirect blocked clients to a site of their choosing, whereas I just slap a flag over the page and call game over. Whichever you pick, you’re doing a solid for the good guys.

RuBy as a Web Service

Using the web service is about as simple as it gets; just add that one-line script fragment anywhere on your page and you’re done. Under the covers, what happens is this:

  • The browser fetches some javascript from the URL at https://shutdownapps.duckdns.org:7076/ruby.js. Note the “defer” attribute on the tag; this instructs the browser to load the script asynchronously and delay execution until the rest of the page is loaded. This avoids any performance impact for pages using the script.
  • The web service examines the incoming IP address and compares it to a list of known address ranges coming from Russia and Belarus. If the IP is not in one of those ranges, an empty script is returned and the page renders / behaves normally.
  • If the IP is in one of those ranges, the returned script replaces the HTML of the page with a full-window rendering of the Ukrainian flag (complete with official colors #005BBB and #FFD500). I considered redirecting to another site, but preferred the vibe of fully dead-ending the page.

Most systems can pretty easily add script tags to template pages. For ShutdownHook it was a little harder because I was using a subscription plan at WordPress.com that doesn’t allow it. This isn’t a problem if you’re on the “business” plan (I chose to upgrade) or are hosting the WordPress software yourself or anywhere that allows plugins. After upgrading, I used the very nice “Insert Headers and Footers” plugin to insert the script tag into the HEAD section of my pages.

And really, that’s it. Done and done.

RuBy Under the Covers

The lookup code itself lives in RuBy.java. It depends on access to the IP2Location Lite “DB1” database; in particular the IPV6 / CSV version. Now, there are tons of ready-to-go libraries for working with this database, including for Java. I chose to implement my own because RuBy has very specific, simple requirements that lend themselves to a more space- and time-efficient implementation than a general-purpose library. A classic engineering tradeoff — are those benefits worth the costs of implementation and code ownership? In my case I think so, because I’m running the service for free and want to keep hardware costs to a minimum, but there are definitely arguments on both sides.

In a nutshell, RuBy is configured with a database file and a list of countries to block (specified as ISO-3166 alpha-2 codes). It makes a number of assumptions about the format of the data file (listed at the top of the source file), so be careful if you use another data source. Only matching ranges are loaded into an array sorted by the start of the range, and queries are handled by binary-searching into the array to find a potentially matching range and then checking its bounds. For Russia and Belarus, this ends up holding only about 18,000 records in memory, so resource use is pretty trivial.

IP addressing does get a little complicated though; converting text-based addresses to the integer values in the lookup array can be tricky.

Once upon a time we all used “v4” addresses, which you’ve surely seen and look like this: 127.0.0.1. Each of the four numbers are byte values from 0-255, so there are 8 * 4 = 32 bits available for a total of about 4.3 billion unique addresses. Converting these to a number is a simple matter that will look familiar to anyone who ever had to implement “atoi” in an interview setting:

a.b.c.d = (16777216 * a) + (65536 * b) + (256 * c) + d

Except, oops, it turns out that the Internet uses way more than 4.3 billion addresses. Back a few years ago this was the source of much hand-wringing and in fact the last IPv4 addresses were allocated to regional registries more than a decade ago. The long-term solution to the problem was to create “v6” addressing which uses 128 bits and can assign a unique address to a solid fraction of all the atoms that make up planet Earth. They’re pretty ugly (e.g., 2001:0db8:85a3:0000:0000:8a2e:0370:7334), but they do the trick.

Sadly though, change is hard, and IPv4 has stubbornly refused to die — only something like 20-40% of the traffic on the Internet is currently using IPv6. Mostly this is because somebody invented NAT (Network Address Translation) — a simple protocol that allows all of the dozens of network devices in your house or workplace to share a single public IP address. So at least for the foreseeable future, we’ll be living in a world where both versions are out in the wild.

To get the most coverage, we use the IP2Location database that includes both v4 and v6 addresses. All of the range values in this database are specified as v6 values, which we can manage because a v4 address can be converted to v6 just by adding “::FFFF:” to the front. This amounts to adding an offset of 281,470,681,743,360 to its natural value — you can see this and the other gyrations we do in the addressToBigInteger method (and for kicks its reverse in bigIntegerToAddress).

Spread the Word!

Technically, that’s about it — pretty simple at the end of the day. But getting everything lined up cleanly can be a bit of a hassle; I hope that between the service and the code I’ve made it a little easier.

Most importantly, I hope people actually use the code on their own websites. We really are at a critical moment in modern history — are we going to evolve into a global community able to face the big challenges, or will we slide back to 1850 and play pathetic imperialist games until we just extinguish ourselves? My generation hasn’t particularly distinguished itself yet in the face of this stuff, but I’m hopeful that this disaster is blatant enough that we’ll get it right. My call to action:

  • If you run a website, consider blocking pariah nations. You can do this with your firewall or gateway, with the RuBy or Redirect Russia scripts, or just roll your own. The only sites I hope we’ll leave open are the ones that might help citizens in these countries learn the truth about what is really happening.
  • Share this article with colleagues and friends on social media so they can do the same.
  • And even more key, (1) give to causes like MSF that provide humanitarian aid, and (2) make sure our representatives continue supporting Ukraine with lethal aid and punishing Russia/Belarus with increasing sanctions.

If I can help with any of this, just drop me a line and let me know.

Attribution: This site or product includes IP2Location LITE data available from https://lite.ip2location.com.