Consenti

Geo-Routing & Auto-Detection

When a widget calls /resolve-profile, the backend maps the visitor to a compliance group — GDPR for EU visitors, CCPA for Californians, and so on. Consenti ships four geo resolver options. This guide explains how each works and when to use it.

How the resolution pipeline works

The widget sends:

text
GET /consenti/api/v1/resolve-profile?tz=Europe%2FParis&lang=fr-FR&locale=fr-FR

The backend runs this pipeline:

  1. Call the configured geoDataProvider with { ip, timezone, language }.
  2. Resolver returns { country, region, locale }.
  3. Country/region is matched against the compliance map (195 countries and territories → 8 compliance groups).
  4. Response returns the file path to the active profile JSON for that group.

The four built-in resolvers

ResolverExtra install?AccuracyOutbound traffic?
defaultNoLow (heuristic)No
hosted-geoip-liteNoMediumYes — calls ipinfo.io
geoipYes — npm install geoip-liteHighNo (local DB)
maxmindYes — npm install maxmindHighestNo (local .mmdb)
createConsenti({
  compliance: {
    type: 'auto',
    geoDataProvider: 'default',   // timezone + Accept-Language heuristic
  },
})

The compliance map

Countries are mapped to compliance groups via an embedded, fixed map of 195+ countries and territories, maintained by the Consenti project — see the full list on the Jurisdiction Coverage Map. There is currently no config option to supply your own map; geoDataProvider is the only customization point in the pipeline — it decides which country/region gets looked up, not what group that country resolves to.

typescript
createConsenti({
  compliance: {
    type: 'auto',
    geoDataProvider: 'geoip', // resolves { country, region } — the map does the rest
  },
})
ℹ️US state-level routing (California → opt-out-strict, other states → opt-out) requires a resolver that returns a region value. The geoip and maxmind resolvers both provide subdivision data. The default and hosted-geoip-lite resolvers return country only.
💡Need a jurisdiction to resolve differently than the map says? Don't try to override the map — pin compliance.type to a fixed group for the whole deployment, or author a profile against a customComplianceGroup and target it explicitly. Both are covered on the Jurisdiction Coverage Map.

Trusted proxies

If your server is behind a load balancer or reverse proxy, the X-Forwarded-For header contains the real client IP. Tell Consenti which proxies to trust:

typescript
createConsenti({
  trustedProxies: ['10.0.0.0/8', '172.16.0.0/12'], // your LB IP ranges
  compliance: { type: 'auto', geoDataProvider: 'geoip' },
})
Related documentation
Advanced Configuration
Full geoDataProvider and trustedProxies option reference
Public Routes
The /resolve-profile endpoint used by the widget
Jurisdiction Coverage Map
Every country, its law(s), and its compliance group

Frequently asked questions