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 (190+ 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 map of 190+ countries and territories, maintained by the Consenti project — see the full list on the Jurisdiction Coverage Map. geoDataProvider decides which country/region gets looked up; compliance.complianceMap decides what group that country resolves to — set it to 'default' to keep the embedded map, a URL to fetch your own JSON map (refreshed in the background per the response's Cache-Control/Expires header), or an inline object to override specific countries directly.

typescript
createConsenti({
  compliance: {
    type: 'auto',
    geoDataProvider: 'geoip', // resolves { country, region } — the map does the rest
    complianceMap: 'default', // or a URL string, or an inline ComplianceMapData object
  },
})
ℹ️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