Skip to main content

Simple tool for getting geolocation information on given IP address from various geolocation databases.

Project description


ip2geotools is a simple tool for getting geolocation information on given IP address from various geolocation databases. This package provides an API for several geolocation databases.


To install the ip2geotools module, type:

$ pip install ip2geotools

Basic usage

>>> from ip2geotools.databases.noncommercial import DbIpCity
>>> response = DbIpCity.get('', api_key='free')
>>> response.ip_address
'Brno (Brno střed)'
>>> response.region
'South Moravian'
>>> response.latitude
>>> response.longitude
>>> response.to_json()
'{"ip_address": "", "city": "Brno (Brno střed)", "region": "South Moravian", "country": "CZ", "latitude": 49.1926824, "longitude": 16.6182105}'
>>> response.to_xml()
'<?xml version="1.0" encoding="UTF-8" ?><ip_location><ip_address></ip_address><city>Brno (Brno střed)</city><region>South Moravian</region><country>CZ</country><latitude>49.1926824</latitude><longitude>16.6182105</longitude></ip_location>'
>>> response.to_csv(',')
',Brno (Brno střed),South Moravian,CZ,49.1926824,16.6182105'

Command-line usage

When installed, you can invoke ip2geotools from the command-line:

ip2geotools [-h] -d {dbipcity,hostip,freegeoip,ipstack,maxmindgeolite2city,ip2location,dbipweb,maxmindgeoip2city,ip2locationweb,neustarweb,geobytescitydetails,skyhookcontextacceleratorip,ipinfo,eurek,ipdata}
                   [--api_key API_KEY] [--db_path DB_PATH] [-u USERNAME]
                   [-p PASSWORD] [-f {json,xml,csv-space,csv-tab,inline}] [-v]


  • ip2geotools: is the script when installed in your environment, in development you could use python -m ip2geotools instead
  • IP_ADDRESS: IP address to be checked
  • -h, --help: show help message and exit
  • -d {dbipcity,hostip,...,ipdata}: geolocation database to be used (case insesitive)
  • --api_key API_KEY: API key for given geolocation database (if needed)
  • --db_path DB_PATH: path to geolocation database file (if needed)
  • -u USERNAME, --username USERNAME: username for accessing given geolocation database (if needed)
  • -p PASSWORD, --password PASSWORD: password for accessing given geolocation database (if needed)
  • -f {json,xml,csv-space,csv-tab,inline}, --format {json,xml,csv-space,csv-tab,inline}: output data format
  • -v, --version: show program’s version number and exit


$ ip2geotools -d dbipcity -f json
{"ip_address": "", "city": "Brno (Brno střed)", "region": "South Moravian", "country": "CZ", "latitude": 49.1926824, "longitude": 16.6182105}


This module contains models for the data returned by geolocation databases and these models are also used for comparison of given and provided data.


Model for storing location of given IP address.


  • ip_address: IP address
  • city: city where IP address is located
  • region: region where IP address is located
  • country: country where IP address is located (two letters country code)
  • latitude: latitude where IP address is located
  • longitude: longitude where IP address is located


  • to_json: returns model data in JSON format
  • to_xml: returns model data in XML format (root element: ip_location)
  • to_csv: returns model data in CSV format separated by given delimiter
  • __str__: internal string representation of model, every single information on new line


This module provides special exceptions used when accessing data from third-party geolocation databases.

  • ip2geotools.errors.LocationError: a generic location error
  • ip2geotools.errors.IpAddressNotFoundError: the IP address was not found
  • ip2geotools.errors.PermissionRequiredError: problem with authentication or authorization of the request; check your permission for accessing the service
  • ip2geotools.errors.InvalidRequestError: invalid request
  • ip2geotools.errors.InvalidResponseError: invalid response
  • ip2geotools.errors.ServiceError: response from geolocation database is invalid (not accessible, etc.)
  • ip2geotools.errors.LimitExceededError: limits of geolocation database have been reached


Following classes access many different noncommercial and commercial geolocation databases using defined interface.


  • IGeoIpDatabase: interface for unified access to the data provided by various geolocation databases



This code requires Python 3.3+ and several other packages listed in requirements.txt.


Please report all issues with this code using the GitHub issue tracker


ip2geotools is released under the MIT License. See the bundled LICENSE file for details.


ip2geotools was written by Tomas Caha <tomas-net at seznam dot cz> for master's thesis at FEEC BUT 2018/2019.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for ip2geotools, version 0.1.5
Filename, size File type Python version Upload date Hashes
Filename, size ip2geotools-0.1.5-py3-none-any.whl (16.4 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page