Flat 18 logo
flat 18
Case study / IP geolocation service

Flat18 Geo

A compact IP intelligence API for Vercel that combines city and ASN lookups, browser-safe geo responses, scheduled refresh dispatch, and a freshness monitor built for operations.

View live APIRead the build story
4 endpointsAPI surface

ipinfo, geo, refresh, and freshness cover the full lifecycle.

60s cacheLookup

Private responses stay light for repeat calls.

15s TTLMonitoring

Freshness checks stay cheap while still showing stale data quickly.

Development journey

From scattered IP data to a service built around trust and freshness.

Flat18 approached IPGeo as a reliability problem first. The API had to answer location questions quickly, keep browser callers safe, and make data age visible without turning the request path into a heavy job.

01 / Trust gap

IP data was useful, but it needed more than a raw lookup.

Other Flat18 apps needed city, region, ASN, and request context, but the data only mattered if it stayed fresh and the caller could trust what came back later.

02 / Product shape

We split the service into the smallest useful endpoints.

Flat18 Geo ended up with four clear jobs: lookup, browser-safe geo, refresh dispatch, and freshness monitoring. Each surface keeps its own auth, cache, and response rules.

03 / Confidence layer

Freshness had to be visible, not assumed.

A monitor endpoint and a background refresh path keep operators aware of data age without making the request path slow, fragile, or hard to support.

Product surfaces

Designed around the moments where geolocation usually gets messy.

Each surface has one job: keep the lookup predictable, keep the browser path safe, and make the next operational step obvious.

GET /api/geo

Make browser callers safe without hiding request context.

The geo endpoint resolves the caller IP from request headers, supports explicit lookups, and keeps the response usable from the browser.

GET /api/ipinfo

Keep the main lookup compact and cacheable.

The lookup endpoint returns city, region, country, timezone, and ASN data with predictable cache behaviour.

GET /api/refresh

Move reload work off the hot path.

Refresh calls validate their trigger, dispatch GitHub Actions, and hand off the heavier GeoLite load without blocking the edge request.

GET /api/freshness

Show data age before it becomes a support problem.

The freshness endpoint reports the latest load row so operators can see when GeoLite data last changed.

ipinfo response
Browser-safe geo
Refresh dispatch
Freshness monitor
Product snapshot

Why it works

Flat18 kept the hot path thin, moved the heavier data reload into GitHub Actions, and split the API into small endpoints so lookup, refresh, and monitoring each stay easy to understand.

LiveDiagnosis: IP data needed trust and freshnessSolution: small endpoints with clear cache rulesOutcome: safer lookups and easier operations

Flat18 treated IPGeo as a confidence problem. The API needed to return useful location data, stay fast enough for other apps to call on demand, and make it obvious when the underlying GeoLite data had gone stale.

Problem found

Other apps needed IP context, but a raw lookup was not enough unless the data was fresh and the response shape stayed predictable.

Flat18 diagnosis

The service needed separate paths for lookup, browser-safe geo, refresh dispatch, and monitoring instead of one heavy endpoint doing everything.

Solution shipped

We built cache-aware endpoints, a GitHub Actions reload path, and a freshness monitor on top of Neon Postgres and the GeoLite2 data model.

Customer value

Flat18 apps can add geolocation context without taking on a heavy platform or a fragile refresh routine.

What Flat18 handled

  • Defined the API contract for lookup, browser-safe geo, refresh, and monitoring
  • Kept the Vercel request path thin and pushed reload work into GitHub Actions
  • Added auth, cache, and debug rules so the service is safe to call from browsers and backend jobs
  • Made data freshness visible so support and operations can spot stale data quickly

Key capabilities

  • City, region, country, timezone, and ASN lookup
  • Browser-safe geo responses with resolved caller IP
  • Basic or bearer auth for lookup requests
  • Cron-aware refresh dispatch
  • Bearer-protected freshness checks
  • Private 60 second cache on successful lookups

Stack

Vercel FunctionsNeon PostgresGitHub ActionsMaxMind GeoLite2Vercel CronHTTP Basic / BearerPostgres SQL functions

Need IP intelligence that stays fast and easy to trust?

Flat18 can turn geolocation, refresh jobs, and freshness monitoring into a service that stays clear under pressure.

Chat with usEmail hello@flat18.co.uk

Tell us what you want to build

Share the goal, deadline and current state. We will reply with the best route and next step.

hello@flat18.co.uk
Remote-first team
Mon-Fri: 12:00 - 20:00 UTC
Quick contact

Need a quicker back-and-forth? Open live chat or message us on Telegram.

Telegram