Written by

Threatmatic

At

Wed Sep 02 2026

Deep Dive: Geo-Aware Zones and the Nearest-Zone API

How Threatmatic zones and devices learned to say where they physically are, and the new API that turns those coordinates into a real routing decision.

Back

A zone in Threatmatic is a microsegmentation container — a boundary that devices can reach into and talk to each other across, enforced over QSChannel™. Until now, a zone had no concept of where it physically was. Two zones on opposite sides of the planet were, to the platform, just two rows in a table. This piece covers the two things that changed that, and is deliberately specific about the new API's real shape — not just the idea behind it.

Comparison of every device being routed to the same distant zone entry point versus the nearest-zone API computing actual distance and picking the closest one

The problem: "nearest" was never computed anywhere

As Threatmatic's footprint grows past a single region, a question keeps coming up: when a device in Bangalore needs to reach a zone, should it really be handed the same entry point as a device in San Francisco? Distance has a real cost — every extra hop of geography is latency a device didn't need to pay.

The honest answer, until this pass, was: nothing in the platform computed "nearest" at all. Not in the console, not in QSChannel™'s own WireGuard reconciliation loop. A zone had exactly one entry point, full stop, and every device that reached it got the same one regardless of where either side of the connection actually was.


Zones and devices learn to say where they are

The fix starts at the schema. Both zone and device now carry a latitude/longitude pair — plain coordinates, admin-entered, nothing exotic. No PostGIS, no geography column type: at the number of zones a single org actually runs, that infrastructure isn't earning its keep yet, and plain floats plus a distance formula in SQL are exactly enough.

Coordinates are optional and record intent, not automatic truth. Setting them today doesn't move any traffic — it just gives the platform a fact it never had before: this zone is here; this device is there.


The Nearest-Zone API

GET /api/zones/nearest?lat=<number>&lng=<number>&tag=<optional>

Auth. This endpoint is meant to be called by something other than a logged-in browser — the eventual consumer is QSChannel™'s own routing decision, not a console user — so it authenticates with an API key (x-api-key header, or Authorization: Bearer), scoped to an organization, not a browser session:

GET /api/zones/nearest?lat=12.9716&lng=77.5946
x-api-key: org_...

A missing key returns 401. An invalid or unauthorized one returns 403.

Parameters. lat and lng are required — the coordinates of whoever's asking "which zone is closest to me." tag is optional, and it's the interesting part (more below).

What it returns. The single nearest zone with coordinates set, plus the computed distance:

{
  "data": [
    {
      "id": "01a05ec9-...",
      "title": "Bangalore",
      "slug": "bangalore",
      "latitude": 12.9716,
      "longitude": 77.5946,
      "distanceKm": 0.03
    }
  ]
}

The math. Great-circle (haversine) distance, computed directly in the query:

6371 * acos(
  cos(radians(:lat)) * cos(radians(zone.latitude)) *
  cos(radians(zone.longitude) - radians(:lng)) +
  sin(radians(:lat)) * sin(radians(zone.latitude))
)

Ordered ascending, limited to one row. No external geo service, no extension — Postgres already knows trigonometry.


The design decision that mattered most: regions aren't a new concept

The obvious next question was how to model regional zone groups — a set of zones that together serve, say, "remote access," so a device picks the nearest one among just that set, not every zone the org has.

The tempting version of that is a new schema concept: a region table, a foreign key, a join. We didn't build that. A region is just zones that share a tag — the same tags array every zone already has, used for the same purpose it's always been used for. tag=remote-access on the API call filters the nearest-zone search down to only zones carrying that tag:

GET /api/zones/nearest?lat=51.5074&lng=-0.1278&tag=remote-access

Nothing new to migrate, nothing new to teach the console UI, nothing new for an admin to learn. A "region" is a naming convention on data that already exists.


What this doesn't solve — and why that's the honest answer

It would be easy to let "nearest-zone API" quietly imply "geo-routing is solved." It isn't, and the gap is worth being specific about.

This API answers the question for a caller who already knows their own coordinates — a device initiating an outbound connection to a regional zone. It does not answer the question for anonymous inbound traffic hitting a published hostname, where there's no "device," only a source IP and a DNS lookup. Routing that traffic to the nearest edge is a genuinely different problem — it lives at the DNS layer (GeoDNS) or the network layer (anycast IP announcement via BGP), not in a REST endpoint a device calls after the fact. That work is still ahead of us, deliberately scoped as its own effort rather than forced into this one.

It's also worth saying plainly: this API doesn't yet change what QSChannel™ actually does. Today, a zone still resolves to exactly one entry point, chosen by tag match, not by distance. Wiring a nearest-zone decision into QSChannel™'s own reconciliation loop — the piece that actually pushes WireGuard peer configuration to a device — is the next concrete step, not something this pass claims to have finished.


What comes next

Two follow-ons are already scoped:

  • Regional remote-access zones, using the tag-group pattern above, so a device's outbound QSChannel™ connection actually resolves to whichever regional zone is closest — not just computable via an API call, but the thing that happens automatically.
  • Anycast for EdgeScale Ingress and π, for the inbound side this API deliberately doesn't touch — published-hostname traffic and inspected traffic routed to the nearest point of presence at the network layer, the way the "route to the nearest edge" story has always been told publicly.

Both build on the same coordinates this pass introduced. Neither pretends this pass finished them.


Threatmatic. threatmatic.ai