Docs

Geo Detection SettingsNew

3 min readUpdated November 10, 2026

Link Bio → Geo Detection decides how the plugin finds a visitor’s country. The country is used by Geo Targeting and the {country} and {country_code} tags.

Geo detection settings with provider choices, API keys, page caching steps and the country tags table

CDN check#

The top of the screen tells you whether a CDN country header reached this page:

  • Cloudflare / Bunny.net country header found: countries come from your CDN, with no outside lookups.
  • No CDN country header: if your site is behind Cloudflare or Bunny.net, turn on the country header there. Otherwise use Automatic or an IP lookup service.

WP LinkCanvas reads Cloudflare’s CF-IPCountry header and Bunny.net’s X-Bunny-Country or CDN-LoopCountryCode header.

Providers#

Provider How it works
Automatic (recommended) Uses the CDN header first, then asks freeipapi.com when there is none. Right for most sites.
CDN header only Only the Cloudflare or Bunny.net header. No outside lookups. Visitors who do not pass through your CDN get no country.
freeipapi.com Looks the visitor up at freeipapi.com: 60 requests a minute free, more with an API key. A CDN header is still used when present.
IP2Location.io Looks the visitor up at ip2location.io: 30,000 lookups a month free, API key required. A CDN header is still used when present.

API keys#

freeipapi.com API key: optional. Leave it empty for the free tier.

IP2Location.io API key: required for the IP2Location.io provider. Get a free key at ip2location.io.

Both key fields are masked on screen.

Lookups are cached for each visitor address, so repeat visits do not use up your quota. A lookup that fails is tried again after 5 minutes. The lookup happens only in the background request described below, never while the page itself is being built.

If your site sits behind a load balancer or proxy that is not on a private network address, see the nlb_trusted_proxies filter in Action & Filter Hooks so the visitor’s real IP is used.

Works with page caching#

No cache exclusions or cookie rules are needed for WP Rocket, LiteSpeed, W3 Total Cache, Bunny CDN or Cloudflare:

  1. The cached page contains every geo-targeted link, each tagged with its country rule.
  2. When the page opens, a small script asks /wp-json/nlb/v1/geo for the visitor’s country. That answer is never cached.
  3. Links show or hide for that country, and {country} tags fill in. Geo-targeted links stay hidden until the country is known, so a cached page never shows another visitor’s links.

If the request is blocked, for example by a security plugin, links are shown or hidden using the best country available rather than staying hidden.

Your cache must not cache /wp-json/ URLs. Every major cache plugin leaves them alone by default.

Saving#

Click Save geo settings or press Ctrl+S (Cmd+S on a Mac). The screen saves without reloading and confirms with a message in the corner.

Privacy#

With a CDN header, no outside service sees the visitor. With freeipapi.com or IP2Location.io, the visitor’s IP address is sent to that service to find the country. Mention this in your privacy policy if you use them.

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only