BoxLang 🚀 A New JVM Dynamic Language Learn More...

PresideCMS Extension: IP Geolocation API

v2.0.2+0000035 Preside Extensions

IP Geolocation APIs for Preside

Using IP lookup for extended geolocation data.


The IP Geolocation APIs extension provides:

  • Preside users with a set of rules engine expressions to use in dyanmic conditional content/access rules. e.g. "Visitor's country is 'UK'"
  • Developers with an interface to get a visitors geo location data

It reads geolocation data from two sources:

  1. Common headers (e.g. Cloudflare geolocation headers) - these can also be extended by admins in the configuration form.
  2. API (only when values not found in headers).


Install the extension with:

box install preside-ext-ip-geolocation-apis

Using the rules engine expressions

Once installed, users will immediately be able to build rules engine conditions using the "Visitor location" group of expressions.

These apply only to "web request" based conditions - they will not work in email content, for example.


API key

The extension gets uses the API to perform lookup calls to get extended geolocation data when not found in http headers. While you can use this API without a paid for API key, the usage is limited. Configuration of an API key can be provided in two ways:

  • Developer provided, via settings.whoisIpLookup.apiKey variables or WHOIS_IP_LOOKUP_API_KEY environment variable
  • Preside admin user provided: if no developer key is provided, users can navigate to System settings -> IP Geolocation API settings and enter an API key there


The extension uses a Cachebox cache named ipLookupCache to cache results of IP lookups. If you wish to configure your own cache, define your own cache in your application's /config/Cachebox.cfc file named ipLookupCache.

Extending header detection

By default, the system checks for Cloudflare headers in the form cf-ipcountry, cf-iplongitude, etc. If you wish to use different/more headers, these can be specified in the admin via System settings -> IP Geolocation API settings in the "Advanced" tab.

Developer API

If developers wish to use the extension to check geo location data, they should do so via the geoLocationService service component. Examples:

property name="geoLocationService" inject="geoLocationService";

// ...

var region = geoLocationService.getRegion();

if ( region == "England" ) {
	// ...

// see also:


We use SemVer for versioning. For the versions available, see the tags on this repository. Project releases can also be found and installed from Forgebox


This project is licensed under the GPLv2 License - see the LICENSE.txt file for details.


The project is maintained by The Pixl8 Group. The lead developers are Niall O'Doherty and Dominic Watson.

Code of conduct

We are a small, friendly and professional community. For the eradication of doubt, we publish a simple code of conduct and expect all contributors, users and passers-by to observe it.



  • Fix manifest ID


  • Fix expression issue when using listFind


Overhaul of the system:

  • Scrap use of extremeIp lookup API
  • Scrap public debug handler for ip lookups
  • Use api exclusively (using a separate open source module for its API)
  • Refactor API to focus on getting individual information points, e.g. getCountry(), etc.
  • Check common Cloudflare HTTP headers for geo location information where possible, avoiding API lookups
  • Introduce a cachebox cache for IP lookups
  • Introduce a preside healthcheck service for the API - if it goes down or we have network connectivity issues, do not block requests


  • Adding debug output for the test method proxyGetIp()


  • Fixing bug with getting the API key - removed incorrect Val()
  • Adding the ability to pass a test IP address in the URL using parameter test_ip_address
  • Adding check for the existence of a leading "/" in the endpoint URL, adding if missing
  • Adding API Key parameter "key=" to the URL for the extreme IP lookup service as per their updated docs -
  • Updated README with notes on the new requirement for the API key

1.3.2 & 1.3.1

  • Adding cache lookups for the IPv6 addresses to the rules engine expressions
  • Bumping the version numbers


  • Adding new service for IPv6 support
  • Adding caching to help with remain within 3rd party API rate limits
  • Changelog added


  • Fixing typo and updating instructions + bumping version numbers


  • Updating extension to allow for smaller HTTP call timeout values

$ box install preside-ext-ip-geolocation-apis

  • {{ getFullDate("2017-06-20T11:41:53Z") }}
  • {{ getFullDate("2023-10-27T09:23:00Z") }}
  • 3,332
  • 21,665