The Python library

Some of our users have already successfully integrated our REST API into their applications thanks to the simplicity of our design and their skills as developers. We love to see how our users not only use our API for their internal products and services, but also for their commercial products. That’s why we’re going to push more and more the development of API clients for different languages, with the idea that more users can start using it by integrating with their services in the most simple way. This month we introduce the first client of our API for the Python language. This is Python Library we currently use for our in-house developments, as we are a Python house. We have hosted the source code on Github just like others that we have released under the Apache 2.0 license, so feel free to collaborate with us to improve it!

How to install

This Python library is supported for Python 2 and 3, for versions 2.7+ and 3.4+ respectively. It is recommended that Python 2 users use python 2.7.9+ to take advantage of the SSL Certificate Validation feature that is not included in earlier versions. You can install the Python Client Library with pip

$ sudo pip install apilityio-lib


You can read the Python documentation API Reference hosted in popular site The developer can start using the API right away, even without registering in the service! If you have any question you can visit the website at, review the REST API specification at and also read the User Guide at

Create the client object

The developer has to instance an object first passing as argument the API_KEY obtained after registering in

It’s possible to use the Python library without an API key, but it will be restricted to only 100 hits per day. The TRIAL plan offers 1000 hits per day for 30 days and the FREE plan has 250 hits per day forever. Please read our pricing plans at

To instantiate the client class with an API key:

client = apilityio.Client(api_key=api_key)

To instantiate the client class without an API key:

client = apilityio.Client()

Execute API calls

Now it’s time to perform the API calls. For example to look up an IP address in databases of blacklists:

response = client.CheckIP(ip)

If the IP address has been not found in any blacklist, it will return a 404 code in the status_code attribute of the Response object:

if response.status_code == 404:
    print("Congratulations! The IP address has not been found in any blacklist.")

If the IP address has been not in any blacklist, it will return a 200 code in the status_code attribute of the Response object, and the lists of blacklists in the blacklists attribute:

if response.status_code == 200:
    print("Ooops! The IP address has been found in one or more blacklist")
    blacklists = response.blacklists
    print('+- Blacklists: %s' % blacklists)

Now the developer can perform as many requests as needed with this client object. And he/she doesn’t need to close the connection because it is stateless.

Example: Get the Geolocation data of an IP address

This full example explains how to write a command-line tool with the Python library to obtain the Geolocation data of an IP address:

import sys
import getopt
import os
import traceback

import apilityio
import apilityio.errors

def main(argv=None):
    if argv is None:
        argv = sys.argv
            api_key = None
            ip = None
            options, remainder = getopt.getopt(
                argv[1:], 'h:a:i', ['help', 'api_key=', 'ip='])
            for opt, arg in options:
                if opt in ('-a', '--api_key'):
                    api_key = arg
                if opt in ('-i', '--ip'):
                        ip = unicode(arg, "utf-8")
                        ip = arg
                elif opt in ('-h', '--help'):
                    print("python --api_key= --ip=")
                    return 0
        except getopt.error as msg:
            raise Exception(msg)

            client = apilityio.Client(api_key=api_key)
            api_key, protocol, host = client.GetConnectionData()

            print('Host: %s' % host)
            print('Protocol: %s' % protocol)
            print('API Key: %s' % api_key)

            print('Geolocate IP: %s' % ip)

            response = client.GetGeoIP(ip)
            if response.status_code != 200:
                print("The API call returned this error HTTP %s: %s" %
                      (response.status_code, response.error))
                return 0

            geoip = response.geoip
            print('+- Accuracy radius: %s' % geoip.accuracy_radius)
            print('+- Address: %s' % geoip.address)
            print('+- City: %s' %
            print('+- City Geoname ID: %s' % geoip.city_geoname_id)
            print('+- City Names: %s' % geoip.city_names)
            print('+- Continent: %s' % geoip.continent)
            print('+- Continent Geo Name ID: %s' % geoip.continent_geoname_id)
            print('+- Continent Names: %s' % geoip.continent_names)
            print('+- Country: %s' %
            print('+- Country Geo Name ID: %s' % geoip.country_geoname_id)
            print('+- Country Names: %s' % geoip.country_names)
            print('+- Hostname: %s' % geoip.hostname)
            print('+- Latitude: %s' % geoip.latitude)
            print('+- Longitude: %s' % geoip.longitude)
            print('+- Postal code: %s' % geoip.postal)
            print('+- Region: %s' % geoip.region)
            print('+- Region Geoname ID: %s' % geoip.region_geoname_id)
            print('+- Region Names: %s' % geoip.region_names)
            print('+- Time Zone: %s' % geoip.time_zone)
            print('+--- AS number: %s' % geoip.asystem.asn)
            print('+--- AS name: %s' %
            print('+--- AS country: %s' %
            print('+--- AS networks: %s' % geoip.asystem.networks)

        except apilityio.errors.ApilityioValueError as ae:
            print("ERROR: ", ae)
            return 2

        return 0
    except Exception as e:
        print("ERROR: ", e)
        print("For help, use --help")
        return 2

if __name__ == "__main__":

If you would like to obtain code examples for any of the included client libraries, you can find it in the examples folder of the Github repository.

What’s next?

So now you can start coding or integrate our library with your application or service! And we would like to know about it! So please don’t hesitate and contact us to tell us about your product or service!

Do you have an issue using the Apilityio Client Libraries? Or perhaps some feedback for how we can improve them? Feel free to let us know on our issue tracker.