API, Blog, PHP, WordPress, WordPress Shortcode

IP To Location (API)

Resolving your website visitors to a location is an intrinsic part of online marketing. The purpose of this post isn't intended to educate you on the benefits of delivering locally relevant content and advertising to your audience, or maximizing the conversion rate through geographically relevant call to actions (all of which we'll look at later). Instead, it's just a basic introduction to our IP to Location API.

Back in 2013 we set up LocateMyIP.info for our clients as a basic unmetered means of location services. While there's countless online tools that'll provide the same feature, we needed to return some Australian specific information. While that requirement remains, the need to maintain another website doesn't. There was a time when we would build a never-ending stream of websites for the purpose of monetizing multiple risk platforms... however, 900 or so sites later we realized our time was better suited to other tasks (more on this another time). So, while we'll likely retire the LocateMyIP platform sometime soon, we've migrated the (improved) API to BeliefMedia. All of the IP location related articles on all of our other websites will be rewritten and migrated here over the next couple of months.

Determine the IP Address of Your Visitor

Before you can make a request to our API, you're required to provide us with an IP address you want resolved. We've provided a function in the past that will serve this purpose.

Making a Request to the API

The API endpoint is as follows:

http://api.beliefmedia.com/geo/json.php?ip=XXX.XXX.XXX.XXX

Requires the IP parameter (?ip=123.456.789.123). If no IP is provided, the address of the requesting machine will be used. Click here to download sample JSON applicable to your current IP address.

Returned Data

We'll return JSON data with a status code (and message), ipaddress, ipversion, countrycode, countryname, regionname, cityname, latitude and longitude, timezone, zipcode, and host. We expect we'll provide more data in the near future.

The JSON data will translate to an array that looks like the following:

Array

(

[status] => 200

[msg] => OK

[data] => Array

(

[ipaddress] => 122.217.15.111

[ipversion] => 4

[countrycode] => JP

[countryname] => Japan

[regionname] => Tokyo

[cityname] => Tokyo

[latitude] => 35.6895065308

[longitude] => 139.691696167

[timezone] => +09:00

[zipcode] => 105-0004

[host] => 122x217x15x111.ap122.ftth.ucom.ne.jp

)

Example Usage in WordPress

Caching IP data will save repeated requests to the API for the same user, and it'll speed up your page-load on occasions where the same IP address is used. In the world of WordPress the last thing you want to do is bloat up your database with largely irrelevant IP data. Instead, we'll use our PHP cache functions to store data in local text files.

While we'll provide a ton of examples over time, in the below example we will demonstrate how you can return just the region name and country name of a user in a WordPress post or page.

While WordPress has threatened for over 10 years to include a core function to determine a client IP address, they have never done so. For this reason you'll also require our IP function as provided here.

Usage: Shortcode [ipgeo] returns what your IP address determines to be your location: Columbus (United States).

Copy and paste the WordPress function into your theme's functions.php file or, if you sensibly have one installed, your custom functions plugin.

<?php

IP To Location (API)

http://www.beliefmedia.com/ip-location-api

Requires the following:

http://www.beliefmedia.com/simple-php-cache

http://www.beliefmedia.com/get-ip-address

function beliefmedia_geo_country_city($atts) {

$atts = shortcode_atts(array(

'cache' => 3600 * 24 * 60

), $atts);

/* http://www.beliefmedia.com/get-ip-address */

$atts['ip'] = beliefmedia_ip();

$ip_transient = 'ip_' . md5(serialize($atts));

$cachedresult = beliefmedia_get_transient($ip_transient, $cache = $atts['cache']);

if ($cachedresult !== false ) {

$data = $cachedresult;

} else {

$data = file_get_contents('http://api.beliefmedia.com/geo/json.php?ip=' . $atts['ip']);

$data = json_decode($data, true);

$result = ($data['status'] == '200') ? beliefmedia_set_transient($ip_transient, $data) : false;

}

/* Built result from array */

if ($result !== false) {

$cityname = $data['data']['cityname'];

$countryname = $data['data']['countryname'];

$return = $cityname . ' (' . $countryname . ')';

} else {

$return = '(data unavailable)';

}

return $return;

}

add_shortcode('ipgeo', 'beliefmedia_geo_country_city');

If you require shortcode to work in a sidebar widget, you'll have to enable the functionality with a filter. If you're using our custom functions plugin, you'll have that feature enabled by default.

The data cached in a text file is the serialized array returned via our API. This means you may selectively retrieve returned data for the same IP address for different purposes.

Considerations

Again, the shortcode function requires our Simple PHP Cache and our IP function. The former functions will require that you define your cache directory. Setting it as a global is obviously the preferred method - but it's not necessary.
The host data can't be relied upon via the API. However, you can retrieve this result yourself with PHP's gethostbyaddr() function.
Throttling may apply to mitigate abuse.
We've cached data in our function for 60 days. IP address allocations rarely change.
IP to Location data isn't necessarily accurate - particularly on cellular networks. However, we'll be working to improve accuracy over time.
The API is very new. Please report errors.
If you're a client and have a geo-related featured on your site, we've already switched you over to the new API (with caching). Additionally, if you're using the API yourself, add &key=xxxxx to the API query string. This will bypass any throttling, and the API will return more information.

Download

Title: IP To Location (API)
Description: The BeliefMedia IP to Location API. Sample shortcode will return city and country. Requires PHP Simple Cache and IP Address functions. Client Use Only.
Download • Version 0.2, 702.0B, zip, Category: PHP Code & Snippets

■ ■ ■

Download our complimentary 650-page guide on marketing for mortgage brokers. We'll show you exactly how we generate billions in volume for our clients.