Geo-Targeting Ads – Documentation

You can use geo-targeting to display or hide ads for visitors coming from a specific location, i.e., a country, city, or continent. This feature is available within the “Geo Location” Visitor Condition included in the Geo-Targeting add-on.

Enabling Geo-Targeting

The Geo-Targeting add-on by Advanced Ads requires the GeoLite2 databases provided by MaxMind. Advanced Ads can connect with MaxMind and download the databases automatically for you. All you need is a free license key from MaxMind.

Download and connect the MaxMind databases automatically

Follow these steps to install the Geo-Targeting ads add-on. Generate a license key at MaxMind, and let Advanced Ads download the databases.

  1. Download and install the Geo-Targeting add-on
  2. Enable the license key at Advanced Ads > Settings > Licenses > Geo-Targeting
  3. Sign up as a GeoLite2 user for free at maxmind.com
  4. Generate a license key in your MaxMind account.
    • Select My License Key in the left navigation.
    • Click on Generate new license key.
    • Give your license key a title.
    • Select “No”, when you are asked “Will this key be used for GeoIP Update?”

Please note: the MaxMind license key will only be visible once, so please save it somewhere for later use. You can generate a new free license key in your MaxMind account anytime.

Getting a license key from Maxmind to enable geo-targeting ads
Getting a new license key from MaxMind
  1. Copy the generated license key to the field “MaxMind license key” in your Advanced Ads settings at Advanced Ad > Settings > General > Geo-Targeting
  1. Click “Update geo location database (~66MB)” to upload the files and connect with the databases.
    • if you get the error message “Database update failed”, please check if the license key is correct or try again later if it is a temporary error by MaxMind.
Updating the geo-targeting database

Advanced Ads will download the database files to the folder wp-content/uploads/advanced-ads-geo on your webhost. You can update the database after each first Tuesday of a month.

Manually upload the MaxMind databases

You can also manually download the MaxMind databases and upload them via FTP in the folder wp-content/uploads/advanced-ads-geo of your WordPress installation.

Follow these steps to upload the GeoLite2 databases manually:

  1. Sign up as a GeoLite2 user at maxmind.com and generate a license key as described above.
  2. Download the databases GeoLite2 City and GeoLite2 Country in the binary format from your MaxMind account. They are provided as GZIP files. You don’t need to download the SHA256 files.
  3. Unpack the GZIP files. Each archive contains a .mmdb file and two .txt files.
  4. Upload GeoLite2-City.mmdb and GeoLite2-Country.mmdb into the folder wp-content/uploads/advanced-ads-geo via FTP.
  5. Enter your MaxMind license key into the field “MaxMind license key” in Advanced Ad > Settings > General > Geo-Targeting. Save the settings afterward.

Please make sure to upload both .mmdb files. Advanced Ads will recognize the databases automatically. 

When the databases are successfully connected, you will see the confirmation “Geo Database found” at Advanced Ads > Settings > General > Geo-Targeting.

Using Geo-Targeting

To geo-targeting ads, go to the Visitor Conditions meta box on the ad edit screen and select the geolocation option.

Choose the "Geo Location" visitor condition for ad geo-targeting
To geo-targeting ads, choose “Geo Location” from the visitor conditions.

After selecting this condition, you can choose whether the ad should show up or be hidden for the location. Then select the country or continent. Inserting a city is optional.

Define a country, a region, or a city to specify the geo-targeting of your ads.

Display Ads by Country

To display or hide an ad by country, choose it from the second select field of the geolocation options.

The plugin provides a list of all available countries. If you are missing one, then please contact us.

You can find some widespread countries at the top of the list and the rest later. You can also just start typing the name to jump to it.

Leave the field for the city and state empty to target all visitors from that country.

Geo Targeting ad by Country
Example: displaying ads by country

Display Ads by City

To target an ad to a specific city, enter the city’s name into the City field.

You don’t need to select a country or state.

Geo Targeting Ads by City
Example: displaying ads by city

Display Ads by State/Region

The level of a state or region depends on the individual structure of the country you are targeting. To target a state, enter the name into the State/Region field.

You don’t need to select a country. Entering a city name would lead to the region being ignored in the check.

Geo Targeting Ads by State
Example: displaying ads by state/region

Display Ads by Continent

You find the selection of a continent in the second select field below the most common countries.

There is also a bulk option to select countries from the European Union. This selection is not identical to Europe as a continent.

With the UK leaving the EU in 2021, we removed this country from the EU choice.

geo targeting ads by continent
Example: displaying ads by continent

Targeting multiple geolocations

You can also target multiple geo locations, e.g., two or more different countries.

Geo targeting by multiple locations
Example: showing an ad in Los Angeles and San Francisco

To target multiple locations, you just add another visitor condition with the OR connector. There is no limit on areas you can combine with each other.

Using translated state or city names

The geolocation database provides some translations for city and state names. The availability of these translations depends on the country.

To check names in other languages, choose one from Advanced Ads > Settings > General > Languages of names.

Setting for Languages of Geo names
Choose the language of the state, region, or city.

There are up to 8 languages available. If the name you entered is not available in the chosen language, it will be checked against the English name.

Targeting locations by radius

You can target a region or larger area around a specific spot using the radius option.

