Free website visitors geolocation with the ipstack API (Review)

Since its humble beginnings over 25 years ago, the world wide web has evolved in ways that even the best analysts could have never predicted. Form what was essentially a tool to help researchers share information, it has evolved into a consumer tool that many of us simply can’t live without. It has changed many aspects of our lives and we’ve come to rely on it, perhaps more than we should. It has become so commonplace that it is changing the retail industry. From big chains of brick-and-mortar stores, the top retailers are now web-based marketplaces.

To be successful, online retailers need not only to be present on the web, but they also need to fully utilize its features. One such feature is geolocation. This technology can allow a retailer to know the location of its website’s visitor, a useful feature to allow them to display estimated shipping charges or to present location-specific offers. One of the easiest ways to benefit from geolocation is to use a dedicated API that can be fed with an IP address and that will return any pertinent information about that address. The ipstack API is one such product and we’re about to discover how it does its magic and what it can do for you. We’ll have a look at the tool’s basic functionality as well as how it to use it. We’ll see how it performs, what type of documentation and support is available for the product and have a look at its rather simple pricing structure.

Introducing ipstack

At its core, ipstack is a geolocation API which uses multiple interconnected ISPs to provide accurate geographical data. You call the API from your website’s code and it will return a plethora of geographical data about your website’s users. You will, of course, get the user’s geographical location (isn’t that the main point?) but that’s not all. For instance, the tool will return a link to an image of the user’s country flag or an emoji version of it. Furthermore, you’ll get information about whether the user is accessing your site through a proxy. We’ll go in deeper details on all this as we look in deeper details at the available modules.

The project, initially called freegeoip.net, saw the light back in 2009 as an open source initiative to help developers. Through continuous improvement based on user feedback, it evolved some eight years later into the full-fledged product that we are looking at. During this time, the product’s user base grew up to over one hundred thousand satisfied customers. And they’re not just any customers. Giants like Microsoft or Samsung are using the API. So are Airbnb and HubSpot.

The ipstack API uses a highly dynamic scheme which updates its database multiple times a day, ensuring the integrity of the returned results. For this purpose, ipstack has partnered up with several large ISPs throughout the world. The tool performs all communication over 256-bit SSL-encrypted channel—using HTTPS—to secure all data transfers. Results can be returned by the API in either XML or JSON format, depending on your specific needs.

One of the best parts of ipstack API is its modularity. Various available module return increasingly more data about the user’s location. That makes for a very flexible tool. Speed is also one of the product’s forte. You call the API with the appropriate parameter(s) and get the requested results super fast. Currently, ipstack API handles more than two billion requests daily and it’s still responding almost instantly. Through a partnership with various ISPs, the product can cover some 2 million locations and over two hundred thousand cities worldwide. It also supports both IPv4 and IPv6 addresses.

How Geolocation Works

Before we go any further, let’s briefly pause and have a quick look at how geolocation looks. As you’d guess from ipstack’s name, it has to do with IP addresses. IP addresses can be compared—to a certain extent—to postal addresses. Each Internet-connected device has a unique IP address. But these IP addresses are not just randomly assigned to every device. There is some sense into it. Part of an IP address identifies the individual connected device and part of it identifies the network it is connected to. And the network part itself is hierarchically organized, somewhat like a computer disk directory tree. (I hope the engineers among our readers will forgive me for this oversimplification.)

This is similar to a postal address with a street number, a street name, a city, and, eventually, a country. And just like the British post has no idea where any US address is located, it will send US-bound mail to the USPS which will take care of routing the mail to the right location. And just like you could enter pretty much any postal address in a tool such as Google map and get the exact corresponding location, you can query a tool such as the ipstack API with an IP address to get its location.

This has some limitations, though. For instance, you won’t get the exact location from the IP address. What you’ll get is whatever the ISP supplying the IP address can provide. This is often not much more precise than the city or general neighbourhood although some providers return more information than others. Also, if the user is suing a VPN to access your website, what you’d get from such a lookup is the location of the VPN server they’re using.

Main Features Of The ipstack API

The developers of the ipstack API chose to use a modular approach with this product. It consists of various modules, each returning a different type of information. There are, for instance, modules of timezone, currency, or even security. You choose what module to use by using the appropriate parameters when sending the request to the ipstack API.

There are a few advantages to this approach. First, it makes the response easier to handle. If there was only one type of request returning all available data about an IP address, your website’s code would have to parse the whole answer to fetch whatever information it needs. Also, sending smaller requests—with smaller responses—can improve performance.

Let’s have a deeper look at each of the available module, how to call them and what their typical response looks like. That will give you a rather clear overview of what to expect from this powerful tool.

