Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/whois-api-llc/flask-simple-geoip

The simplest GeoIP lookup library for Flask.
https://github.com/whois-api-llc/flask-simple-geoip

flask geolocation geolocation-api ip-geolocation python whoisxmlapi

Last synced: 2 months ago
JSON representation

The simplest GeoIP lookup library for Flask.

Awesome Lists containing this project

README 

        
flask-simple-geoip

==================



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



Meta

----

- Author: Randall Degges

- Email: [email protected]

- Twitter: https://twitter.com/rdegges

- Site: http://www.rdegges.com

- Status: production ready



Prerequisites

-------------



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.



Installation

------------



To install ``flask-simple-geoip`` using `pypi `_, simply run:



.. code-block:: console



    $ pip install flask-simple-geoip



In the root of your project directory.



Usage

-----



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. =)



Changelog

---------



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!