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.

This page explains how to use the macros provided by this plugin, with examples and best practices

Documentation for Geolocation Magic Macros plugin

Before you proceed, follow the the instructions for installing a newly purchased plugin into your Revive Adserver installation.

Macro syntax and documentation

The Revive Adserver software 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 geographic location names and codes 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.is_in_eu} will display ‘true’ if the country is part of the European Union, otherwise it will display ‘false’
  • {geo.subdivision_1_code} will display the code of the higher level subdivision. For example the name of a state, province, or other high level administrative area
  • {geo.subdivision_1} will display the name of the higher level subdivision. For example the name of a state, province, or other high level administrative area
  • {geo.subdivision_2_code} will display the code of the lower level subdivision. For example the name of a country, region, metropolitan area, or other lower level administrative area
  • {geo.subdivision_2} will display the name of the lower level subdivision. For example the name of a country, region, metropolitan area, or other lower level administrative area
  • {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.accuracy_radius} will display the accuracy of the geographic location that was found for the visitor’s IP address, expressed in kilometers
  • {geo.time_zone} will display the name of the time zone the visitor’s location resides in
  • {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.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.

Examples

Default values

A default value can be added to any of the macros, to display some text in case the macro does not have a value for a specific IP address’ location.

The default is added by appending a | symbol plus the default text value at the end of the macro name.

Example: {geo.subdivision_2|Unknown for this location}

URL and JSON encoding

By default, all macros return a text value. These can be encoded for use in a URL or for use in code, by adding the .enc and .json modifiers.

Examples for a user residing in the London Metropolitan Area:

  • {geo.subdivision_1} will display ‘London Metropolitan Area’
  • {geo.subdivision_1.enc} will display ‘London+Metropolitan+Area’
  • {geo.subdivision_1.json} will display ‘”London Metropolitan Area”‘

Deprecated but still supported for backward compatibility

  • {geo.dma} will return the same value as us_metro; DMA means Designated Market Area
  • {geo.dma_code} will return the same value as us_metro_code
  • {geo.region_code} will return the same value as subdivision_1_code
  • {geo.region} will return the same value as subdivision_1

No longer supported with GeoIP2

  • {geo.area_code} used to return the telephone area code for the area where the visitor resides. This is no longer available with GeoIP2.