A Practical API Integration Checklist for IP Lookups

Adding an IP intelligence call is ten minutes of work and six months of edge cases. This is the checklist we would want a new integration to pass.

1. Get the client address right

Before anything else, make sure you are looking up the correct address. Behind a load balancer or CDN, remoteAddr is your own proxy. You need the forwarded chain — and you need to trust only the hops you control, taking the right-most untrusted entry rather than the left-most spoofable one. A lookup of the wrong address is worse than no lookup, because it looks authoritative.

Also handle IPv6 properly, including addresses in bracketed form and IPv4-mapped notation.

2. Set a hard timeout

Pick a budget — 300–800 ms is usually right for a signup path — and enforce it client-side. A risk check that hangs turns a security feature into an outage.

3. Decide fail-open or fail-closed, per path

Write it down explicitly for each call site:

• Signup / login → fail open. Never lock out your whole user base because a dependency is slow.
• Payout or withdrawal → fail closed, or queue for manual review. Money leaving is worth a delay.

Defaulting the whole application to one policy is how teams end up with either an outage or a loss event.

4. Cache

The same address will hit you repeatedly within minutes. Cache results for a sensible window — an hour is a good starting point — keyed on the address. It cuts latency, cost and provider load at once. Make the TTL configurable so you can shorten it during an incident and lengthen it when traffic spikes.

5. Do the lookup off the critical path where possible

Not every check needs to block the response. For analytics cleanup, log enrichment and post-hoc review, queue the address and enrich asynchronously. Reserve synchronous calls for decisions you are making right now.

6. Handle the unhappy responses

Enumerate them and test them: rate limited, invalid key, unknown address, private or reserved range, malformed input. Each should produce a defined outcome in your code, not an unhandled exception in a request handler.

Private ranges deserve special mention — 10.x, 192.168.x, 127.0.0.1 and friends will appear in development and in misconfigured proxy chains. Short-circuit them before you spend an API call.

7. Protect the key

The API key belongs in server-side configuration, never in browser JavaScript or a mobile bundle. Anything shipped to a client is public. Rotate keys when staff change, and use separate keys per environment so you can revoke one without breaking everything.

8. Log the verdict with the decision

Store the score and flags alongside whatever action you took. When you later ask "why did we decline this order in March?", the answer needs to be in your database, not reconstructed from a provider's dashboard.

9. Watch your own metrics

Track call latency percentiles, error rate, cache hit rate and quota consumption. A quiet drift in any of them usually precedes a visible incident.

10. Test with real addresses

Include a known datacenter address, a known TOR exit, a residential address and a mobile address in your test suite, and assert on classification rather than exact scores. Scores evolve; categories are stable.

Work through the list once and the integration will outlast the sprint that produced it.