Geo Controller provides JavaScript objects that allow developers to access visitor geolocation information directly in the browser.
These objects can be used to personalize page content, populate form fields, display location-specific messages, and implement client-side behavior based on the visitor’s detected country, region, city, or other available geographic properties.
Geo Controller generates this information on the server and embeds it into the page when JavaScript integration is enabled.
1. Available JavaScript Objects
Geo Controller exposes geographic information through three global JavaScript references:
window.wp.geo— geographic information available through the WordPress global namespace.window.cfgeo— direct access to Geo Controller’s geographic data.window.cf.geoplugin— compatibility reference for integrations using the legacy object structure.
All three references point to the same geographic data object when the integration initializes successfully.
Recommended: Use window.cfgeo for new integrations. The other references are available for compatibility with existing implementations.
2. Enabling JavaScript Integration
To use Geo Controller data in JavaScript:
- Open the WordPress administration dashboard.
- Navigate to Geo Controller settings.
- Locate the JavaScript integration option.
- Enable JavaScript support and save the settings.
- Open a public page and verify that the geographic object is available.
When JavaScript support is enabled, Geo Controller inserts its geographic object into the page header.
If geographic information is unavailable, the object may not be generated.
3. Understanding the Geographic Data Object
The geographic object contains properties returned by Geo Controller for the current visitor.
Depending on the available data and plugin configuration, these may include:
ip— detected visitor IP address.country— detected country name.country_code— detected country code.region— detected region or state.city— detected city.continent— detected continent.continent_code— continent code.latitudeandlongitude— approximate geographic coordinates.timezone— geographic timezone information.currency— geographic currency code.in_eu— European Union geographic status.is_vat— geographic VAT-status indicator.flag— URL of the corresponding country flag image, when available.
Additional properties may be available depending on the geographic lookup result.
The values are provided as strings in the generated JavaScript object. For example, numeric indicators may be represented as "1" or "0", rather than JavaScript boolean values.
Example Geographic Data
The following example illustrates a subset of the available properties. It is not a complete or guaranteed API response.
{
ip: "216.73.217.104",
country: "United States",
country_code: "US",
region: "Ohio",
city: "Columbus",
continent: "North America",
continent_code: "NA",
currency: "USD",
timezone: "America/New_York",
is_eu: "0",
is_vat: "0"
}
The example IP address is reserved for documentation. The geographic values are illustrative.
Do not assume that every property is always present or populated.
4. Basic JavaScript Usage
To retrieve the visitor’s detected country, access the window.cfgeo object:
const geo = window.cfgeo;
if (geo) {
console.log('Country:', geo.country);
console.log('City:', geo.city);
console.log('IP:', geo.ip);
}
This example prints the available geographic information to the browser developer console.
Using a Safe Fallback
When writing reusable scripts, check whether Geo Controller has initialized before accessing its properties.
const geo =
window.cfgeo ||
window.wp?.geo ||
window.cf?.geoplugin;
if (geo) {
console.log(geo.country || 'Unknown');
} else {
console.log('Geo Controller data unavailable.');
}
This approach avoids JavaScript errors when the geographic object is missing.
It also supports the alternative global references provided by Geo Controller.
5. Displaying Geographic Information on a Page
You can use geographic information to update HTML elements dynamically.
HTML Example
<p>Your detected country: <span id="visitor-country">Unknown</span></p>
JavaScript Example
document.addEventListener('DOMContentLoaded', function () {
const geo = window.cfgeo;
const element = document.getElementById(
'visitor-country'
);
if (element && geo?.country) {
element.textContent = geo.country;
}
});
The script updates the text inside the selected HTML element using the visitor’s detected country.
Using textContent instead of innerHTML avoids interpreting geographic values as HTML markup.
6. Automatically Populating Form Fields
Geo Controller data can be used to populate supported form fields.
For example, you can automatically insert the detected city into an input field.
HTML Example
<input type="text" id="visitor-city" name="visitor_city" value="">
JavaScript Example
document.addEventListener('DOMContentLoaded', function () {
const geo = window.cfgeo;
const input = document.getElementById(
'visitor-city'
);
if (input && geo?.city) {
input.value = geo.city;
}
});
You can use the same approach with other geographic properties, such as country, region, or country code.
Important: Form fields populated with JavaScript can be modified by visitors. Always validate submitted values on the server when they affect application behavior.
7. Using Geo Controller With jQuery
Geo Controller’s geographic object can also be accessed through jQuery-based scripts.
For example:
jQuery(function ($) {
const geo = window.cfgeo;
if (geo?.address) {
$('#address').val(geo.address);
}
});
This example fills an input field with the available geographic address.
Geo Controller does not require jQuery simply to read window.cfgeo. Modern JavaScript can access the same object directly.
8. Geographic Conditional Logic
You can use the geographic object to display different messages based on the detected country.
Example: Country-Specific Messages
const geo = window.cfgeo;
if (geo) {
switch (geo.country_code) {
case 'US':
console.log('Welcome from the United States!');
break;
case 'GB':
console.log('Welcome from the United Kingdom!');
break;
case 'DE':
console.log('Willkommen aus Deutschland!');
break;
default:
console.log('Welcome to our website!');
}
}
This approach can be used for client-side personalization, regional messages, and non-security-sensitive user interface behavior.
9. European Union and VAT Indicators
Geo Controller exposes geographic indicators that can be used for informational purposes.
For example, check whether the visitor is detected in the European Union:
const geo = window.cfgeo;
if (geo?.in_eu === '1') {
console.log('Visitor detected in the European Union.');
}
Or check the geographic VAT-status indicator:
const geo = window.cfgeo;
if (geo?.is_vat === '1') {
console.log('VAT-related geographic indicator is enabled.');
}
Important: These properties represent geographic information. They do not establish a customer’s legal tax status, calculate VAT, verify identity, or provide a compliant consent management mechanism.
Do not use JavaScript geographic indicators as the sole basis for payment, taxation, authorization, or other security-sensitive decisions.
10. JavaScript and Full-Page Caching
Geo Controller generates its JavaScript geographic object on the server when the page is rendered.
This means the object contains geographic information associated with the request that generated the HTML.
If your website uses full-page caching, a reverse proxy, or a CDN, the generated HTML may be reused for subsequent visitors.
For example, a page originally generated for a visitor from Germany could be served from cache to a visitor in the United States. In that situation, the JavaScript geographic object may still contain the German visitor’s geographic values.
Important: Reading window.cfgeo does not independently perform a new geolocation lookup. It reads the geographic information already embedded in the page.
How to Handle Caching
For websites that require location-aware JavaScript data:
- Review your full-page caching and CDN configuration.
- Use an appropriate geographic cache variation strategy where available.
- Exclude relevant pages from shared full-page caching when necessary.
- Test geographic output from different visitor locations.
- Do not assume that a browser refresh forces the server to generate new geographic information.
For applications requiring a fresh server-side lookup, use a separately implemented and appropriately secured request to a supported API endpoint.
The standard JavaScript geographic object should not be treated as a real-time lookup service.
11. Accessing Geographic Data Through an External Application
If your application needs to retrieve geographic information independently of the current page, Geo Controller provides authenticated API endpoints for supported installations.
The API supports authentication and geographic lookup through the selected WordPress AJAX or REST transport.
For security reasons, external applications should authenticate through a trusted server-side component rather than exposing API credentials or access tokens in publicly accessible JavaScript.
For more information, see:
12. Troubleshooting
window.cfgeo Is Undefined
If the geographic object is unavailable:
- Confirm that Geo Controller is installed and activated.
- Verify that JavaScript integration is enabled in Geo Controller settings.
- Check whether geographic information is available for the current request.
- Inspect the generated HTML for the Geo Controller JavaScript object.
- Verify that the script accessing the object executes after it has been initialized.
JavaScript Displays the Wrong Country
Check the geographic information returned by Geo Controller and review your website’s caching configuration.
If a CDN or full-page cache serves previously generated HTML, the embedded geographic values may belong to an earlier request.
A Geographic Property Is Missing
Not every geographic property is guaranteed to be available.
Some properties may be excluded from the generated JavaScript object, and others may be unavailable in the underlying geographic lookup response.
Always check for missing or empty values before using them.
JavaScript Executes Before Geo Controller Initializes
Geo Controller inserts its JavaScript geographic object into the page header when the integration is enabled and geographic data is available.
If your script executes too early, the object may not yet exist.
Use appropriate script loading order or initialize your code after the document is ready.
13. Developer Filters
Geo Controller provides WordPress filters for developers who need to customize the JavaScript geographic object.
The following filters are available in the integration:
cfgp/public/js/exclude— customize the list of geographic properties excluded from the generated JavaScript object.cfgp/public/js/objects— modify the generated JavaScript property definitions before output.cfgp/javascript_support/flag— customize the country flag URL generated for JavaScript.
These filters execute on the server while Geo Controller prepares the JavaScript output.
Developer note: The cfgp/public/js/objects filter receives generated JavaScript property fragments rather than a normalized associative array. Custom output must preserve valid JavaScript syntax and should be carefully validated before production use.
Related Documentation
Summary: Geo Controller provides geographic information through window.cfgeo, window.wp.geo, and the legacy window.cf.geoplugin reference. These objects allow developers to build location-aware browser experiences using data embedded during server-side page rendering. For fresh authenticated lookups, use the supported API through a trusted backend.