The Location Module

The ipstack API’s most basic module is the Location Module. It returns details about the physical location of the IP address provided in the query. You will get the IP address’ country, its main or official language as well as an emoji for the country’s flag which you can use to personalize your user’s experience.

Here’s a typical response to a query to the ipstack API. The first part is included with any query, regardless of the module requested:

ip: "142.243.254.224"
hostname: "142.243.254.224"
type: "ipv4"
continent_code: "NA"
continent_name: "North America"
country_code: "CA"
country_name: "Canada"
region_code: "QC"
region_name: "Quebec"
city: "Montreal"
zip: H2V
latitude: 45.5178
longitude: -73.6046

Most of the returned attributes are self-explanatory but you have detailed documentation on ipstack’s website should you need further help.

But since we’re talking about the location module, let’s have a look at what extra information is returned when using it:

location: Object {}
   geoname_id: null
   capital: "Ottawa"
   languages: Object {}
   code: "en"
   name: "English"
   native: ""English""
   code: "fr"
   name: "French"
   native: ""Français""
   country_flag: "https://assets.ipstack.com/flags/ca.svg"
   country_flag_emoji: "??"
   country_flag_emoji_unicode: "U+1F1E8 U+1F1E6"
   calling_code: "1"
   is_eu: false

As you can see, the extra information you get is mainly the country’s capital, the various languages in use in that location, a link to an image of the country’s flag and the unicode of the country’s emoji.

The Currency Module

The Currency module can be used to further improve your website user experience. This is particularly true of a shopping site as it will allow you to display prices in your user’s currency. The details provided include the local currency name and symbol as well as its plural name. The API won’t convert prices to the proper currency, of course, but it will allow you to use another API to convert your prices into the right currency for your visitors. Let’s have a look at what the output from the currency module looks like:

currency: Object{}
   code: "CAD"
   name: "Canadian Dollar"
   plural: "Canadian dollars"
   symbol: "CA$"
   symbol_native: "$"

The Security Module

Probably not as popular—or useful—as the previous modules, the Security Module is still interesting. It returns information about several security aspects of the incoming connection. For instance, it will tell you whether the site is accessed through a proxy and, if so, the type of proxy or whether the request came in through the tor network. It can also tell you that a request is from a crawler rather than an actual user. This type of information can be used to prevent scraping. The module also returns the threat level associated with the IP address provided, potentially allowing for crude protection against malicious requests. Here’s a look at the typical response from the Security Module:

security: Object{}
   is_proxy: false
   proxy_type: null
   is_crawler: false
   crawler_name: null
   crawler_type: null
   is_tor: false
   threat_level: "low"
   threat_types: null

The Time Zone Module

Another module which can come in handy to personalize your website visitors user experience is the Time Zone module. It returns some extra details about—you guessed it—your website visitors. One of the places where you could use such a feature in sites that deal with time-sensitive information. It allows you to display the correct time based on your users’ location.

The module provides information like GMT offset, current user time, time code, and time zone location as you can see from this sample response:

time_zone: Object{}
   id: "America/Montreal"
   current_time: "2019-07-09T12:39:22-04:00"
   gmt_offset: -14400
   code: "EDT"
   is_daylight_saving: true

The Connection Module

Last but not least is the Connection Module. This one is rather simplistic. All it returns is the autonomous system (AS) number associated with the source IP address as well as the ISP name. Well, it’s actually the name of the AS owner rather the ISP. Some organizations register their own autonomous system, as is the case in the example below:

connection: Object{}
   asn: 395399
   isp: "City of Montreal"

This is probably the least useful of all the modules but some will find it useful for various analytic purposes.

Working With the ipstack API

We’ve had a look at what information can be returned by the ipstack API, now is the time to have a look at how it is called. The ipstack API offers three different types of queries each with different parameters. There’s the Standard Lookup, the Bulk Lookup and the Requester Lookup. Let’s see how they differ. This is a nice feature as, for instance, the bulk request allows one to combine several requests into one, thereby reducing the total overhead and allowing for faster results. Let’s have a deeper look at each type of request.

Standard Lookup

As you might have guessed, the Standard Lookup is the most basic one. It returns the details about a single IP address that you provide when calling the ipstack API. It’s pretty simple to use and it will work with either IPv4 or IPv6 addresses. To make matters even easier, the product’s documentation provides sample code for the standard request in both PHP (cURL) and JavaScript (Jquery.ajax). If your website is build using either of these, using the API is really a no-brainer. Here’s a sample of a typical call to the API using simple HTML code:

