The simplest IP Geolocation lookup library for Flask.

.. image:: https://raw.githubusercontent.com/whois-api-llc/flask-simple-geoip/master/images/geoip.png

.. image:: https://img.shields.io/pypi/v/flask-simple-geoip.svg :alt: flask-simple-geoip Release :target: https://pypi.python.org/pypi/flask-simple-geoip

.. image:: https://img.shields.io/travis/whois-api-llc/flask-simple-geoip.svg :alt: flask-simple-geoip Build :target: https://travis-ci.org/whois-api-llc/flask-simple-geoip

• Author: Randall Degges
• Email: r@rdegges.com
• Twitter: https://twitter.com/rdegges
• Site: http://www.rdegges.com
• Status: production ready

To use this library, you'll need to create a free IP Geolocation account: https://ip-geolocation.whoisxmlapi.com/api

If you haven't done this yet, please do so now; you will obtain an API key that will be needed to use the library.

To install flask-simple-geoip using pypi <https://pypi.org/>_, simply run:

.. code-block:: console

$ pip install flask-simple-geoip

In the root of your project directory.

Once you have flask-simple-geoip installed, you can use it to easily find the physical location of a given IP address.

This library gives you access to all sorts of geographical location data that you can use in your application in any number of ways.

Here's a simple Flask app that makes use of the geolocation lookups:

.. code-block:: python

from flask import Flask, jsonify
from flask_simple_geoip import SimpleGeoIP


app = Flask(__name__)

# The API key is obtained from the IP_GEOLOCATION_API_KEY environment variable.
# Alternatively it can be set as follows:
# app.config.update(IP_GEOLOCATION_API_KEY='YOUR_API_KEY')

# Initialize the extension
simple_ip = SimpleGeoIP(app)


@app.route('/')
def test():
    # Retrieve IP Geolocation data for the given requester
    ip_data = simple_ip.get_geoip_data()

    return jsonify(data=ip_data)

Here's the sort of data you might get back when performing a IP Geolocation lookup request:

.. code-block:: json

{
  "ip": "8.8.8.8",
  "location": {
    "country": "US",
    "region": "California",
    "city": "Mountain View",
    "lat": 37.40599,
    "lng": -122.078514,
    "postalCode": "94043",
    "timezone": "-08:00"
  }
}

By default, this library handles retrying failed HTTP requests for you. For instance: if the IP Geolocation API service is currently down or having issues, your request will be retried up to three consecutive times before failing.

In the event a IP Geolocation lookup still can't return successfully, the data returned will be None. This library will never throw an exception. This decision was made strategically: not having IP Geolocation data should never be the cause of a failed request. =)

All library changes in descending order.

Version 0.2.4

Released October 27, 2020.

• Described in the readme how to supply the API key.

Version 0.2.3

Released August 26, 2020.

• Fixed pypy support.

Version 0.2.2

Released August 24, 2020.

• Added X_FORWARDED_FOR headers support.

Version 0.1.1

Released June 18, 2018.

• Fixing readme so it shows properly on PyPI :(

Version 0.1.0

Released June 18, 2018.

• First release!