# Documentation Django 3.1.9.dev

# Géolocalisation avec GeoIP2

L’objet `GeoIP2` est une adaptation de la bibliothèque Python geoip2 de MaxMind. [1]

Afin de pouvoir procéder à la géolocalisation basée sur l’adresse IP, l’objet `GeoIP2` a besoin de la bibliothèque Python geoip2 et d’un des jeux de données GeoIP `Country` ou `City` en format binaire (les fichiers CSV ne fonctionneront pas !). Récupérez les fichiers `GeoLite2-Country.mmdb.gz` et `GeoLite2-City.mmdb.gz` et décompressez-les dans un répertoire correspondant au réglage `GEOIP_PATH`.

En outre, il est recommandé d’installer la bibliothèque C libmaxminddb, afin que `geoip2` puisse tirer parti de la vitesse plus rapide de la bibliothèque C.

## Exemple

Voici un exemple de son utilisation :

    >>> from django.contrib.gis.geoip2 import GeoIP2
    >>> g = GeoIP2()
    >>> g.country('google.com')
    {'country_code': 'US', 'country_name': 'United States'}
    >>> g.city('72.14.207.99')
    {'city': 'Mountain View',
    'continent_code': 'NA',
    'continent_name': 'North America',
    'country_code': 'US',
    'country_name': 'United States',
    'dma_code': 807,
    'is_in_european_union': False,
    'latitude': 37.419200897216797,
    'longitude': -122.05740356445312,
    'postal_code': '94043',
    'region': 'CA',
    'time_zone': 'America/Los_Angeles'}
    >>> g.lat_lon('salon.com')
    (39.0437, -77.4875)
    >>> g.lon_lat('uh.edu')
    (-95.4342, 29.834)
    >>> g.geos('24.124.1.80').wkt
    'POINT (-97 38)'

## Référence de l’API

class `GeoIP2`(path=None, cache=0, country=None, city=None)

L’objet `GeoIP` n’a besoin d’aucun paramètre s’il utilise les réglages par défaut. Cependant, il faut au minimum définir le réglage `GEOIP_PATH` en indiquant le chemin vers l’emplacement des jeux de données GeoIP. Les paramètres nommés suivants peuvent être utilisés pour personnaliser les réglages par défaut lors de l’initialisation.

Paramètres nommés | Description
--- | ---
`path` | Répertoire de base où sont stockées les données GeoIP ou chemin complet de l’emplacement des fichiers de données (.mmdb) de villes et de pays. On suppose que les jeux de données des villes et des pays se trouvent dans ce même répertoire ; ce paramètre surcharge le réglage `GEOIP_PATH`.
`cache` | Les réglages de cache lors de l’ouverture des jeux de données GeoIP. Il peut s’agir d’un nombre entier dans (0, 1, 2, 4, 8) correspondant respectivement aux réglages `MODE_AUTO`, `MODE_MMAP_EXT`, `MODE_MMAP` et `GEOIP_INDEX_CACHE` des réglages `MODE_MEMORY` de l’API C. La valeur par défaut est 0 (`MODE_AUTO`).
`country` | Le nom du fichier de données des pays GeoIP. La valeur par défaut est `GeoLite2-Country.mmdb`. L’attribution d’une valeur à ce paramètre surcharge la valeur du réglage `GEOIP_COUNTRY`.
`city` | Le nom du fichier de données des villes GeoIP. La valeur par défaut est `GeoLite2-City.mmdb`. L’attribution d’une valeur à ce paramètre surcharge la valeur du réglage `GEOIP_CITY`.

Changed in Django 3.0:

La prise en charge des chemins `path` de type `pathlib.Path` a été ajoutée.

## Méthodes

### Instanciation

classmethod `GeoIP2.``open`(path, cache)

Cette méthode de classe crée une instance d’objet GeoIP à partir du chemin de base de données indiqué et du réglage de cache.

### Interrogation

Toutes les routines d’interrogation suivantes acceptent soit une chaîne d’adresse IP ou un nom de domaine entièrement qualifié (FQDN). Par exemple, `'205.186.163.125'` et `'djangoproject.com'` sont tous deux des paramètres d’interrogation valides.

`GeoIP2.``city`(query)

Renvoie un dictionnaire d’informations sur une ville correspondant à la requête donnée. Certaines valeurs du dictionnaire peuvent rester indéfinies (`None`).

`GeoIP2.``country`(query)

Renvoie un dictionnaire contenant le pays et son code correspondant à la requête donnée.

`GeoIP2.``country_code`(query)

Renvoie le code de pays correspondant à la requête donnée.

`GeoIP2.``country_name`(query)

Renvoie le nom de pays correspondant à la requête donnée.

### Obtention de coordonnées

`GeoIP2.``coords`(query)

Renvoie un tuple de coordonnées `(longitude, latitude)`.

`GeoIP2.``lon_lat`(query)

Renvoie un tuple de coordonnées `(longitude, latitude)`.

`GeoIP2.``lat_lon`(query)

Renvoie un tuple de coordonnées `(latitude, longitude)`.

`GeoIP2.``geos`(query)

Renvoie un objet `Point` correspondant à la requête.

## Réglages

### `GEOIP_PATH`

Une chaîne ou objet `pathlib.Path` indiquant le répertoire où se trouvent les fichiers de données GeoIP. Ce réglage est obligatoire sauf dans le cas où vous indiquez manuellement le paramètre `path` lors de l’initialisation des objets `GeoIP2`.

Changed in Django 3.0:

La prise en charge des chemins de type `pathlib.Path` a été ajoutée.

### `GEOIP_COUNTRY`

Le nom de base à utiliser pour le fichier de données des pays GeoIP. `'GeoLite2-Country.mmdb'` par défaut.

### `GEOIP_CITY`

Le nom de base à utiliser pour le fichier de données des villes GeoIP. `'GeoLite2-City.mmdb'` par défaut.

## Exceptions

exception `GeoIP2Exception`

  L’exception levée quand une erreur survient lors d’un appel à la bibliothèque sous-jacente `geoip2`.

Notes de bas de page

[1] | GeoIP(R) est une marque déposée de MaxMind, Inc.