Return Home

Playing in Traffic and Heatmaps

Project JavaScript WebApp API Maps

I Like Hexagons

Inspired by the Google Maps API, I thought it would be really cool to try and create a hex oriented activity heatmap (with a last second traffic congestion overlay). From what I could find, the Maps API didn't have anything readily available to accomplish this task. Instead, I simulated congestion by generating a per-hex hourly activity curve using commute-shaped Gaussian peaks (morning/evening travel), overnight dips, and included some pseudo-randomness. Lastly, I factored in a road-density baseline from OpenStreetMap to make it look plausible; More roads = busier. This was not the case.

After trying to tweak my algorithm to try and make it look legitimate (why is a neighborhood more active than the busiest intersection in town... screw you OSM), I did some more research and found that not only does TomTom still exist, but they have an API that provides aggregated historical traffic data at a per-street level. With this, I then finalized the requirements: A semi-accurate hexagon-based activity heatmap, with a historical traffic overlay, and a slider at the bottom to visualize the time of day... with a few other scope creep inclusions like per-hex tooltips, ZIP code search, etc.

Below is the documentation of the project, what it does, and my personal experience with each API and library I used. I documented the cost of each API/library (we're broke out here), the ease of use, and finally a brief explanation of how it was used or integrated into the overall project.

What the App Does

The app renders a live Google Maps basemap overlaid with an Uber H3 hexagonal grid. Each hex is colored on a gradient from cool blue (low activity) to hot red (high activity) based on a traffic profile unique to that hex's location and road density. On top of the hex layer, TomTom road segments are drawn in orange and red wherever historical speed data shows significant congestion, we exclude TomTom segments with low congestion.

The four main features are:

  • Hex grid: The entire visible viewport is tiled with H3 resolution-9 hexagons. Each cell is colored based on its traffic profile at the given hour. The color gradient dynamically normalizes to the min/max of the visible cells, so the full color range always spans whatever is on screen.
  • TomTom road overlay: Orange and red polylines are drawn over real road segments fetched from TomTom's historical Flow Statistics API. Only segments with a normalized congestion score ≥ 0.6 (orange–red range) are shown.
  • ZIP code search: Entering any US ZIP code recenters the map and rebuilds the hex grid at that location. The Google Geocoding API resolves coordinates and a place label (e.g. "Manhattan, NY") is shown as feedback below the search field.
  • Per-hex tooltip: Clicking any hex opens a popup showing the current traffic level, peak hour, quietest hour, and a 24-bar daily sparkline profile. The active hour is highlighted in the sparkline as the time slider moves.

The interactive demo was created capturing static images with the slider hidden on the actual webapp, injecting those images here, and then reattaching a slider. The time slider at the bottom advances hourly from 00:00 to 23:00. Every hex and road segment re-evaluates its color at the selected hour, with smooth transitions between frames. Use the slider below to view a full day of traffic.

00:00 23:00

Drag the slider or hit Play to watch congestion build and clear across the day.

The Fake Traffic Problem

What the time slider shows for the hex grid is entirely synthesized. It resembles plausible activity patterns, but doesn't translate to real world traffic. Hexes near road corridors got a slight boost in activity score, and hexes far from any road stayed low. It felt spatially plausible, but still a mathematical approximation. Some of the flaws showed early on with neighborhoods that have many roads showing "high activity" due to the road density, while the highways adjacent to them were lower even though they had more through traffic.

Additionally, historical traffic data didn't exist for free at the scale I needed. TomTom's statistics endpoint has a daily limit of 2,500 daily requests, Google doesn't expose anything comparable. The hexes that show TomTom segments contain real data; everything else is an approximation. I blended the TomTom congestion score on top of the synthesized baseline to get a final congestion score for each hex, and this combination is what drove the color.

If I Could Do Something Differently

I went about this project backwards. I initially tried to establish an activity heatmap with synthesized data, and later layered historical traffic data (what I didn't realize was real activity) on top. In retrospect, the historical traffic data TomTom provided was the closest thing to an activity heatmap I could use as a starting point.

I should have started with the TomTom historical data at a small scale, then layered my hexagons and done the heatmap calculations based on traffic. This would have provided a consistent baseline across all types of areas and infrastructure. Hex grid coloring would have then coincided with real traffic congestion patterns. In addition to this, starting at a smaller scale would have saved me days, because I kept running out of TomTom API calls while testing.

APIs Used

    Google Maps Platform

  • Google Maps JavaScript API
    Cost: $7 / 1,000 map loads Ease of use: Easy

    Google Maps provided the basemap and camera controls, loaded in with @googlemaps/js-api-loader. I originally wanted a tilted basemap with raised 3D hex columns reflecting activity levels. My first attempt was deck.gl's HexagonLayer, but that approach was not a good fit, because I needed stable, globally addressable hex cells for caching and per-hex state. I dropped the raised-column idea and moved to H3-indexed hexes, rendered with deck.gl PolygonLayer, which gave me predictable geometry and global IDs.

    My second issue was tilt. Google Maps defaults to raster rendering, which is essentially a flat map layer with no available 3D camera behavior. To enable tilt, I had to generate a Map ID with vector rendering enabled. I integrated everything correctly, went to test my code, but my map in Chrome was still flat. After about 15 minutes of debugging and testing, I switched browsers. To my surprise, the tilt worked great in Edge and the VS Code browser. The issue was something silly; hardware acceleration was disabled in Chrome, which caused a silent default to raster mode. Apparently tilting the map is a GPU intensive task, who knew.

  • Google Geocoding API
    Cost: $5 / 1,000 requests Ease of use: Easy

    I used this to power the ZIP code search in the top-left panel. You typed a US ZIP, hit Go, and the Geocoding API returned the coordinates and a formatted address. The app pulled geometry.location to recenter the map and read the address components to build a label like "Manhattan, NY" shown as feedback below the search field. It was straightforward, no issues.

  • Google Places API
    Cost: $0.032/req (Nearby Search); $0.017–$0.05/req (Place Details) Ease of use: Medium

    I tried Places so I could populate a "Nearby Places" section in my hex tooltips. The problem was that Nearby Search frequently returned street names (routes) or town names (localities) instead of actual businesses, which was useless for contextualizing traffic/activity. When it did return businesses, it felt random and inconsistent, and these were not the businesses causing traffic (Subway, McDonald's, Laundromat, etc.). Stopped using it after a few testing iterations.

  • TomTom

  • TomTom Traffic Tile API
    Cost: Included in 50,000/day free tier Ease of use: Easy

    I tried this first since it felt like a lightweight solution. I encountered an immediate hard stop: tiles are pre-rendered images fetched by zoom/x/y grid coordinate. There was no underlying data to query; I couldn't ask what the speed was on a given road, click a segment, or map time-of-day values to the time slider. I stopped using this very quickly.

  • TomTom Flow Segment Data - Real-Time
    Cost: Included in 2,500/day free tier Ease of use: Easy

    I tried flowSegmentData/absolute as an initial data source just to see how it worked. By passing it a lat/lng and zoom level, it returned the nearest road segment's current speed, free-flow speed, and polyline geometry. As this was strictly real-time traffic, it couldn't be used with the time slider.

  • TomTom Flow Segment Data - Statistics (Historical)
    Cost: Included in 2,500/day free tier Ease of use: Medium*

    This was the endpoint that actually integrated well with the time slider. Using flowSegmentData/statistics, I got a sub-hourly historical speed profile across the full day. As I quickly found out, at street-level granularity across a zoomed-out viewport, I burned through my 2500 free API requests in minutes.

    TomTom's historical data comes from GPS probes. These are cars that drive around and report their speed and location. The more traffic a road sees, the more probe data exists for it. Major roads in big cities were well covered; however, quiet residential streets and anything outside major metro areas had little to no data at all.

    There is a big drawback - the requests limitation - and this was why I marked it Medium*. The API was straightforward, but I had to do mental gymnastics to stay within my request budget. TomTom's free tier is 2,500 requests per day, and a city viewport at zoom 15 could have 200+ hexes with one hit each, per slider step. Panning around Manhattan with the slider playing burned through the daily cap in minutes. I attacked this by only requesting data for hexes above a certain OSM road density score, and only once per whole hour rather than on every fractional step. While this seriously limited my traffic visibility, it eliminated the majority of idle API usage. It also allowed me to continue testing without hitting the daily cap in 4 minutes when my cap reset (I still only lasted about 20 minutes).

  • Other

  • OpenStreetMap - Overpass API
    Cost: Free Ease of use: Medium

    Overpass let me query what roads actually existed near each hex center, and I used that to build a baseline score for each cell to try and represent potential activity. For example, a hex sitting on top of a highway got a higher score than one sitting in a park. When TomTom data eventually came in for sampled points, it was blended on top of those baseline scores, and the result drove both the hex color and whether a hex was worth spending a TomTom request on in the first place.

    The limitation was that Overpass only knew about roads, not what was generating traffic on them. A crazy example of this phenomena is a neighborhood. Neighborhoods can have very complex street grids, and OSM will interpret these as higher road density (busier), when they're actually quiet residential streets, vice 4 way intersections, where it only sees 2 multilane roads.

  • H3 - Uber's Hexagonal Grid
    Cost: Open-source (free) Ease of use: Easy

    H3 became the core hexagonal grid system for the app. I used it to fill the visible map area with hex indexes at a fixed resolution, which gave me a deterministic set of cells every time the camera moved.

    With a stable grid in place, I drew each hex cleanly on the map and used each one as a reference point to collect specific traffic data. Any location I clicked or searched for could be matched to a specific hex, which made cell-specific API calls very easy. Now instead of constantly recalculating everything from scratch, I had the ability to cache data to specific hexes for reuse.