ZIP-to-lat/lng feels like a solved problem. There are something like 41,000 active US ZIP codes. They're a public dataset. They're geocoded. Multiple free APIs serve them. You wire one up, it works, you ship.
That's what I thought. Then a user reported that the gas station on his block was showing as "8,247 miles away."
Quick context: I run a gas price finder side project. When you enter a ZIP, the site looks up that ZIP's lat/lng, then sorts nearby gas stations by driving distance. If the ZIP's lat/lng resolves to (0, 0), the Haversine math returns absurd distances because (0, 0) is in the middle of the Atlantic Ocean off the coast of Africa.
The user's ZIP was 75072. McKinney, Texas. Population 200,000. Not some obscure rural P.O. box. A real ZIP code with a real population center.
My geocoder was returning (0, 0).
What was actually happening
My geocoder, at the time, was a single fetch:
async function zipToLatLng(zip: string) {
const res = await fetch(`https://api.zippopotam.us/us/${zip}`);
if (!res.ok) return { lat: 0, lng: 0 };
const data = await res.json();
return {
lat: parseFloat(data.places[0].latitude),
lng: parseFloat(data.places[0].longitude),
};
}
zippopotam.us is free, fast, and was working for everything I'd tested. So when 75072 returned a 404, my fallback was the (0, 0) sentinel. Garbage in, garbage out.
I dug a little. Curled the API directly:
$ curl -i https://api.zippopotam.us/us/75072
HTTP/1.1 404 Not Found
Then I tried 75070, the neighboring ZIP:
$ curl -i https://api.zippopotam.us/us/75070
HTTP/1.1 200 OK
So 75070 is in zippopotam's data, 75072 isn't. Two ZIPs in the same city, one block apart, one of them missing. There's no announced data freshness commitment from zippopotam (it's a free service maintained by one person), so this isn't a bug to report. It's just a gap.
I spot-checked. Out of a sample of 100 ZIPs from my user logs, zippopotam returned 404 on 4 of them. A 4% gap rate. On a programmatic site with 33,620 pages, that's about 1,300 pages where the geocoder silently returned (0, 0) and broke distance math.
This is the moment when "I'll just use a free API" stops scaling.
The chain I shipped
What I needed wasn't a better single source. It was a chain of sources, each with different tradeoffs, ordered from cheapest to most expensive:
- Static file lookup (instant, zero network)
- Redis cache (instant, one network hop)
- zippopotam.us (~150ms, free, has gaps)
- Nominatim (~400ms, free, rate-limited, covers gaps)
- Sentinel (0, 0) with degraded behavior
Here's the actual implementation, slightly cleaned up:
import { Redis } from '@upstash/redis';
import zipContent from './zipContent.json';
const redis = Redis.fromEnv();
type LatLng = { lat: number; lng: number };
export async function zipToLatLng(zip: string): Promise<LatLng> {
// Tier 1: static file (33,620 pre-resolved ZIPs)
const staticEntry = (zipContent as Record<string, any>)[zip];
if (staticEntry?.lat && staticEntry?.lng) {
return { lat: staticEntry.lat, lng: staticEntry.lng };
}
// Tier 2: Redis cache (for ZIPs we've resolved at runtime)
const cached = await redis.get<LatLng>(`zip:${zip}`);
if (cached) return cached;
// Tier 3: zippopotam.us
try {
const res = await fetch(`https://api.zippopotam.us/us/${zip}`, {
signal: AbortSignal.timeout(2000),
});
if (res.ok) {
const data = await res.json();
const result = {
lat: parseFloat(data.places[0].latitude),
lng: parseFloat(data.places[0].longitude),
};
await redis.set(`zip:${zip}`, result, { ex: 60 * 60 * 24 * 30 });
return result;
}
} catch (e) {
// network error or timeout, fall through
}
// Tier 4: Nominatim
try {
const res = await fetch(
`https://nominatim.openstreetmap.org/search?postalcode=${zip}&country=us&format=json&limit=1`,
{
headers: { 'User-Agent': 'GasPriceCheck/1.0 (contact@example.com)' },
signal: AbortSignal.timeout(3000),
}
);
if (res.ok) {
const data = await res.json();
if (data.length > 0) {
const result = {
lat: parseFloat(data[0].lat),
lng: parseFloat(data[0].lon),
};
await redis.set(`zip:${zip}`, result, { ex: 60 * 60 * 24 * 30 });
return result;
}
}
} catch (e) {
// network error or timeout, fall through
}
// Tier 5: sentinel
return { lat: 0, lng: 0 };
}
Five tiers, ordered by cost. Each one only runs if the previous one didn't find an answer. The static file handles 99% of requests in zero time. Redis handles the runtime-resolved ones. The two API tiers are the actual fallbacks.
A few notes on the implementation choices.
Tier 1: pre-resolving everything you can ahead of time
The biggest performance win wasn't the chain. It was Tier 1: a static JSON file with every ZIP I knew about, pre-resolved to lat/lng once at build time.
I wrote a Python script (enrich-zip-latlng.py) that walks my full ZIP list, calls zippopotam for each one, falls back to Nominatim for the gaps, and writes the results to zipContent.json. The script is resumable: it checkpoints to a JSON file every 100 ZIPs, so if it crashes (and it did, several times, on intermittent rate limits), you restart and it picks up where it left off.
import json, time
from pathlib import Path
import requests
CHECKPOINT = Path("zip_latlng_progress.json")
OUTPUT = Path("zipContent.json")
def load_progress():
if CHECKPOINT.exists():
return json.loads(CHECKPOINT.read_text())
return {"resolved": {}, "remaining": load_zip_list()}
def resolve(zip_code):
# try zippopotam, fall back to Nominatim
try:
r = requests.get(f"https://api.zippopotam.us/us/{zip_code}", timeout=5)
if r.ok:
d = r.json()
return float(d["places"][0]["latitude"]), float(d["places"][0]["longitude"])
except Exception:
pass
try:
r = requests.get(
"https://nominatim.openstreetmap.org/search",
params={"postalcode": zip_code, "country": "us", "format": "json", "limit": 1},
headers={"User-Agent": "ZipEnricher/1.0"},
timeout=10,
)
if r.ok:
data = r.json()
if data:
return float(data[0]["lat"]), float(data[0]["lon"])
except Exception:
pass
return None, None
After running this against all 33,620 ZIPs (took about 9 hours of wall clock time, mostly idle waiting for rate limits), I had 100% coverage. Every known ZIP resolves in zero network calls at runtime.
The runtime fallback chain is now a safety net for the ZIPs that aren't in zipContent.json (mostly newly-issued ZIPs and edge-case P.O. box codes). It's load-bearing maybe 0.1% of the time. The other 99.9% of requests hit Tier 1 and exit.
Tier 4: Nominatim's etiquette is real
Nominatim is OpenStreetMap's geocoder. It's free. It's also explicit about its rate limits: 1 request per second, max. They publish a usage policy. They will rate-limit you (or ban your IP) if you violate it.
Two things matter for keeping Nominatim happy:
-
Set a real User-Agent header. They block requests with the default
node-fetch/1.0UA. Use something likeMyApp/1.0 (contact@example.com). - Throttle. If you're calling Nominatim from a script, sleep at least 1 second between calls. From an API route serving real users, this is fine because user traffic is naturally sparse.
If you're going to depend on Nominatim at scale, you should run your own instance. It's open source and Dockerized. For a side project hitting it 1-2 times a day, the public instance is fine.
Tier 5: the sentinel and graceful degradation
When all four tiers fail, my function returns { lat: 0, lng: 0 }. The downstream code needs to handle this without producing garbage.
In my case, the downstream consumer is a "nearest gas stations" sorter that uses Haversine distance. If the user's coords are (0, 0), Haversine returns absurd distances for every station. So I added a guard:
const userCoords = await zipToLatLng(zip);
if (userCoords.lat === 0 && userCoords.lng === 0) {
return stations; // unsorted, no distance column
}
return sortByDistance(stations, userCoords);
If we can't geocode, we still show stations. We just don't sort by distance, and we don't display the distance column. The page degrades gracefully instead of showing "8,247 miles away" everywhere.
This is the "fail open" pattern: when the dependency fails, the user still gets a useful page, just with less information. Better than failing the whole request.
What I'd tell my past self
Three things.
One. "Free APIs have gaps" is not a hypothesis, it's a default assumption. Any API where the provider is one person, a small org, or a "we'll keep this up as a community resource" project will have data quality issues somewhere. Plan for it from day one.
Two. Pre-resolve the long tail at build time, not request time. Runtime API calls are a tax on every user. If you have a finite, enumerable input space (like US ZIP codes), resolve the whole space once and cache the results to disk. This collapses the runtime cost from "1 API call per request" to "1 file lookup per request."
Three. Build the chain before you need it. The temptation when the first source works is to ship the single-source version and add fallbacks "later." Later means after a user reports a bug. Building the chain up front takes maybe 2 hours and saves you the embarrassment of "8,247 miles away" emails.
The architecture lesson here generalizes beyond ZIPs. Anywhere you have a dependency that maps "A → B" deterministically and the input space is finite, the move is the same: pre-resolve at build, cache at runtime, fall back to alternative providers, degrade gracefully when all else fails. ZIP geocoding, currency conversion, language code lookups, country data, time zone data, postal codes for any country with public data: same pattern.
The whole rebuild took about a weekend. I'd do it again in an afternoon now that I know the shape. The hard part wasn't the code, it was admitting that "free API + sentinel" wasn't actually a fallback strategy. It was a single-source-of-truth dressed up as one.
If you've shipped a layered geocoding chain on top of zippopotam, Nominatim, or a paid alternative, drop your tier ordering in the comments. Curious what other chains people are running.