The Geolocation Magic Macros plugin for OpenX, 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.

Demonstration

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="http://en.wikipedia.org/wiki/{geo.country.enc}" title="read about {geo.country} on Wikipedia" target="_blank">{geo.country}, 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 or upgrading plugins in OpenX.

Download: Geolocation Magic Macros plugin for OpenX 2.8+ Version: 0.9.9-beta Updated: July 23, 2010 Size: 3.78 KB

Stay informed about future releases

Subscribe to our mailing list and receive a short e-mail whenever a new version of this plugin is available.

Macro syntax

The OpenX Ad Server 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}. A white paper on the OpenX website documents the use of Magic Macros.

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

The Magic Geo plugin for OpenX 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.
• {geo.country} 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.
• {geo.city} 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.dma} will display the Designated Market Area (DMA) of the visitor’s location. DMA is generally available for the north American continent only.
• {geo.dma_code} displays the code of the DMA 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 OpenX. For instance, a default OpenX 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 OpenX, 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, {geo.city} would return “New York” and {geo.city.enc} 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 {geo.country}” 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=”http://www.example.com/images/flags/{geo.country_code.enc}.png” alt=”See a list of shops in {geo.country}“ />
• In the destination address of any banner, you could include the visitor’s country code or city name, for use with webanalytics or to populate a form, for example like this:
  http://www.example.com?DV={geo.country_code.enc}
  or like this:
  http://www.example.com?country={geo.country.enc}&city={geo.city.enc}

How geolocation works

When someone visits a web page and sends an ad request to OpenX, 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 OpenX, 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 OpenX adds is the ability to display the geographic location names inside a banner.

How to enable geotargeting in OpenX

You have to be logged in as an administrator to enable and configure the geotargeting features of OpenX.

There is a documentation page on the OpenX website that explains how to enable geotargeting in the OpenX Ad Server. Simply switch to ‘OpenX MaxMind (Flat File)‘ and ‘Save changes’ to enable country-level geolocation lookups and geotargeting.

If you have a more detailed database from MaxMind, then you will also have to go into the ‘Plugins’ tab of your OpenX 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.

We 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 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 OpenX database, and it does not add any tables. It does not store or alter data in the database in any way.