How to plugin geoPlugin to your pages
Using geoPlugin directly from your pages, requires a javascript call to geoPlugin.
This can be done in 1 of 3 ways.
Geo-localized javascript only
<script language="JavaScript" src="http://www.geoplugin.net/javascript.gp" type="text/javascript"></script>
For more information on how to use this output, see the Quickstart section on How To geo-localize your visitors.
To see the javascript that geoPlugin outputs, view the HTML source of this page
Statistics tracking only
<script language="JavaScript" src="http://www.geoplugin.net/statistics.gp" type="text/javascript"></script>
Statistics and Geo-localized javascript
(requires free registration)
Please DO NOT use this option if you have used either of the two above.
This example is simply a way to use both of the above in the same javascript call.
<script language="JavaScript" src="http://www.geoplugin.net/" type="text/javascript"></script>
Note: Statistics tracking will only work on activated domains that requires free registration.
How to geo-localize your visitors
1)
Enable the javascript code between the <head></head> tags of your pages:
<script language="JavaScript" src="http://www.geoplugin.net/javascript.gp" type="text/javascript"></script>
Once added, you will have geo-localized javascript functions available to your entire page.
These functions are as follows:
geoplugin_city()
geoplugin_region()
geoplugin_areaCode()
geoplugin_dmaCode()
geoplugin_countryCode()
geoplugin_countryName()
geoplugin_continentCode()
geoplugin_latitude()
geoplugin_longitude()
geoplugin_currencyCode()
geoplugin_currencySymbol()
geoplugin_currencyConverter()
function geoplugin_currencyConverter(amt, symbol) {
var converted = amt * 1
if (symbol == false) { return Math.round(converted * 100)/100; }
else { return '' + Math.round(converted * 100)/100; }
}You can call any of these javascript functions in your scripts to output the relevant geo-localized information about your visitor.
geoPlugin Web Service interface
Sometimes you need more flexibility in your scripts and want to localize your visitor on your server backend script rather than on the web page frontend output. geoPlugin allows you to do this2) without the hassle of installing complex and large databases, by using one of the geoPlugin Web Services.
PHP service
The PHP service is the most popular service and will return a PHP serialized array of all the information of your visitor. Described in detail here, and a quick quide is given below.
Call this service in your script using
http://www.geoplugin.net/php.gp?ip=xx.xx.xx.xx
Of course, substitute the xx's with your visitor's IP number.
As an example, the following PHP snippet
echo var_export(unserialize(file_get_contents('http://www.geoplugin.net/php.gp?ip='.$_SERVER['REMOTE_ADDR'])));
will output
array ( 'geoplugin_city' => '', 'geoplugin_region' => '', 'geoplugin_areaCode' => '0', 'geoplugin_dmaCode' => '0', 'geoplugin_countryCode' => 'US', 'geoplugin_countryName' => 'United States', 'geoplugin_continentCode' => 'NA', 'geoplugin_latitude' => '38', 'geoplugin_longitude' => '-97', 'geoplugin_regionCode' => '', 'geoplugin_regionName' => NULL, 'geoplugin_currencyCode' => 'USD', 'geoplugin_currencySymbol' => '$', 'geoplugin_currencyConverter' => 1, )
Alternatively, simplify things using the free PHP Class
JSON service
More flexibile that Javascript, JSON can be used for more server-side processing, so we built a JSON webservice interface to geolocate your visitors.
Described in detail here, and a quick quide is given below.
Call the JSON service in your script using
http://www.geoplugin.net/json.gp?ip=xx.xx.xx.xx
Again, substitute the xx's with your visitor's IP number.
Example output of a JSON query for your IP address (38.107.191.114) is:
geoPlugin({
"geoplugin_city":"",
"geoplugin_region":"",
"geoplugin_areaCode":"0",
"geoplugin_dmaCode":"0",
"geoplugin_countryCode":"US",
"geoplugin_countryName":"United States",
"geoplugin_continentCode":"NA",
"geoplugin_latitude":"38",
"geoplugin_longitude":"-97",
"geoplugin_regionCode":"",
"geoplugin_regionName":null,
"geoplugin_currencyCode":"USD",
"geoplugin_currencySymbol":"$",
"geoplugin_currencyConverter":1
})
XML service
XML is a versatile language, so we've added an XML interface too. Described in detail here, and a quick quide is given below.
Call the XML service in your script using
http://www.geoplugin.net/xml.gp?ip=xx.xx.xx.xx
Again, substitute the xx's with your visitor's IP number.
Example output of a XML query for your IP address (38.107.191.114) is:
<?xml version="1.0" encoding="UTF-8"?> <geoPlugin> <geoplugin_city></geoplugin_city> <geoplugin_region></geoplugin_region> <geoplugin_areaCode>0</geoplugin_areaCode> <geoplugin_dmaCode>0</geoplugin_dmaCode> <geoplugin_countryCode>US</geoplugin_countryCode> <geoplugin_countryName>United States</geoplugin_countryName> <geoplugin_continentCode>NA</geoplugin_continentCode> <geoplugin_latitude>38</geoplugin_latitude> <geoplugin_longitude>-97</geoplugin_longitude> <geoplugin_regionCode></geoplugin_regionCode> <geoplugin_regionName/> <geoplugin_currencyCode>USD</geoplugin_currencyCode> <geoplugin_currencySymbol>$</geoplugin_currencySymbol> <geoplugin_currencyConverter>1</geoplugin_currencyConverter> </geoPlugin>
geoPlugin Currency Converter
Those of you paying attention to the output of geoPlugin's web services would have noticed that the output of the geoplugin_currencyConverter variable is a number.
This value represents the exchange rate of one US$ for your visitor. If you trade in US dollars, then this value is very convenient. You simply call the geoplugin_currencySymbol value (to display the visitor's local currency) then multiply the price of your product by the geoplugin_currencyConverter value.
Voila! The price of your product is now displayed to the visitor in his/her local currency, with the correct exchange rate for that day
However, what can you do if your base currency isn't the US$? For example, a French site wants to sell goods based on the €uro.
For this, you need to tell the geoPlugin web service (Javascript, PHP, JSON, and XML all work the same) that your base currency is not USD.
You do this by adding &base_currency=XXX after the IP address.eg
http://www.geoplugin.net/php.gp?ip=38.107.191.114&base_currency=EUR
Now geoplugin_currencyConverter will output the exchange rate of one Euro for your visitor.
Adding Domains
(requires free registration)
Once you have registered and logged in, adding domains opens up the full potential of geoPlugin to those domains
Unless you specifically want geoPlugin on specific subdomains, register the main top-level domain, eg yourdomain.com that way all subdomains will be available to geoPlugin.
By doing this, you can always add specific subdomains later, if you require specific functionality (eg statistics) for specific subdomains.
In short, registering the main top-level domain is a catch-all for all domains under that main website.
Note: www.yourdomain.com is a subdomain. Even if your server is configured to treat www.yourdomain.com and yourdomain.com equally, geoPlugin does not know this. If you register www.yourdomain.com, then you will not be able to use yourdomain.com on geoPlugin, until you register it as a new domain. This is the most common mistake in getting your site to work with geoplugin!
To register a domain, login to the member area, and under Domain Management, click ”Add a domain”.
Once added, you will be sent an email on how to easily activate this domain.
Follow the instructions in the email you received when you registered a new domain to activate it.
No statistics nor geoPlugin javascript variables will be served until the domain is activated.
Activating statistics for a domain
(requires free registration and domain activation)
To have geoPlugin track your visitors using our powerful statistics program, simply add the following code anywhere in your pages:
<script language="JavaScript" src="http://www.geoplugin.net/statistics.gp" type="text/javascript"></script>
Note: The domain is www.geoplugin.net and not www.geoplugin.com
Naming pages
If you use dynamically-driven content eg index.php?variable1=value1&variable2=value2…etc all your pages in the statistics will appear to come from index.php.
If you wish to use more meaningful names in the statistics, then add the variable page=<yourpagename> to the javascript code.
<script language="JavaScript" src="http://www.geoplugin.net/?page=home" type="text/javascript"></script>
This will generate statistics for a separate page called “home”
Naming pages can also be divided into directories, e.g.
<script language="JavaScript" src="http://www.geoplugin.net/?page=products/albums/easy_listening/index" type="text/javascript"></script>
will generate statistics for a page called “index” under the submenus “products→albums→easy_listening”
Enable heatmaps to your page statistics
geoPlugin heatmap click tracking is a way to see where on your pages visitors click and is provided in a hassle-free way by simply by adding a simple variable to the geoPlugin statistics code to your pages. This is an excellent way to visualize a heatmap of clicks on a HTML page, showing hot and cold click zones allowing you to better organize your content.
geoPlugin heatmap click tracking is not enabled by default. To enable this feature, simply add the variable map_group=<yourpagename> to the javascript code.
<script language="JavaScript" src="http://www.geoplugin.net/?page=home&map_group=home" type="text/javascript"></script>
Once enabled, your heatmaps can be viewed when logged in, under the Statistics → Pages Viewed → Heatmap section
See also
- Quickstart User Guide
- In-depth User Guide