Geolocation ajax API

POST /utils/geolocate.json.

Geolocate visitors based on their IP address - designed specifically for locale targeting in Evance. 

International websites may have a number of regionally targeted locales, offering translated or unique content for regional users. For example, a UK website may have a US locale in English for US and Canadian visitors (/en-us) and a Spanish version targeting visitors from Mexico (/es-us). 

This article does not stipulate the user experience (UX) for visitor geolocation, it only describes how to obtain geolocation and targeting data from the Ajax API. 

An easy-to-implement open source JavaScript library is available on Github at evanceit/theme-geolocator-js which implements the API calls below.

Request

Send a POST request to /utils/geolocate.json.

    jQuery.post('/utils/geolocate.json', function(response) {
        console.log(response);
    });

Accepted parameters

You may supply the following optional parameters with your POST request:

Response

A successful response from the API will include a JSON object containing success, status and data properties.

data.location

The location object represents the visitor's country based on their IPv4 or IPv6 address. 

data.locale.current

Contains information about the current locale if you localised the URL of your API request based on visitor's current locale. This is useful if you wish to include information about the current locale within a geolocation prompt, asking the user if they wish to change from the current locale to the recommended locale.

The current locale's information is also available using the website.locale property in EVML. 

Locale information includes:

data.locale.recommended

Contains a locale recommended by Evance for the user. This may be calculated based on the user's browser settings or manually targeted based on settings within Evance. The structure of the locale object is identical to that of the data.locale.current object (see properties table above).

data.locale.preferred

Contains the preferred locale for the user, or null if the user has not yet selected one (i.e. a new visitor). The preferred locale's ID is contained within an ev-locale cookie. This cookie is set automatically when sending a user to the url property returned in in any one of the locale objects. Evance provides this facility for your convenience, however you may wish to create a custom implementation. The structure of the locale object is identical to that of the data.locale.current object (see properties table above). 

Example JSON response

The response below represents a repeat visitor who is visiting a UK locale, but has been recommended the US locale based on their location. However, we acknowledge their preference to remain on the GB locale.

{
    "success": true,
    "status": 200,
    "data": {
        "location": {
            "countryCode": "US",
            "countryName": "United States",
            "acceptLanguage": [
                "en-us",
                "en"
            ],
            "isTargeted": true
        },
        "locale": {
            "current": {
                "id": "en-gb",
                "countryCode": "GB",
                "countryName": "United Kingdom",
                "languageCode": "en",
                "languageName": "English",
                "currencyCode": "GBP",
                "timezone": "Europe/London",
                "url": "/locale?direct=Lw%253D%253D&set=en-gb"
            },
            "recommended": {
                "id": "en-us",
                "countryCode": "US",
                "countryName": "United States",
                "languageCode": "en",
                "languageName": "English",
                "currencyCode": "USD",
                "timezone": "America/New_York",
                "url": "/locale?direct=Lw%253D%253D&set=en-us"
            },
            "preferred": {
                "id": "en-gb",
                "countryCode": "GB",
                "countryName": "United Kingdom",
                "languageCode": "en",
                "languageName": "English",
                "currencyCode": "GBP",
                "timezone": "Europe/London",
                "url": "/locale?direct=Lw%253D%253D&set=en-gb"
            }
        }
    }
}

Geolocation limitations

Geolocation in Evance is based upon the user's IP address (IPv4 or IPv6) to country-level only and is not 100% accurate. Our research has shown that geolocation accuracy significantly worsens when geolocating to state/region or city level. Since Evance's locale system is based on Country, we have no plans to geolocate beyond country level. 

Because IP addresses change regularly we update our IP address tables monthly. 

Website owners/administrators should be aware that visitors may bypass intended geolocation targeting when using a VPN.