Introduction
As web developers, we have to work harder than mobile app developers to gather information about our site visitors. Today, I'll introduce you to the ipstack API, a service that provides our users' geolocation, timezone lookup, language, currency and organizational identity with a simple low latency query.
ipstack can also provide background security data on your visits helping you identify bots, crawlers, anonymous users and bad actors.
The home page for the ipstack.com website and its ip2location time zone lookup an, language and currency services.
The power of having one low latency query to provide this information is potent for any web developer who wishes to provide dynamic experiences for users. ipstack's average response time is typically 20-50ms.
Here's an example of a subset of an ipstack API response. I had to reduce and adjust it slightly to fit all of the results in a single image. This response is in JSON but XML is also available.
Example of JSON response of an ipstack query for free geolocation, IP to language, timezone lookup, currency, et al.
Essentially, they offer free IP to location or geolocation, IP to language, IP to timezone aka timezone lookup as well as additional hostname and ASN lookups and security details.
ipstack is the result of its merger with FreeGeoIp, which you have likely heard of. The latter service handled more than 2 billion requests worldwide per day. ipstack is providing a faster, more advanced and more scalable API service. And, they already have over 100,000 customers.
ipstack's geolocation service remains completely free for up to 10,000 requests, which is excellent for startups and entrepreneurs. The majority of the remaining services are available for $9.99 month with a 20% annual discount available.
ipstack response data is also available in eight languages English/US, German, Spanish, French, Japanese, Portuguese (Brazil), Russian, and Chinese.
At last, there's an affordable, easy to work with alternative to larger corporate geolocation entities and it's ipstack.
The provider behind ipstack is apilayer. I've written about this intriguing company here before. One of my favorite aspects of their sites are how universally simple and easy to access their services are.
apilayer does a great job providing well-designed, easy to integrate, fast, scalable and affordable web services for a variety of customers.
You can read some of earlier tutorials about them below:
- Introduction to the coinlayer Real Time Cryptocurrency API
- Introduction to the eversign Electronic Signature API
- How The Streetlayer API Lets You do Real-time, International Address Validation and Autocomplete
Let's dive into exploring the ipstack API.
Getting Started with ipstack's Free Geolocation API
Get Your Free API Key
To get started with ipstack, click the orange GET FREE API KEY button in the navigation bar. You can start with the free plan or choose a higher capacity plan. At this time, you can also select monthly or annual billing for a 20% discount.
ipstack Pricing
For individuals just starting out with the API, there is a free account that allows 10,000 requests per month. They always allow you to exceed your account level volume limit by 20% before restricting queries.
ipstack's pricing page showing Free, Basic $9.99, Professional $49.99, Professional Plus $99.99 and custom volume plans.
For $9.99 per month, you get 50,000 requests per month, ip2location, currency information, timezone lookup and hostname and ASN organizational details. The ASN is a code associated with the organization that manages a range of IP addresses.
Higher level plans provide bulk processing, which allows you to gather data about large numbers of ip addresses you already have, often from your existing customer base. With the Professional Plus plan at $99.99 per month, you gain access to security details. Again, 20% discounts are available for annual accounts.
All paid plans gain SSL access via HTTPS.
The Sign Up Form
Once you've chosen a plan you'll be asked to complete a sign up form. It's very straightforward:
Blank sign up form at ipstack's website ipstack.com.
Once completed, you'll land in the dashboard and receive a friendly email with links to documentation and support.
Welcome email received after signing up at ipstack.com.
The ipstack API Dashboard
The Quickstart Guide
ipstack's API dashboard provides your API key and a simple 3 step quickstart guide:
3-step quickstart guide at ipstack after sign up.
Step 1 - Your API Access Key
Your API access key provides access to the ipstack API. It's required to be included as a parameter in every call. You can also reset the key to secure a new one whenever you wish.
Step 2 - Reviewing the Six API Endpoints
Overall, there are three primary methods for making use of ipstack API services:
- Standard Lookup: Looks up the data behind a specific IP address you provide in the request.
- Bulk Lookup: Look up the data for multiple IP addresses at once, which you provide in the request.
- Requester Lookup: Look up the data behind the IP address the current API request is coming from i.e. the requesting API is the specified IP address.
Base URL: Whichever API method you choose to use, all API requests to the ipstack API start out with the following base URL: https://api.ipstack.com/
// Standard IP Lookup - look up the data behind an IP address
https://api.ipstack.com/134.201.250.155
? access_key = YOUR_ACCESS_KEY
// optional parameters:
& fields = ip,location,security
& hostname = 1
& security = 1
& language = en // ip to language
& callback = MY_CALLBACK
& output = jsonHere's an example response in JSON:
{
"ip":"104.128.136.44",
"type":"ipv4",
"continent_code":"NA",
"continent_name":"North America",
"country_code":"US",
"country_name":"United States",
"region_code":"WA",
"region_name":"Washington",
"city":"Seattle",
"zip":"98168",
"latitude":47.4891,
"longitude":-122.2908,
"location":{
"geoname_id":5809844,
"capital":"Washington D.C.",
"languages":[
{
"code":"en",
"name":"English",
"native":"English"
}
],
"country_flag":"http:\/\/assets.ipstack.com\/flags\/us.svg",
"country_flag_emoji":"\ud83c\uddfa\ud83c\uddf8",
"country_flag_emoji_unicode":"U+1F1FA U+1F1F8",
"calling_code":"1",
"is_eu":false
},
"Time_zone":{
"id":"America\/Los_Angeles",
"current_time":"2018-07-25T17:26:46-07:00",
"gmt_offset":-25200,
"code":"PDT",
"is_daylight_saving":true
},
"currency":{
"code":"USD",
"name":"US Dollar",
"plural":"US dollars",
"symbol":"$",
"symbol_native":"$"
},
"connection":{
"asn":63008,
"isp":"Contina"
}
}Note that ipstack allows you to customize and minimize the response set of the data request to improve response times and minimize bandwidth.
Continued from page 1.
The third step of the quickstart is to dive into the API documentation, but before we do that, I'd like to show you how simple it is to make requests and work programmatically with the response data. That's a common barrier web developers face when learning new APIs.
Querying the Endpoints in Multiple Programming Languages
Here's a PHP cURL-based example for making requests (from ipstack's documentation):
Screenshot of PHP cURL example of calling their API methods. Code is available in their documentation.
The $api_result decodes the JSON into an accessible array.
And here's one in JavaScript using AJAX:
Screenshot of jQuery ajax example of calling the ipstack API methods. Code is available in their documentation.
Parsing the JSON Response Data
As you can see above, parsing the JSON responses are fairly straightforward whichever language you prefer in the moment. Here are a couple more examples.
This uses the PHP shell interpreter to further demonstrate json_decode. I requested compressed format for the API for this demonstration (e.g. format=0):
$ php -a
Interactive shell
php > print_r( json_decode('{"ip":"134.201.250.155","type":"ipv4","continent_code":"NA","continent_name":"North America","country_code":"US","country_name":"United States","region_code":"CA","region_name":"California","city":"Huntington Beach","zip":"92648","latitude":33.6746,"longitude":-118.0086,"location":{"geoname_id":5358705,"capital":"Washington D.C.","languages":[{"code":"en","name":"English","native":"English"}],"country_flag":"http:\/\/assets.ipstack.com\/flags\/us.svg","country_flag_emoji":"\ud83c\uddfa\ud83c\uddf8","country_flag_emoji_unicode":"U+1F1FA U+1F1F8","calling_code":"1","is_eu":false},"time_zone":{"id":"America\/Los_Angeles","current_time":"2018-07-25T17:51:07-07:00","gmt_offset":-25200,"code":"PDT","is_daylight_saving":true},"currency":{"code":"USD","name":"US Dollar","plural":"US dollars","symbol":"$","symbol_native":"$"},"connection":{"asn":25876,"isp":"Los Angeles Department of Water & Power"}}',true));This returns the following structured array:
Array
(
[ip] => 134.201.250.155
[type] => ipv4
[continent_code] => NA
[continent_name] => North America
[country_code] => US
[country_name] => United States
[region_code] => CA
[region_name] => California
[city] => Huntington Beach
[zip] => 92648
[latitude] => 33.6746
[longitude] => -118.0086
[location] => Array
(
[geoname_id] => 5358705
[capital] => Washington D.C.
[languages] => Array
(
[0] => Array
(
[code] => en
[name] => English
[native] => English
)
...Or, you can use the JavaScript JSON.parse() method for JavaScript in your browser's developer console:
Screenshot of console output after JSON.parse operation on API result.
You can see how quickly and easily it is to translate the JSON strings ipstack returns into usable arrays or objects.
That's basically my standard for assessing good APIs: how quickly can I make my first request and use the data for my application? ipstack delivers on this well.
Using the ipstack Endpoints
The first ipstack geolocation endpoint is the Standard IP Lookup. Here's a screenshot of their dynamic documentation, which works well throughout all of ipstack and all of apilayer's other services.
Screenshot of ipstack geolocation documentation for Standard IP Lookup showing parameters.
The parameters give you a number of options. You can customize the response data with fields, turn on or off hostname lookup and security module data and choose the language for the response e.g. English, French, etc. There is also a callback option which allows the response data to be fed to a JavaScript function. I'll demonstrate further on in this article.
Here's a sample response from the IP Lookup documentation. I've clicked the XML button at the bottom right to switch the response format:
Screenshot of XML response of ipstack Standard IP Lookup.
What if we'd like to request data for a large number of IP addresses? Let's move on to the Bulk IP Lookup method.
The Bulk IP Lookup Endpoint
The ipstack Bulk IP Lookup endpoint allows you to query multiple IP addresses in a single request. The usage is similar to the Standard IP Lookup endpoint but the response includes data for all the requested IP addresses.
Screenshot of ipstack documentation for Bulk IP Lookup showing calling parameters.
You can use this in various ways. Here are a couple ideas:
- You can gather IP addresses from your logs and analyze your traffic for location, language, et al.
- If you track IP addresses in your database, you can analyze existing application users and gather more information from them.
The API responds with a series of results in sequence:
Example of response data in XML, a series of results for two ip addresses, from the Bulk Lookup endpoint
Again, you can customize and minimize the response set of the data request to improve response times and minimize bandwidth.
Requester IP Lookup
The Requester IP Address Lookup returns the same response data as the standard IP lookup above, but it provides this data for the requesting IP address e.g. the current server or the current web visitor.
Screenshot of Requester IP Lookup from ipstack documentation with parameters.
Be aware that using the Requester IP does expose your API key to visiting browsers, so you may choose to capture the visitor's IP address on your server and use the Standard IP Lookup instead.
Continued from page 2.
Alternately, you can send the visitor's IP address via AJAX to your server for the Standard IP Lookup call.
Documentation for ipstack Parameters
ipstack's documentation is thorough like all of apilayer's API services. You can visit the Response Objects page to learn more about all of the response data returned by ipstack's geolocation API and its other modules.
Here is a screenshot of a subset of all the response objects ipstack provides; this image is just a sliver of the complete set:
Screenshot of Documentation of Response Objects, which describes fields returned by the API.
Using Callback Functions with the API
All of ipstack's API methods allow you to specify a JavaScript function to call when they return.
Screenshot of documentation from JSONP callbacks showing the API response when a callback function is defined.
When using JavaScript, in my experimentation, it was easier just to have the AJAX success method call my functions with the response data. But, what happens when you're calling the API from a different language?
Here's an example of using the callback method from PHP, to call a JavaScript function on the page to display the data.
The ipstack api query is made via PHP cURL. My specified callback is the JavaScript function name getRegionName(), which must be defined before the API call:
<script src="/jquery.js"></script>
<script>
function getRegionName() {
$('#results').html(JSON.stringify(arguments[0]['region_name']));
}
</script>
<br /><br /><br /><br /><br />
<div id="results">
<!--- data displayed here --->
</div>
<?php
// set IP address and API access key
$ip ='67.183.38.149';
$access_key = 'YOUR ACCESS KEY';
// Initialize CURL:
$ch = curl_init('https://api.ipstack.com/'.$ip.'?access_key='.$access_key.'&callback=getRegionName');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Store the data:
$json = curl_exec($ch);
echo '<script type="text/javascript">'.
$json.
'</script>';
;
curl_close($ch);
?>The result is that the region name is parsed from the result and displayed on the page.
For the IP address specified, it simply says: "Washington". I use arguments[0] to refer to the data sent in the callback.
The ipstack API Security Module
If you are subscribing to the Professional Plus plan or above, you can use the very intriguing security module of the ipstack API.
Screenshot of the documentation for Enabling the Security Module on ipstack's API.
The security module can tell you the following things about any IP address:
- Is it associated with a proxy e.g. CGI, web or VPN
- Is it a crawler such as a search engine bot, site monitor, screenshot creator, link checker, wearable computer, web scraper, vulnerability scanner, virus scanner, speed tester, feed fetcher, tool or marketing
- Is it associated with the anonymous Tor network
- Is it a low, medium or high level threat with characteristics being from Tor, being a fake crawler or web scraper or an known attack source vector e.g. http, mail or ssh
I hope you're getting a sense of the power of ipstack. It's not only ip2location but timezone lookup, ip2language, ip to currency and security!
Before we wrap up, there are just a couple other things to highlight.
Available Languages for Response Data
There are currently eight languages with which to receive response data on the ipstack API calls. Just simply specify the language parameter with the appropriate language code.
Screenshot from documentation of Specify Response Language for API calls.
Upgrading Your Account
ipstack is a subscription-based service and your chosen plan renews automatically each month. You can upgrade, downgrade or cancel anytime.
You might want to upgrade your account for any one or combination of these reasons:
- To use SSL encryption
- You need higher transaction limits (ipstack provides a page to calculate your usage statistics in the current period and historically over time.)
- You want additional functionality such as Currency Module, Time Zone Module, Connection Module, Bulk Endpoint or the Security Module
Screenshot of upgrade chart for functionality and pricing. Same pricing as new account levels described earlier.
If you're ready to upgrade from your free account level to try some of these additional APIs, go to the Dashboard and click Subscription Plan.
In Conclusion
I hope you've enjoyed this introduction to ipstack, a simple, affordable high performance geolocation API with extras that build on the success and popularity of FreeGeoIp.
It's essentially a one stop source for: Geolocation or IP to location, IP to language and IP to timezone. It's also a simpler more affordable alternative to Maxmind.
ipstack is a great resource for startups and small companies as well as great big enterprise level corporations.
I always enjoy catching up with the apilayer team and writing about their new projects. They are sharp technologists always offering utilitarian services with affordable prices, easy to integrate APIs and high performing scalable technologies.
Check out their suite of products and you'll likely find more that interest you.
Screenshot of portfolio of apilayer companies which offer related web-based data APIs.
I definitely want you to check out the coinlayer real time cryptocurrency API and currencylayer, since I just wrote about them recently.
apilayer and ipstack appreciate your questions, comments and feedback. You can also follow them on Twitter @apilayernet and the apilayer Facebook page.
About apilayer
ipstack is the most recent solution from apilayer, an established leader in product APIs. apilayer aims to help developers and businesses automate and outsource complex processes by serving them with dedicated and handy programming interfaces.
Two other products by apilayer include Invoicely, the invoicing platform, and the real time cryptocurrency exchange API, coinlayer, the latter of which I wrote about recently for ProgrammableWeb.