# Django GeoIP2 Extras
Useful extras based on the `django.contrib.gis.geoip2` module, using
the [MaxMind GeoIP2 Lite](http://dev.maxmind.com/geoip/geoip2/geolite2/) database.
The first feature in this package is a Django middleware class that can
be used to add city, country level information to inbound requests.
### Version support
The current version of the this app support **Python 3.8+** and **Django 3.2+**
## Requirements
1) This package wraps the existing Django functionality, and as a result
relies on the same underlying requirements:
In order to perform IP-based geolocation, the GeoIP2 object requires
the geoip2 Python library and the GeoIP Country and/or City datasets
in binary format (the CSV files will not work!). Grab the
GeoLite2-Country.mmdb.gz and GeoLite2-City.mmdb.gz files and unzip
them in a directory corresponding to the GEOIP_PATH setting.
NB: The MaxMind database is not included with this package. It is your
responsiblity to download this and include it as part of your project.
2) This package requires the usage of a Django cache configuration to
maintain adaquate performance.
## Installation
This package can be installed from PyPI as `django-geoip2-extras`:
```
$ pip install django-geoip2-extras
```
If you want to add the country-level information to incoming requests,
add the middleware to your project settings.
```python
# settings.py
MIDDLEWARE = (
...,
'geoip2_extras.middleware.GeoIP2Middleware',
)
```
The middleware will not be active unless you add a setting for the
default `GEOIP_PATH` - this is the default Django GeoIP2 behaviour:
```python
# settings.py
GEOIP_PATH = os.path.dirname(__file__)
```
You must also configure a cache to use via `GEOIP2_EXTRAS_CACHE_NAME`.
The value should match the name of the Django cache configuration you
wish to use for caching.
```python
# settings.py
# Django cache configuration setting
CACHES = {
"default": { ... },
"some-other-cache": { ... }, # <-- it would use this one.
...
}
# Set this to specific configuration name from CACHES
GEOIP2_EXTRAS_CACHE_NAME = "some-other-cache"
```
Tip: see `/demo/settings.py` for a full working example.
### Settings
The following settings can be overridden via your Django settings:
* `GEOIP2_EXTRAS_CACHE_NAME`
The Django cache configuration to use for cacheing.
* `GEOIP2_EXTRAS_CACHE_TIMEOUT`
Time to cache IP <> address data in seconds - default to 1hr (3600s)
* `GEOIP2_EXTRAS_ADD_RESPONSE_HEADERS`
Set to True to write out the GeoIP data to the response headers. Defaults to use
the `DEBUG` value. This value can be overridden on a per-request basis by adding
the `X-GeoIP2-Debug` request header, or adding `geoip2=1` to the request
querystring. This is useful for debugging in a production environment where you
may not be adding the response headers by default.
## Usage
Once the middleware is added, you will be able to access City and / or
Country level information on the request object via the `geo_data` dict:
```python
>>> request.geo_data
{
"city": ""
"continent-code": "NA"
"continent-name": "North America"
"country-code": "US"
"country-name": "United States"
"dma-code": ""
"is-in-european-union": False
"latitude": 37.751
"longitude": -97.822
"postal-code": ""
"region": ""
"time-zone": "America/Chicago"
"remote-addr": "142.250.180.3"
}
```
The same information will be added to the HttpResponse headers if
`GEOIP2_EXTRAS_ADD_RESPONSE_HEADERS` is True. Values are set using the
`X-GeoIP2-` prefix.
NB blank (`""`) values are **not** added to the response:
```shell
# use the google.co.uk IP
$ curl -I -H "x-forwarded-for: 142.250.180.3" localhost:8000
HTTP/1.1 200 OK
Date: Sun, 29 Aug 2021 15:47:22 GMT
Server: WSGIServer/0.2 CPython/3.9.4
Content-Type: text/html
X-GeoIP2-Continent-Code: NA
X-GeoIP2-Continent-Name: North America
X-GeoIP2-Country-Code: US
X-GeoIP2-Country-Name: United States
X-GeoIP2-Is-In-European-Union: False
X-GeoIP2-Latitude: 37.751
X-GeoIP2-Longitude: -97.822
X-GeoIP2-Time-Zone: America/Chicago
X-GeoIP2-Remote-Addr: 142.250.180.3
Content-Length: 10697
```
If the IP address cannot be found (e.g. '127.0.0.1'), then a default
'unknown' country is used, with a code of 'XX'.
```shell
$ curl -I -H "x-forwarded-for: 127.0.0.1" localhost:8000
HTTP/1.1 200 OK
Date: Sun, 29 Aug 2021 15:47:22 GMT
Server: WSGIServer/0.2 CPython/3.9.4
Content-Type: text/html
X-GeoIP2-Country-Code: XX
X-GeoIP2-Country-Name: unknown
X-GeoIP2-Remote-Addr: 127.0.0.1
Content-Length: 10697
```
## Tests
The project tests are run through `pytest`.
Raw data
{
"_id": null,
"home_page": "https://github.com/yunojuno/django-geoip2-extras",
"name": "django-geoip2-extras",
"maintainer": "YunoJuno",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "code@yunojuno.com",
"keywords": "",
"author": "YunoJuno",
"author_email": "code@yunojuno.com",
"download_url": "https://files.pythonhosted.org/packages/b5/c0/44b6c35edd3798e846d3c8d0687e20e23fe88be132ce23f704a9d28109e1/django_geoip2_extras-4.1.tar.gz",
"platform": null,
"description": "# Django GeoIP2 Extras\n\nUseful extras based on the `django.contrib.gis.geoip2` module, using\nthe [MaxMind GeoIP2 Lite](http://dev.maxmind.com/geoip/geoip2/geolite2/) database.\n\nThe first feature in this package is a Django middleware class that can\nbe used to add city, country level information to inbound requests.\n\n### Version support\n\nThe current version of the this app support **Python 3.8+** and **Django 3.2+**\n\n## Requirements\n\n1) This package wraps the existing Django functionality, and as a result\nrelies on the same underlying requirements:\n\n In order to perform IP-based geolocation, the GeoIP2 object requires\n the geoip2 Python library and the GeoIP Country and/or City datasets\n in binary format (the CSV files will not work!). Grab the\n GeoLite2-Country.mmdb.gz and GeoLite2-City.mmdb.gz files and unzip\n them in a directory corresponding to the GEOIP_PATH setting.\n\nNB: The MaxMind database is not included with this package. It is your\nresponsiblity to download this and include it as part of your project.\n\n2) This package requires the usage of a Django cache configuration to\nmaintain adaquate performance.\n\n\n## Installation\n\nThis package can be installed from PyPI as `django-geoip2-extras`:\n\n```\n$ pip install django-geoip2-extras\n```\n\nIf you want to add the country-level information to incoming requests,\nadd the middleware to your project settings.\n\n```python\n# settings.py\nMIDDLEWARE = (\n ...,\n 'geoip2_extras.middleware.GeoIP2Middleware',\n)\n```\n\nThe middleware will not be active unless you add a setting for the\ndefault `GEOIP_PATH` - this is the default Django GeoIP2 behaviour:\n\n```python\n# settings.py\nGEOIP_PATH = os.path.dirname(__file__)\n```\n\nYou must also configure a cache to use via `GEOIP2_EXTRAS_CACHE_NAME`.\nThe value should match the name of the Django cache configuration you\nwish to use for caching.\n\n```python\n# settings.py\n\n# Django cache configuration setting\nCACHES = {\n \"default\": { ... },\n \"some-other-cache\": { ... }, # <-- it would use this one.\n ...\n}\n\n# Set this to specific configuration name from CACHES\nGEOIP2_EXTRAS_CACHE_NAME = \"some-other-cache\"\n```\n\nTip: see `/demo/settings.py` for a full working example.\n\n### Settings\n\nThe following settings can be overridden via your Django settings:\n\n* `GEOIP2_EXTRAS_CACHE_NAME`\n\nThe Django cache configuration to use for cacheing.\n\n* `GEOIP2_EXTRAS_CACHE_TIMEOUT`\n\nTime to cache IP <> address data in seconds - default to 1hr (3600s)\n\n* `GEOIP2_EXTRAS_ADD_RESPONSE_HEADERS`\n\nSet to True to write out the GeoIP data to the response headers. Defaults to use\nthe `DEBUG` value. This value can be overridden on a per-request basis by adding\nthe `X-GeoIP2-Debug` request header, or adding `geoip2=1` to the request\nquerystring. This is useful for debugging in a production environment where you\nmay not be adding the response headers by default.\n\n## Usage\n\nOnce the middleware is added, you will be able to access City and / or\nCountry level information on the request object via the `geo_data` dict:\n\n```python\n>>> request.geo_data\n{\n \"city\": \"\"\n \"continent-code\": \"NA\"\n \"continent-name\": \"North America\"\n \"country-code\": \"US\"\n \"country-name\": \"United States\"\n \"dma-code\": \"\"\n \"is-in-european-union\": False\n \"latitude\": 37.751\n \"longitude\": -97.822\n \"postal-code\": \"\"\n \"region\": \"\"\n \"time-zone\": \"America/Chicago\"\n \"remote-addr\": \"142.250.180.3\"\n}\n```\n\nThe same information will be added to the HttpResponse headers if\n`GEOIP2_EXTRAS_ADD_RESPONSE_HEADERS` is True. Values are set using the\n`X-GeoIP2-` prefix.\n\nNB blank (`\"\"`) values are **not** added to the response:\n\n```shell\n# use the google.co.uk IP\n$ curl -I -H \"x-forwarded-for: 142.250.180.3\" localhost:8000\nHTTP/1.1 200 OK\nDate: Sun, 29 Aug 2021 15:47:22 GMT\nServer: WSGIServer/0.2 CPython/3.9.4\nContent-Type: text/html\nX-GeoIP2-Continent-Code: NA\nX-GeoIP2-Continent-Name: North America\nX-GeoIP2-Country-Code: US\nX-GeoIP2-Country-Name: United States\nX-GeoIP2-Is-In-European-Union: False\nX-GeoIP2-Latitude: 37.751\nX-GeoIP2-Longitude: -97.822\nX-GeoIP2-Time-Zone: America/Chicago\nX-GeoIP2-Remote-Addr: 142.250.180.3\nContent-Length: 10697\n```\n\nIf the IP address cannot be found (e.g. '127.0.0.1'), then a default\n'unknown' country is used, with a code of 'XX'.\n\n```shell\n$ curl -I -H \"x-forwarded-for: 127.0.0.1\" localhost:8000\nHTTP/1.1 200 OK\nDate: Sun, 29 Aug 2021 15:47:22 GMT\nServer: WSGIServer/0.2 CPython/3.9.4\nContent-Type: text/html\nX-GeoIP2-Country-Code: XX\nX-GeoIP2-Country-Name: unknown\nX-GeoIP2-Remote-Addr: 127.0.0.1\nContent-Length: 10697\n```\n\n## Tests\n\nThe project tests are run through `pytest`.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Additional functionality using the GeoIP2 database.",
"version": "4.1",
"project_urls": {
"Homepage": "https://github.com/yunojuno/django-geoip2-extras",
"Repository": "https://github.com/yunojuno/django-geoip2-extras"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a17ff8a5dcb23154d73cf8e50cc700f7be33e3d82d373e26661f7bfa996130dc",
"md5": "fe93c0a586a3f061b3c25b60523053a5",
"sha256": "ad62e3063fa3ab152f59ae6b20e3276cc968703117d785193a74f63ae4f7974c"
},
"downloads": -1,
"filename": "django_geoip2_extras-4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe93c0a586a3f061b3c25b60523053a5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 6929,
"upload_time": "2023-11-15T10:45:48",
"upload_time_iso_8601": "2023-11-15T10:45:48.620366Z",
"url": "https://files.pythonhosted.org/packages/a1/7f/f8a5dcb23154d73cf8e50cc700f7be33e3d82d373e26661f7bfa996130dc/django_geoip2_extras-4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b5c044b6c35edd3798e846d3c8d0687e20e23fe88be132ce23f704a9d28109e1",
"md5": "b3510489aaf8c1ce8b42fa479a061c34",
"sha256": "d7cf8c30369d66e09ca699eebb5343c04c7ed66ef54f103ce3f1fbb9c02e8ef6"
},
"downloads": -1,
"filename": "django_geoip2_extras-4.1.tar.gz",
"has_sig": false,
"md5_digest": "b3510489aaf8c1ce8b42fa479a061c34",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 5920,
"upload_time": "2023-11-15T10:45:50",
"upload_time_iso_8601": "2023-11-15T10:45:50.136217Z",
"url": "https://files.pythonhosted.org/packages/b5/c0/44b6c35edd3798e846d3c8d0687e20e23fe88be132ce23f704a9d28109e1/django_geoip2_extras-4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-15 10:45:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yunojuno",
"github_project": "django-geoip2-extras",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-geoip2-extras"
}
JSON
