Understanding WP Geo Controller’s Lookup and Caching Architecture

If you’re using WP Geo Controller to personalize content, control WooCommerce behavior, or enforce regional logic, understanding how its lookup and caching architecture works is essential.

Many WordPress site owners assume geolocation happens in JavaScript or through repeated API calls. In reality, WP Geo Controller is built around a server-side lookup + smart caching model designed for performance, scalability, and cache compatibility.

In this article, we’ll break down:

• How the geolocation lookup process works
• How API results are cached
• How shortcodes and PHP retrieve data
• How JavaScript accesses location data
• How caching layers and proxies affect behavior
• Best practices for performance and reliability

1. The Core Principle: Server-Side First

WP Geo Controller performs geolocation lookups on the server, not in the browser.

This is a critical architectural decision because it ensures:

• Fast execution
• Consistent PHP and JS data
• Cache-friendly behavior
• No client-side API exposure
• No duplicate lookups per request

JavaScript never performs the lookup. It only reads data that has already been resolved and embedded into the page output.

2. How the Lookup Process Works

Let’s walk through what happens when a visitor loads your site.

Step 1: Visitor IP Detection

The plugin determines the visitor’s IP address. If you’re behind a proxy like Cloudflare, the correct forwarded IP is used (when configured properly).

Step 2: Lookup Layer

The lookup layer (via the internal API class) resolves geolocation data for that IP. This may include:

• Country
• Country code
• Region
• City
• Latitude / Longitude
• Timezone
• Currency
• EU / VAT status
• Proxy / TOR detection

Important: the lookup is not executed every time you request data.

Step 3: API Result Storage

The result is stored in the plugin’s internal cache under the key API. From this point forward, all data access pulls from the cached result — not from a new API request.

3. The Role of CFGP_U::api()

In PHP, the main access point for geolocation data is CFGP_U::api().

Key facts:

• It reads from the cached API result
• It does not perform the lookup itself
• It stores results in a static variable for the current request
• It applies a WordPress filter before returning values

Example usage:

$geo     = CFGP_U::api( false, [] );     // full API array
$country = CFGP_U::api( 'country_code', '' );
$city    = CFGP_U::api( 'city', 'Unknown City' );

This architecture ensures:

• Zero duplicate lookups
• Minimal database hits
• Fast repeated access within the same request

4. How Shortcodes Use the Cache

The core shortcode is [cfgeo]. When no custom IP is provided, it reads the already cached API data (rather than doing a new lookup).

Common examples:

[cfgeo return="country_code"]
[cfgeo return="city" default="Unknown city"]

Conditional wrappers such as [cfgeo_in_eu], [cfgeo_is_vat], and [cfgeo_is_proxy] also rely on the same cached API result, which keeps output consistent across the entire page.

5. JavaScript Architecture: No Client-Side Lookups

From version 6.x.x and above, WP Geo Controller injects geolocation data directly into the HTML and exposes it globally via:

• window.wp.geo
• window.cfgeo
• cf.geoplugin (legacy)

Recommended access pattern (frontend reads, never looks up):

(function(geo){
    if (!geo) return;
    console.log(geo.country);
}(window.wp.geo || window.cfgeo || cf.geoplugin));

Important points:

• JS reads server-provided data
• No async API calls required
• No external HTTP requests
• Fully cache-friendly

6. AJAX Lookup and Cache Bypass

In heavily cached environments (full-page caching, aggressive CDN), embedded geo data may be stale or unavailable.

WP Geo Controller provides a dedicated AJAX action cfgeo_cache to fetch fresh data server-side and return JSON. It should only be used when necessary, and it requires a valid nonce.

$.ajax({
    method: 'POST',
    url: ajaxurl + '?action=cfgeo_cache',
    data: { cfgeo_nonce: GEO_NONCE },
    cache: false
}).done(function(data){
    console.log(data);
});

7. Internal Caching Layers Explained

WP Geo Controller uses multiple caching layers:

1) Static Request Cache

Within a single PHP request, API data is stored in memory so repeated reads are instant.

2) Plugin Cache Storage

The API result is stored via the plugin’s caching system (keyed as API).

3) WordPress Object Cache (if available)

If your site uses persistent caching (Redis/Memcached), repeated reads can be faster across requests.

4) Page Caching Compatibility

Because lookups happen server-side, page caches can store rendered output — as long as your caching strategy is compatible with geo-personalization.

8. CDN and Proxy Considerations

If your site uses Cloudflare, reverse proxies, or load balancers, correct visitor IP detection is essential.

Improper proxy configuration can lead to:

• All visitors resolving to one country
• Incorrect EU/VAT detection
• Broken WooCommerce geolocation behavior

9. Why This Architecture Is Performance-Optimized

Compared to client-side geolocation solutions, WP Geo Controller’s architecture is optimized for production:

• Server-side lookup
• Single lookup per request
• Shortcodes and PHP read cached data
• JS consumes embedded data without extra calls
• Better compatibility with WooCommerce and caching layers

10. Best Practices for Stable Operation

• Prefer embedded geo data over repeated AJAX refresh calls
• Monitor daily lookup usage (especially on limited plans)
• Configure proxy / Cloudflare headers correctly
• Use shortcodes for content personalization where possible
• Use CFGP_U::api() for PHP reads, not custom duplicate logic
• Treat frontend geo objects as read-only

11. Migration Note: Deprecated CF_Geoplugin Class

The legacy CF_Geoplugin class is kept for backward compatibility. New projects should prefer:

• CFGP_U::api() for PHP
• [cfgeo] and conditional shortcodes for content
• Global JS objects like window.wp.geo / window.cfgeo

Final Thoughts

Understanding WP Geo Controller’s lookup and caching architecture helps you:

• Debug issues faster
• Avoid unnecessary API usage
• Build scalable geo-personalized experiences
• Stay compatible with caching and CDN setups

In short: the lookup resolves once, the result is cached, and every layer (PHP, shortcodes, JS) reuses the same data.