Documentation is a work in progress.

(Category Country Aware plugin version 1.2.3 onwards)

Server side geolocation is simpler and faster. However; if you are using certain caching plugins then geolocation may have to be executed via your visitor’s browser.

The CCA plugin provides an API for those javascript coders and plugin developers who want client side country/EU geolocation. The CCA API has many advantages over other 3rd party geolocation API’s (see bottom of page).

The API response (the information returned by the API)

a JSON object contaning the following elements:

  • ['ccISO'] : the 2 character ISO country code of the visitor; or if unknown it is set to an empty string “”.
  • ['countryName'] the country name of the visitor; or if unknown it is set to an empty string “”.
  • ['isEU'] set to “y” if the visitor’s country is included in the (EU) country list (editable via your CCA settings); otherwise it is set to “n”.

API request:

CCA uses standard WordPress API functionality. You make an Ajax call to admin-ajax.php with the data argument action set to identify CCA’s ajax handler cca_get_geoinfo.


var args = {'action': 'cca_get_geoinfo'}; // CCA wp ajax handler
var cca_info = {ccISO: '?', isEU: '?', countryName: '?'}; // if need outside Ajax function (if unchanged from "?" AJAX has not finished)

jQuery.ajax({
  url: '//example.com/wp-admin/admin-ajax.php', type:'post', data:args, dataType:'json',
  success : function( response ) {
    cca_info = response; // provide object/array for use outside function 
    // and/or insert string into HTML by id etc etc
    // and/or set cookie or local storage to avoid running Ajax on subsequent pages
  },
  error : function(xmlhttprequest,textstatus,message) {
     console.log('fail:'+textstatus+':'+message);
     cca_info.ccISO = "error";
  }
});

The URL for admin-ajax.php will usually be something like “//example.com/wp-admin/admin-ajax.php” however plugin developers would normally use “admin_url(‘admin-ajax.php’)” and “wp_localize_script()” server-side PHP to make the url available to their javascript.

3rd Party vs CCA’s geolocation API

  • Free (and paid) 3rd party API’s may have a usage cap; CCA on your own site does not
  • When using a 3rd party API you are reliant on BOTH their, and your own site being up and running. Using CCA you’re only reliant on your own site.
  • Sites using CCA do not have to register and request an API key
  • GDPR: CCA API does not set a cookie or store any information as a result of the visitor’s API request. Information on the main 3rd party API websites is vague but seems to indicate API requests result in setting of cookies and/or storage of details in their own databases e.g. IP address and device type/version etc. i.e. with these API’s you probably need to obtain consent before use – i.e. you can’t check the location of your visitor to decide whether consent is required unless the user has already consented!