geo-targeting ads by radius from a specific spot
Use the radius option to geo-target ads around a specific location

The usage is straightforward. Choose whether to include or exclude the given area, the distance, and whether it should be measured in kilometers or miles.

Then get the coordinates by entering a city name and click on the appropriate results to load the exact coordinates.

This option is also only as accurate as the underlying database and might still be off.

Getting coordinates for a particular city
Getting coordinates for a specific city

What else you need to know

Like with all dynamic ad conditions, an installed and activated cache can negatively influence the functionality. Use cache-busting in Advanced Ads Pro in such cases.

If you are missing more details for your targeted region, please check out the Extending the database section.

The Radius option might not work when your traffic uses a different nameserver, like Sucuri or Cloudflare.

Tests and issues

General issues

Please be aware that IPs are continually changing. The more populated the region, the more accurate geo-targeting is working.

Please note that the used GeoLite2 database by MaxMind might miss IPs, especially for small locations and cities. See the upgrade options below.

There is also a list of how accurate the lists are on a city level for each country. See GeoIP2 City Accuracy.

Caching and geo-targeted ads

On cached websites, make sure that you enable cache-busting under Advanced Ads > Settings > Pro.

If Cache-Busting is used, the Geo-Location visitor condition only looks up the location of the visitor ones. This could lead to unexpected behavior when you change the IP address while debugging the option.

To resolve this, you can:

  • Use a private window in your browser for each test. Close the window after each tested location.
  • Clear the advanced_ads_pro_visitor_referrer cookie after each check.
  • Disable cache-busting for the placement (only for testing).
Update the Visitor profile option when testing different locations in the same browser with cache-busting enabled.

Important changes due to the CCPA

Following the new privacy regulations set by the California Consumer Privacy Act (CCPA), MaxMind has changed the distribution of their free GeoLite2 databases. 

Since December 30th, 2019, MaxMind requires the users of their GeoLite2 databases to register for a MaxMind account and obtain a license key. This way, MaxMind can ensure that their service complies with the privacy regulations mandated in the CCPA.

They still offer their GeoLite2 databases free of charge and provide an insightful article about the changes here.

If you have installed the database files before December 30th, 2019, you should already have them on your server. But you should sign up as a new MaxMind user and obtain a free license key to comply with the CCPA. 

With the license key, the Geo-Targeting add-on can upload the files and connect with the database automatically as described above.

Geo-targeting test ad

The following ad shows your current position according to the geo-targeting database. It allows you to estimate how far it might be off for your position.

You can download this ad’s code on this page. Use it in the Plain text and code ad type and enable the Allow PHP option.

Once the database files are uploaded, you can geo-target your ads with the Visitor Conditions meta box on the ad edit screen.

Testing locations

Using a constant

This method is most appropriate when testing on a staging or new website.

You can set the constant ADVANCED_ADS_GEO_TEST_IP in your wp-config.php to simulate that traffic from all visitors on your website comes from a specific IP address.

define( 'ADVANCED_ADS_GEO_TEST_IP', '31.17.16.74' ); // some German IP address

Other resources for testing:

Using a VPN

You can use a so-called VPN to your website from a different “location”. Our team prefers using TunnelBear, which has a free plan large enough for testing.

There are also websites offering a VPN without installing anything or having to create an account. If you try them, then please make sure to test more than one service. We have found some of them to deliver unreliable results.

Troubleshooting

Debugging Geo-Targeting

To find a potential problem with geo-targeting, you can log all checks made by the plugin.

Add the following line to your wp-config.php file to log all checks done by the Geo-Targeting plugin.

define('ADVANCED_ADS_GEO_CHECK_DEBUG', true );

Once the constant is added, all checks will be written into the geo_check.log file in your wp-content folder. You can access it by using the following URL with example.com being your domain: http://www.example.com/wp-content/geo-check.log.

One log entry might look like this:

GEO CHECK (setting|visitor): COUNTRY |DE – REGION | – CITY new york|berlin

The value from the ad settings (left) and the one from the current user (right) are separated by a pipe (|). In the example above, the visitor is in Berlin, Germany (DE), but the ad setting is New York.

Note that COUNTRY and REGION will only be listed here if you provided a value in the geo-targeting Visitor Condition. When you set a continent, it will also be listed next to COUNTRY.

There is no error output if your IP is empty, e.g., when you are in a local environment.

Matching city and state names

Unfortunately, there is no list available for all regions. We suggest to enable geo-targeting debugging and get the regions from the log file.

Keep in mind that city and state names must be perfect matches with the geolocation database. Even small differences will result in a broken check.

Example: Bryanskaya Oblast’ and Bryanskaya Oblast’ are not the same string, because of the different apostrophe.

A good reference to ensure that you use the correct spelling is the ISO 3166-2 standard for representing names of countries and their subdivisions.

Missing entries and extending the database

The GeoLite2 database created by MaxMind might not be as accurate, especially for smaller areas.

MaxMind offers the GeoIP2 database with better accuracy on a country or city level. See their offers.

To use their additional database, just rename it to GeoLite2-City.mmdb for the city level and GeoLite2-Country.mmdb for the country level. Replace files with the same name in wp-content/uploads/advanced-ads-geo to use it.