Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rednaks/django-ip-geolocation
IP Geolocation Hooks for django
https://github.com/rednaks/django-ip-geolocation
django hacktoberfest hooks middleware plugin python
Last synced: 3 days ago
JSON representation
IP Geolocation Hooks for django
- Host: GitHub
- URL: https://github.com/rednaks/django-ip-geolocation
- Owner: rednaks
- License: mit
- Created: 2019-12-27T17:45:41.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-10-20T11:49:54.000Z (about 3 years ago)
- Last Synced: 2024-09-26T08:13:54.415Z (about 2 months ago)
- Topics: django, hacktoberfest, hooks, middleware, plugin, python
- Language: Python
- Homepage: https://pypi.org/project/django-ip-geolocation/
- Size: 87.9 KB
- Stars: 37
- Watchers: 5
- Forks: 6
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://badge.fury.io/py/django-ip-geolocation) [](https://pepy.tech/project/django-ip-geolocation) [](https://travis-ci.org/rednaks/django-ip-geolocation)
# Django Ip Geolocation
Django request/response hooks to geolocate visitors by their ip address.
# Installing
```
python -m pip install django-ip-geolocation
```
# Usage
## Decorator
Use decorators to decorate views:
```python
from django_ip_geolocation.decorators import with_ip_geolocation
@with_ip_geolocation
def api_view(request):
location = request.geolocation
...
```
## Middleware
First you need to add the middleware into your `settings.py`.
```python
MIDDLEWARE = [
...
'django_ip_geolocation.middleware.IpGeolocationMiddleware',
...
]
```
Then the location is available to all views in request and response:
```python
def api_view(request):
location = request.geolocation
...
def other_view(request):
location = request.geolocation
...
```
## Cookie
Geolocation data stored in the Response cookie lacks the `raw_data` and is base64 encoded.
## User consent
Developers must implement a helper function to check if the user consented or not and configure it in the `settings.py`.
By default if the developer didn't provide a validation function, we consider it as implicit consent.
Here is an example of the helper function:
```python
def check_user_consent(request):
if request.user.is_consented: # this is only an example.
return True
return False
```
## Settings
You can configure settings for your hook in the `settings.py` as follow:
```python
IP_GEOLOCATION_SETTINGS = {
'BACKEND': 'django_ip_geolocation.backends.IPGeolocationAPI',
'BACKEND_API_KEY': '',
'BACKEND_EXTRA_PARAMS': {},
'BACKEND_USERNAME': '',
'RESPONSE_HEADER': 'X-IP-Geolocation',
'ENABLE_REQUEST_HOOK': True,
'ENABLE_RESPONSE_HOOK': True,
'ENABLE_COOKIE': False,
'FORCE_IP_ADDR': None,
'USER_CONSENT_VALIDATOR': None
}
```
Those are the default settings, that will be overwritten by those set in `settings.py`
| setting | description | default value (type) |
|------------------------|-------------------------------------------------|-----------------------------------------------------------------------|
| `BACKEND` | Backend class used to detect the geolocation | `django_ip_geolocation.backends.IPGeolocationAPI` (string class path) |
| `BACKEND_API_KEY` | Api key or token for the backend | Empty (string) |
| `BACKEND_EXTRA_PARAMS` | Extra parameters specific to the backend | `{}` (dict) |
| `BACKEND_USERNAME` | username for the backend | Empty (string) |
| `RESPONSE_HEADER` | Custom response header to store the geolocation | `X-IP-Geolocation` (string) |
| `ENABLE_REQUEST_HOOK` | Enable or disable hook on request | `True` (bool) |
| `ENABLE_RESPONSE_HOOK` | Enable or disable hook on request | `True` (bool) |
| `ENABLE_COOKIE` | Enable or disable geolocation data in cookie | `False` (bool) |
| `FORCE_IP_ADDR` | Force ip address, rather than using visitor ip | `None` (string) |
| `USER_CONSENT_VALIDATOR`| A function path to check if the current user gave his consent | `None` (string, function path) |
### Available Backends
* `django_ip_geolocation.backends.IPGeolocationAPI` : (Default) Using https://ipgeolocationapi.com/
* `django_ip_geolocation.backends.IPStack` : (Require `BACKEND_API_KEY`) Using https://ipstack.com/documentation
* `django_ip_geolocation.backends.IP2LocationCom` : (Require `BACKEND_API_KEY`, Accepts `BACKEND_EXTRA_PARAMS`) Using https://www.ip2location.com/web-service/ip2location
* `django_ip_geolocation.backends.IPDataCo` : (Require `BACKEND_API_KEY`) Using https://docs.ipdata.co/
## Implementing your own backend
If you want to add a new backend, you need to inherit from `django_ip_geolocation.backends.base`, then you need to implement `geolocate()` and `_parse()`.
### `geolocate()`
Makes API calls and stores the API response in `self._raw_data`.
### `_parse()`
Parse raw data stored in `self._raw_data` and assigns values to the class attribute, such as `self._continent`, `self._county`, `self._geo`.
`self._country` is a dict with `code` and `name` keys.
`self._geo` is a dict with `latitude` and `longitude` keys.