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

GeoLocation By IP

v3.0.0+16 Modules

Geolocation Lookup Module

GeoLocation-lookup-by-IP CI

This module will retrieve geolocation information for a specific user's ip address using the API available at


The following and more information will be retrieved for you:

  • cached
  • cityName
  • countryCode
  • countryName
  • latitude
  • longitude
  • regionName
  • timeZone
  • zipCode
<cfdump var="#getModel( 'GeoLocation@GeoLocation' ).getLocation()#">

Please note the cached key which will denote if the lookup is a fresh lookup or a cached request.


Apache License, Version 2.0.


  • Lucee 5+
  • ColdFusion 2018+
  • ColdBox 5+


Use CommandBox to install

box install GeoLocation-lookup-by-IP

You can then continue to configure the module in your config/Coldbox.cfc.

moduleSettings = {

    "GeoLocation-lookup-by-IP" : {
        // Cache subsequent ip address lookups for performance
		cache          : true,
		// How many minutes to cache the IP lookup
		cacheTimeout   : "60",
		// The default cache provider to use
		cacheName      : "default",
		// The cache prefix to use on all ip keys
		cacheKeyPrefix : "GeoLocation-",
		// Register here for free:
		developerKey   : ""



You can retrieve the main model via injection or requesting it from WireBox using the following DSL

  • GeoLocation@GeoLocation

There are two two public methods that you can use

  • getLocation() - To get a location from an IP Address
  • clearCache() - To clear the geo cache

You can also use our handy mixin called: getGeoLocation() from any handler, interceptor, layout or view.


var result = geoLocation.getLocation();

By default, it will use the IP address obtained from the CGI scope (taking into account a forwarded request). By default, this method will also cache the result in your default CacheBox provider for 60 minutes.

This method takes the following optional parameters that override the module defaults:

  • IPAddress
  • cache


This method will clear out any items in the cache that it put there.

This code comes with no warranties, promises, or rainbows. In fact, it will probably kick your cat.

Brad Wood

Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp


Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us. ." Romans 5:5


"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12


All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[3.0.0] => 2022-MAR-04


  • Upgrade to script
  • Upgrade to Coldbox 5+ Compatibility
  • Cleanup + formatting
  • Automation
  • New helper: getGeoLocation()
  • Case sensitivity for location details return structure
  • Added error logging to the response structure
  • Modernization of the code
  • Updated the retrieval of the IP address to a nice function
  • Added a cached key in the resposne to denote if the lookup is fresh or cached
  • Simplified the api to not be passing all the settings around

$ box install GeoLocation-lookup-by-IP

No collaborators yet.
5.00 / 2
  • {{ getFullDate("2013-06-07T09:07:45Z") }}
  • {{ getFullDate("2022-03-08T16:41:37Z") }}
  • 8,129
  • 5,521