Geolocation Magic Macros

The Geolocation Magic Macros plugin for Revive Adserver, Magic Geo in short, enables you to dynamically insert the name of the geographic location of a visitor into a banner. This can be used in both the HTML code and the destination URL. Using this new feature, you can automatically make a banner adjust its content to the location of a visitor.


The banner below demonstrates this by showing your country name and country code, and the name of the continent, and a link to a Wikipedia article about your country.

The code used in this HTML banner looks like this:
You are currently in <a href="{}" title="read about {} on Wikipedia" target="_blank">{}, country code {geo.country_code}</a>, which is part of {geo.continent}.

Download and installation

Download this free plugin, and then read the instructions on installing plugins in Revive Adserver. Download Geolocation Magic Macros v1.0.0 (file size: 3.9 KB, downloaded 4,597 times)

Macro syntax

The Revive Adserver software (formerly known as OpenX Source) has always had a feature called ‘Magic Macros’, enabling users to dynamically insert certain values into a banner. The best known examples of these macros are {random}, {timestamp} and {clickurl}.

The Magic Geo Macros can be used in an HTML banner. They can also be used in the destination URL of any other banner type.

The Magic Geo plugin for Revive Adserver supports the following macros to display various location related information for any visitor:

  • {geo.continent_code} will display the continent code.
  • {geo.continent} will display the name of the continent.
  • {geo.country_code} displays the country code.
  • {} displays the country name.
  • {geo.region_code} displays the region code (region is the generic name for states, counties, provinces or regions, as defined in individual countries).
  • {geo.region} will display the region name.
  • {} displays the name of the city.
  • {geo.postal_code} will display the postal code of the visitor’s address.
  • {geo.latitude} and {geo.longitude} will display the latitude and longitude of the visitor’s location.
  • {geo.us_metro} will display the US Metro name of the visitor’s location. It is available for the north American continent only.
  • {geo.us_metro_code} displays the US Metro code for the visitor’s location.
  • {geo.area_code} will display the telephone area code for the area where the visitor resides.
  • {geo.organisation} displays the company or organisation name associated with the internet connection that is used by the visitor. It can be their place of work or the internet provider that provides the internet connection.
  • {geo.isp} will display the name of the Internet Service Provider (ISP) for the visitor’s internet connection.

Important notes:

  • Several of the macros described above rely on data that is not available by default in Revive Adserver. For instance, a default Revive Adserver installation will support the use of continent and country information. Information for other macros will come from various extra data files (some free, some paid) that are provided by MaxMind. Installing this plugin does not automatically add these data files, and it does not enable the geotargeting feature in Revive Adserver, which is disabled by default.
  • If you add the code .enc to the end of any of these macros, they will return the URL-encoded version of their output. For example:
    if the visitor is in New York, {} would return “New York” and {} would return “New+York”.

Sampe use cases

Here are a few examples of how Geolocation Magic Macros can be used:

  • Instead of a generic banner saying ‘See a list of shops in your country’ you can have a banner that says: “See a list of shops in {}” which automatically inserts the visitor’s country name into the banner.
  • If you have country flags for all countries, you could dynamically load the right flag for each visitor like this: <img src=”{geo.country_code.enc}.png” alt=”See a list of shops in {}” />
  • In the destination address of any banner, you could include the visitor’s country code or city name, for use with web analytics or to populate a form, for example like this:{geo.country_code.enc}
    or like this:{}&city={}

How geolocation works

Logo of MaxMindWhen someone visits a web page and sends an ad request to Revive Adserver, that request will always contain the IP address of the visitor. In a massive lookup table that’s created by companies like MaxMind, that IP address is then used to pin point the appropriate entry where the location information like country name, city name or DMA code can be found.

In Revive Adserver, a banner can be geotargeted, which means that the banner will only be displayed when the visitor is in a specific country or city, for instance.

What the Geolocation Magic Macros plugin for Revive Adserver adds, is the ability to dynamically display the geographic location names inside a banner.

How to enable geotargeting in Revive Adserver

Please read this article that explains how to enable and configure the geotargeting feature in Revive Adserver.

If you have a more detailed data file from MaxMind, then you will also have to go into the ‘Plugins’ tab of your Revive Adserver and select the ‘details’ link of the oxMaxMindGeoIP plugin. Then click the ‘Settings’ link and provide the exact full path of the files you have placed on your server. You must specify the absolute path, it’s not sufficient to enter a relative path.

A note about accuracy

Geolocation is not always completely accurate. It uses information that’s published by internet providers around the world. Companies like MaxMind conduct extensive research to complete this information. For example: some internet providers haven’t taken the trouble to assign the IP addresses they hand out to their customers to the actual geographic locations, but instead they report all of those IP addresses to be located at the address of their company headquarter. MaxMind attempts to find the correct locations. This is a time consuming and intensive process.

MaxMind publishes a free version of the country and city databases, and they have paid version of both as well, which are much more accurate. In addition, there are databases that contain information on regions (states, provinces, counties), metro code, organisation, ISP, and so on. We suggest that you consider obtaining a license for these paid GeoIP databases to get the most accurate results.

What you see below is a banner displaying all available Geolocation Magic Macros, so you can see how accurate the output is for your current geographical location. You will see both the standard and the URL-encoded versions of all macros. Logo of MaxMindWe want to thank MaxMind for providing us with a license to use their ISP and Organisation databases for the purpose of this demonstration. If certain values remain empty, that is because they are not defined for your geographic location.

Release notes

Version 1.0.0 – released March 1, 2011

  • Fixed: debug.log warnings during delivery of banners with no magic macros
  • Added: {geo.us_metro} and {geo.us_metro_code}
  • Deprecated: {geo.dma} and {geo.dma_code}

Version 0.9.9-beta – released July 23, 2010

  • This is a beta version of the “Geolocation Magic Macros” plugin, publicly released to collect feedback and suggestions.
  • As always with beta software, we suggest testing this plugin first in a staging environment or on a copy of your live system.
  • We do not accept responsibility for any problems arising from the use of this beta software.
  • This plugin does not make any changes to the existing tables in your Revive Adserver database, and it does not add any tables. It does not store or alter data in the database in any way.
You are currently in <a href=”{}” title=”read about {} on Wikipedia” target=”_blank”>{}, country code {geo.country_code}</a>, which is part of {geo.continent}.