WP Engine’s powerful GeoTarget add-on is a great way for users to create customized and targeted content for users in different geographic locations, while still maintaining cacheability and scalability of your site. In this article we will explain how developers can use GeoTarget to implement custom content and functions.
NOTE: Before getting started, be sure you have fully enabled GeoTarget.
Users often face the struggle of finding a cacheable solution when implementing their geographically-customized content. For example, if a user wanted a Canadian phone number to show only for users in Canada and a US phone number to show for users in the United States, a developer would need to manually regenerate HTML for the page via PHP on every single page load, based on where the user is located.
With GeoTarget, WP Engine’s proprietary page caching system will store variations of the page for each geographic location in separate cache segments. Our GeoTarget system uses the GeoIP database from MaxMind to determine where the user is from, and serves them cached version from their location. This allows your site to scale better with waves of traffic while still providing a custom experience.
How to Use GeoTarget Shortcodes
After enabling the GeoTarget system (1. Install the plugin and 2. Contact Support), you will be able to use the GeoTarget shortcodes in your website’s Pages, Posts, and Widgets. GeoTarget Shortcodes are ideal to use when customizing different content to be displayed to your users around the globe. If you wish to perform PHP functions by using GeoTarget, such as redirects, popups, or custom banner messages, skip down to the GeoTarget PHP Environment variables section.
Use the following GeoTarget location shortcodes to print the location of a user:
NOTE: We don’t advise using region outside of the USA or Canada. In the USA, “region” will return state, in Canada “region” will return province. Otherwise “region” will simply return region number, which is not unique between countries.
To print out these variables, use the shortcodes in your Post, Page, or Widget as follows:
Welcome to our website! Hope the weather is great in [geoip-city], [geoip-region], [geoip-country].
If I was visiting this website from “Austin, Texas, US” the output would be as follows:
Welcome to our website! Hope the weather is great in Austin, TX, US.
Print conditional content based on location
You can use the
geoip-content shortcode to display different content conditionally, based on the geographic location of your users. The basic format of the shortcode is as follows:
[geoip-content bucket="value"]Your geographically-specific content here.[/geoip-content]
Your “bucket” can be any of the following values:
For example, if you wanted to say, “Guten tag” to users connecting from Germany, you could use the
geoip-content shortcode like so:
[geoip-content country="DE"]Guten tag![/geoip-content]
If you wanted to also say, “Bonjour” to customers connecting from France on the same page, you could use the shortcode in this way:
[geoip-content country="DE"]Guten tag![/geoip-content][geoip-content country="FR"]Bonjour![/geoip-content]
You can use GeoTarget to inform only EU visitors about GDPR privacy regulation compliance for your site, while hiding this information from other users around the world.
On your “About Us” page, you could display a message indicating the website’s compliance by using the following code:
Hide content from specific geographies
Use the “not-bucket” syntax to HIDE content from specific geographies.
Your “not-bucket” can be any of the following values:
For example, if you wanted to print, “Hello” to all of the US, but only to Texas visitors print “Howdy”, use this logic:
Testing geographically customized content may present a challenge. For example, you could use a Virtual Private Network (VPN) to “spoof” a user’s location. With GeoTarget, you can actually “spoof” locations much more easily just by adding arguments to the end of the URL you want to test.
NOTE: Spoofing locations in the following way will only work when testing the GeoTarget shortcodes, not when leveraging GeoTarget via PHP code.
To test how your homepage content may display to a user in Texas, use the following argument:
To test how your homepage content may displayed to a user in the United States, use the following arguments:
GeoTarget allows support for the following arguments:
You can also combine the arguments by adding an ampersand
& in between values.
Shortcode Best Practices
Apply shortcodes to multiple regions and separate by using commas
[geoip-content country="US, CA, BR, MX"]Americas content here[/geoip-content]
Exempt regions by narrowing specificity:
[geoip-content country="US" not-region="TX, CA, OR"]Content for everyone but Texas, California, Oregon[/geoip-content]
[geoip-content region="TX" not-city="Austin, Dallas"]Content for everyone but Austin and Dallas[/geoip-content]
Don’t get too granular or specific with your content:
[geoip-content city="Austin"]Hi person from Austin![/geoip-content] [geoip-content city="Los Angeles"]Hi person from Los Angeles![/geoip-content] [geoip-content city="New York"]Hi person from New York![/geoip-content]
- Instead, use the geolocation shortcodes as follows:
"Hi person from [geoip-city]!"
Don’t make an exception to an exception:
[geoip-content continent="EU" not-country="DE" city="Berlin"]Content to show to Europe, but exclude all of Germany except Berlin[/geoip-content]
Instead, use two shortcodes in lieu of making an exception to an exception:
[geoip-content continent="EU" not-country="DE"]Content to show to Europe, but exclude all of Germany[/geoip-content][geoip-content city="Berlin"]Content to show to Berlin[/geoip-content]
Don’t exempt a city that exists in two countries to which you are showing content:
[geoip-content country="US, FR" not-city="Paris"]Content to exempt from Paris, France[/geoip-content]
- The previous example would exempt Paris, TX and any other city in the US named “Paris.” Instead, use two shortcodes to achieve the desired results:
[geoip-content country="FR" not-city="Paris"]Content to show to all of France except Paris[/geoip-content][geoip-content country="US"]Content to show to US[/geoip-content]
PHP Environment Variables for GeoTarget
If you need to create a PHP function to perform an action based on a GeoTarget variable, you will need to include the PHP environment variables to do so. Shortcodes used in the GeoTarget plugin may not be used in your PHP code. As such, you will need to retrieve the environment in your PHP code as follows:
getenv( 'HTTP_GEOIP_COUNTRY_CODE' )
WP Engine’s GeoTarget system supports the following environment variables:
For an example of how to implement these PHP environment variables in your code, check out this example function to perform a redirect based on
MaxMind Country, Continent, and Region Codes
The accepted country and continent codes used in GeoTarget come from MaxMind can be viewed at the following links:
This variable is only available in the US due to limitations with the location data GeoTarget uses. Currently, the estimation of accuracy for Postal Codes is less than 25% of GeoIP requests. Therefore we don’t recommend using this unless absolutely necessary.
For “region,” the MaxMind database will use the standardized two-letter postal state or province abbreviation for the US and Canada. Other global “region” variables use the ISO-3166 standard, which include numerical region codes. These numerical region codes are often reused across multiple countries.
There can be many regions with the same region number in different countries. Without specifying the country, the following code will display in any country with a region 23 (Tierra Del Fuego, Argentina; Qina, Egypt; and Offaly, Ireland, etc…) (This is an example of what not to do):
[geoip-content region="23"] Content only for Shanghai, China [/geoip-content]
This means you should include both the country code and the region number to ensure you get the intended region within that country (This is the correct approach):
[geoip-content country="CN" region="23"] Content only for Shanghai, China [/geoip-content]
For a full list of region variables accepted by GeoTarget, view the following CSV provided by MaxMind:
When using GeoTarget there are some caveats to keep in mind. Due to the nature of GeoTarget there are some discrepancies users may experience that are outside of the control of WP Engine.
GeoTarget uses locations from the MaxMind GeoIP database. WP Engine does not control or update this database. For example, if unincorporated land became a city between the last time the MaxMind GeoIP database was updated and today, and a visitor from that city accessed your website, their city might not be interpreted correctly. If you need to submit a data correction request, you can use the MaxMind correction request form to do so.
LTE/4G/3G/Edge connections return null GeoTarget data as the information passed by cell towers currently don’t support Geolocation. If you are looking to use location services, which do not support mobile connections, you may want to instead refer to Android‘s or iOS’s native functionality documentation.
Proxies and VPNs
When customers access your website from an anonymous proxy or VPN, they may see content intended for a different audience as a result. Because a VPN or proxy service sends the request from a separate web server which may be located in another region, it’s possible that someone from one region may be presented with content intended for another. For example, if you use a proxy that allows a user to browse from a British IP address, you may see content with the “GB” country code because that is where the IP address is located, even if you are truly in the US.
Performance Best Practices
GeoTarget is unique in that it allows you to create customized content for users that also plays nice with cache. Each version of the page content is stored in its own cache “bucket” to serve to other users in that same bucket group. However, if you display different content for lots of extremely specific regions, you may “over-segment” your cache. This makes your cache less effective. In order for your site to scale effectively, you may want to make content for fewer, broader regions.
GeoTarget and GDPR
GeoTarget is a system which stores all location data client-side. This means WP Engine servers do not view or store data from your website’s users. As such, the Data Protection Acts do not apply to the location data stored by WP Engine GeoTarget. Read more about Location Data Regulations with GDPR.
WP Engine Scope of Support
The WP Engine Support team is available to assist with your GeoTarget questions via Live Chat, 24/7. Remember, our Support team cannot assist you with creating custom PHP code snippets. However, we are glad to explain how GeoTarget should work, best practices, and show you how to test your GeoTargeted content in your Posts and Pages. Bear in mind, however, that our Support team are not trained developers so debugging code would be best served by consulting a true developer.