Caching and cost
Decide which VPNDetection answers to cache and for how long, which requests need no lookup, and when a database is cheaper than the API.
Most applications see the same addresses many times, and an address's classification rarely changes within an hour. Caching saves lookups from your quota and removes the API's response time from repeat requests. This page explains what to cache, where, and for how long, and which requests need no lookup at all.
Cache answers by address
We recommend caching each answer by its IP address for about an hour. You may already have this cache without writing one:
- The official libraries cache answers per client, 10,000 addresses for an hour by default. You can change both limits or turn the cache off when you create the client.
- The framework packages cache every answer for an hour.
An answer that carries cap_reached: true is kept for a minute at most, so the full answer returns soon after your organization raises its cap or turns on overage.
Don't cache errors. A failed lookup says nothing about the address, and caching it would repeat the failure for every visitor from that address.
Share a cache across servers
A library's cache lives in one process. If your application runs on several servers, each one looks an address up once an hour. To share one cache, store answers in a shared store such as Redis, keyed by address, with the same one-hour lifetime:
import { createClient } from 'redis';
const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();
export async function lookupShared(ip) {
const cached = await redis.get(`vpndetection:${ip}`);
if (cached) {
return JSON.parse(cached);
}
const result = await client.lookup(ip);
await redis.set(`vpndetection:${ip}`, JSON.stringify(result), { EX: 3600 });
return result;
}A shared cache matters most when the same visitors reach many servers, for example behind a load balancer without sticky sessions.
Skip lookups you don't need
- Static files and health checks don't need to know who is asking.
- Requests from your own infrastructure, such as monitoring and internal services, are already known.
- Private and reserved addresses are answered locally by the libraries and the framework packages, without a request.
Look up the requests where the answer changes what you do, such as sign-ups, logins and payments. A visit to a public page usually doesn't need one. In the framework packages, mount the middleware on those routes, or skip the rest.
Look up many addresses at once
When you have a list rather than a stream, POST /batch answers up to 1,000 addresses in one request on a paid plan, and the libraries split a longer list for you. A batch costs the same lookups as single requests, but it saves the time of a request per address. See Batch.
When a database costs less
Above a few million distinct addresses a day, or where every lookup must finish in microseconds, a database usually costs less than the API, because a downloaded file answers any number of lookups. API or database compares the two.
Next steps
Before you launch, review the go-live checklist, which includes caching among the checks.