https://api.ipstack.com/123.123.123.123?access_key=YOUR_ACCESS_KEY

In this example, YOUR_ACCESS_KEY would be replaced by the actual access key you got when you signed up for the service. You would also include the actual IP address you want information about rather than the dummy one in this example.

The results for a standard lookup include all the modules by default but extra parameters allow you to tune the request to your exact needs. All the details on the available parameters are clearly explained in the product documentation. Likewise, the default response is a JSON object but parameters can change that to an XML format.

Bulk And Requester Lookups

The Bulk lookup lets you request data against multiple IP addresses within a single request. Just like the Standard Lookup, you can get data on both IPv4 and IPv6 addresses. You can even mix both types of addresses in a single request. The format of the request is the same as that of Standard Lookup except that you specify multiple IP addresses separated by commas.

https://api.ipstack.com/123.123.123.123,124.124.124.124,125.125.125.125,
126.126.126.126?access_key=YOUR_ACCESS_KEY

The last type of request offered by the ipstack API is the Requester Lookup. It will return information on the IP address from which the request is coming. It’s the type of request you’d run from withing a client-side script. To make a Requester Lookup call, all you do is use the keyword “check” in lieu of an IP address. The other available request parameters are the same as for other request types.

https://api.ipstack.com/check?access_key=YOUR_ACCESS_KEY

How Does The ipstack API Perform?

The ipstack API is, more than likely, something you’d integrate into a real-time website. For example, you might want to serve different content based on the client’s location. In order to accomplish that, you need the API to perform blazingly fast. Any delay in the API response will translate into delays displaying the page to your client, something you’d more than likely want to avoid. The same is true no matter what you use the location data for. This is why the response time of the tool you’re using is of the utmost importance. While a geolocation API can provide a much-needed functionality, its failure to perform can have a disastrous impact.

For these reasons, you need to choose an API with good response time. We’ve done much of the hard work of testing various scenarios and ran tests with single or multiple IP addresses, some with more optional parameters, some with less. We were quite pleased with the results and got a rather consistent response time of around 100 ms, regardless of the request. Response was also consistent over time with no apparent “rush hours” when performance would suffer and it was also similar no matter where we launched the requests from. It seems like the ipstack servers are built to handle the load they get. Overall, it seems like using the ipstack API had barely any effect on website response seen from a user’s perspective.

Product Documentation And Support

It is often said that a product is only as good as its documentation. If that is true, the ipstack API has nothing to fear as its documentation is easy to find, use, and understand. The quality of the documentation also gives a measure of how much a software publisher cares about its users. Here again, there is nothing to worry about.

One of the best thing about this product’s documentation is, oddly enough, how little there is. Everything fits on a single, well laid out web page where you’ll easily find all you need. And to make thing even easier, a menu pane makes accessing any given section a breeze. The documentation covers everything from using the various types of requests to customizing the response.

In the highly unlikely case when you wouldn’t find what you need in the documentation, support is also available. It can take some time to initially reach the tech support but, once you do, they do respond rather quickly.

Pricing

Several pricing plans are available for the ipstack API. At the lowest level, there the free plan. As its name implies, this one is free. It is also somewhat limited. For starters, you can only run up to 10 000 queries per month. It also only includes the Location Module and access to support is limited. It can, however, be a great way to test the product and see how it can integrate into your environment.

The next level is the basic plan. This one sells for $9.99/month or $95.90/year (a 20% discount) and brings the requests limit up to 50 000/month. It also lets you use the Currency, Time Zone and Connection modules. Furthermore, enhanced support is also included with the plan as well as enhanced security through the use of SSL encryption.

The most popular plan is the professional one which sells for $49.99/month or $479.90/year. It gives you everything that’s included in the basic plan but raises the monthly requests limit to 500 000 and also includes the ability to do bulk requests.

At the top is the professional plus plan. It costs $99.99/month or $959.90/year. It is identical to the professional plan but it allows up to 2 million requests per month and it is the only plan to include the security module.

If that ain’t enough, there is also a customizable enterprise plan that can be arranged by contacting ipstack. It can include as many monthly requests as you might need as well various custom solutions based on a client’s specific needs.

In Conclusion

The ipstack API is an excellent product that will let you grab as much of the data you can get from an IP address quickly and easily. It has amazing response time, excellent documentation and good support which combine to make this a great value for the money. Also, the very fact that several Internet giants use it is probably a good testament to the product’s value.

This is definitely a product I’d recommend if you’re looking at exploiting the data that can be gathered for your website visitor’s IP address. And since a free—albeit limited—plan is available, there is no reason why you shouldn’t at least give it a try is see for yourself what it can do for you.