<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Geolocation with GeoIP2 — Django 1.11.20 documentation</title>
<link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../../../" src="../../../_static/documentation_options.js"></script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<script type="text/javascript" src="../../../_static/language_data.js"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="GeoDjango Utilities" href="utils.html" />
<link rel="prev" title="Geolocation with GeoIP" href="geoip.html" />
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../../templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head><body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../../index.html">Django 1.11.20 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../../../index.html">Home</a> |
<a title="Table of contents" href="../../../contents.html">Table of contents</a> |
<a title="Global index" href="../../../genindex.html">Index</a> |
<a title="Module index" href="../../../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="geoip.html" title="Geolocation with GeoIP">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="utils.html" title="GeoDjango Utilities">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-contrib-gis-geoip2">
<div class="section" id="s-module-django.contrib.gis.geoip2">
<span id="s-geolocation-with-geoip2"></span><span id="module-django.contrib.gis.geoip2"></span><span id="geolocation-with-geoip2"></span><h1>Geolocation with GeoIP2<a class="headerlink" href="#module-django.contrib.gis.geoip2" title="Permalink to this headline">¶</a></h1>
<p>The <a class="reference internal" href="#django.contrib.gis.geoip2.GeoIP2" title="django.contrib.gis.geoip2.GeoIP2"><code class="xref py py-class docutils literal notranslate"><span class="pre">GeoIP2</span></code></a> object is a wrapper for the <a class="reference external" href="https://geoip2.readthedocs.io/">MaxMind geoip2 Python
library</a>. <a class="footnote-reference" href="#id6" id="id1">[1]</a></p>
<p>In order to perform IP-based geolocation, the <a class="reference internal" href="#django.contrib.gis.geoip2.GeoIP2" title="django.contrib.gis.geoip2.GeoIP2"><code class="xref py py-class docutils literal notranslate"><span class="pre">GeoIP2</span></code></a> object requires
the <a class="reference external" href="https://pypi.python.org/pypi/geoip2">geoip2 Python library</a> and the GeoIP <cite>Country</cite> and/or <cite>City</cite> <a class="reference external" href="http://dev.maxmind.com/geoip/geoip2/geolite2/">datasets
in binary format</a> (the CSV files will not work!). Grab the
<code class="docutils literal notranslate"><span class="pre">GeoLite2-Country.mmdb.gz</span></code> and <code class="docutils literal notranslate"><span class="pre">GeoLite2-City.mmdb.gz</span></code> files and unzip them
in a directory corresponding to the <a class="reference internal" href="#std:setting-GEOIP_PATH"><code class="xref std std-setting docutils literal notranslate"><span class="pre">GEOIP_PATH</span></code></a> setting.</p>
<p>Additionally, it is recommended to install the <a class="reference external" href="https://github.com/maxmind/libmaxminddb">libmaxminddb C library</a>, so
that <code class="docutils literal notranslate"><span class="pre">geoip2</span></code> can leverage the C library’s faster speed.</p>
<div class="section" id="s-example">
<span id="example"></span><h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
<p>Here is an example of its usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.contrib.gis.geoip2</span> <span class="k">import</span> <span class="n">GeoIP2</span>
<span class="gp">>>> </span><span class="n">g</span> <span class="o">=</span> <span class="n">GeoIP2</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">g</span><span class="o">.</span><span class="n">country</span><span class="p">(</span><span class="s1">'google.com'</span><span class="p">)</span>
<span class="go">{'country_code': 'US', 'country_name': 'United States'}</span>
<span class="gp">>>> </span><span class="n">g</span><span class="o">.</span><span class="n">city</span><span class="p">(</span><span class="s1">'72.14.207.99'</span><span class="p">)</span>
<span class="go">{'city': 'Mountain View',</span>
<span class="go">'country_code': 'US',</span>
<span class="go">'country_name': 'United States',</span>
<span class="go">'dma_code': 807,</span>
<span class="go">'latitude': 37.419200897216797,</span>
<span class="go">'longitude': -122.05740356445312,</span>
<span class="go">'postal_code': '94043',</span>
<span class="go">'region': 'CA'}</span>
<span class="gp">>>> </span><span class="n">g</span><span class="o">.</span><span class="n">lat_lon</span><span class="p">(</span><span class="s1">'salon.com'</span><span class="p">)</span>
<span class="go">(39.0437, -77.4875)</span>
<span class="gp">>>> </span><span class="n">g</span><span class="o">.</span><span class="n">lon_lat</span><span class="p">(</span><span class="s1">'uh.edu'</span><span class="p">)</span>
<span class="go">(-95.4342, 29.834)</span>
<span class="gp">>>> </span><span class="n">g</span><span class="o">.</span><span class="n">geos</span><span class="p">(</span><span class="s1">'24.124.1.80'</span><span class="p">)</span><span class="o">.</span><span class="n">wkt</span>
<span class="go">'POINT (-97 38)'</span>
</pre></div>
</div>
</div>
<div class="section" id="s-api-reference">
<span id="api-reference"></span><h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="django.contrib.gis.geoip2.GeoIP2">
<em class="property">class </em><code class="descname">GeoIP2</code>(<em>path=None</em>, <em>cache=0</em>, <em>country=None</em>, <em>city=None</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>The <code class="docutils literal notranslate"><span class="pre">GeoIP</span></code> object does not require any parameters to use the default
settings. However, at the very least the <a class="reference internal" href="#std:setting-GEOIP_PATH"><code class="xref std std-setting docutils literal notranslate"><span class="pre">GEOIP_PATH</span></code></a> setting
should be set with the path of the location of your GeoIP datasets. The
following initialization keywords may be used to customize any of the
defaults.</p>
<table class="docutils">
<colgroup>
<col width="25%" />
<col width="75%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Keyword Arguments</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">path</span></code></td>
<td>Base directory to where GeoIP data is located or the
full path to where the city or country data files
(<code class="docutils literal notranslate"><span class="pre">.mmdb</span></code>) are located. Assumes that both the city and
country datasets are located in this directory;
overrides the <a class="reference internal" href="#std:setting-GEOIP_PATH"><code class="xref std std-setting docutils literal notranslate"><span class="pre">GEOIP_PATH</span></code></a> setting.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">cache</span></code></td>
<td>The cache settings when opening up the GeoIP datasets. May
be an integer in (0, 1, 2, 4, 8) corresponding to the
<code class="docutils literal notranslate"><span class="pre">MODE_AUTO</span></code>, <code class="docutils literal notranslate"><span class="pre">MODE_MMAP_EXT</span></code>, <code class="docutils literal notranslate"><span class="pre">MODE_MMAP</span></code>, and
<code class="docutils literal notranslate"><span class="pre">GEOIP_INDEX_CACHE</span></code> <code class="docutils literal notranslate"><span class="pre">MODE_MEMORY</span></code> C API settings,
respectively. Defaults to 0 (<code class="docutils literal notranslate"><span class="pre">MODE_AUTO</span></code>).</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">country</span></code></td>
<td>The name of the GeoIP country data file. Defaults
to <code class="docutils literal notranslate"><span class="pre">GeoLite2-Country.mmdb</span></code>. Setting this keyword
overrides the <a class="reference internal" href="#std:setting-GEOIP_COUNTRY"><code class="xref std std-setting docutils literal notranslate"><span class="pre">GEOIP_COUNTRY</span></code></a> setting.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">city</span></code></td>
<td>The name of the GeoIP city data file. Defaults to
<code class="docutils literal notranslate"><span class="pre">GeoLite2-City.mmdb</span></code>. Setting this keyword overrides
the <a class="reference internal" href="#std:setting-GEOIP_CITY"><code class="xref std std-setting docutils literal notranslate"><span class="pre">GEOIP_CITY</span></code></a> setting.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-methods">
<span id="methods"></span><h2>Methods<a class="headerlink" href="#methods" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-instantiating">
<span id="instantiating"></span><h3>Instantiating<a class="headerlink" href="#instantiating" title="Permalink to this headline">¶</a></h3>
<dl class="classmethod">
<dt id="django.contrib.gis.geoip2.GeoIP2.open">
<em class="property">classmethod </em><code class="descclassname">GeoIP2.</code><code class="descname">open</code>(<em>path</em>, <em>cache</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.open" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This classmethod instantiates the GeoIP object from the given database path
and given cache setting.</p>
</div>
<div class="section" id="s-querying">
<span id="querying"></span><h3>Querying<a class="headerlink" href="#querying" title="Permalink to this headline">¶</a></h3>
<p>All the following querying routines may take either a string IP address
or a fully qualified domain name (FQDN). For example, both
<code class="docutils literal notranslate"><span class="pre">'205.186.163.125'</span></code> and <code class="docutils literal notranslate"><span class="pre">'djangoproject.com'</span></code> would be valid query
parameters.</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.city">
<code class="descclassname">GeoIP2.</code><code class="descname">city</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.city" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Returns a dictionary of city information for the given query. Some
of the values in the dictionary may be undefined (<code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.country">
<code class="descclassname">GeoIP2.</code><code class="descname">country</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.country" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Returns a dictionary with the country code and country for the given
query.</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.country_code">
<code class="descclassname">GeoIP2.</code><code class="descname">country_code</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.country_code" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Returns the country code corresponding to the query.</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.country_name">
<code class="descclassname">GeoIP2.</code><code class="descname">country_name</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.country_name" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Returns the country name corresponding to the query.</p>
</div>
<div class="section" id="s-coordinate-retrieval">
<span id="coordinate-retrieval"></span><h3>Coordinate Retrieval<a class="headerlink" href="#coordinate-retrieval" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.coords">
<code class="descclassname">GeoIP2.</code><code class="descname">coords</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.coords" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Returns a coordinate tuple of (longitude, latitude).</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.lon_lat">
<code class="descclassname">GeoIP2.</code><code class="descname">lon_lat</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.lon_lat" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Returns a coordinate tuple of (longitude, latitude).</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.lat_lon">
<code class="descclassname">GeoIP2.</code><code class="descname">lat_lon</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.lat_lon" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Returns a coordinate tuple of (latitude, longitude),</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.geos">
<code class="descclassname">GeoIP2.</code><code class="descname">geos</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.geos" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Returns a <a class="reference internal" href="geos.html#django.contrib.gis.geos.Point" title="django.contrib.gis.geos.Point"><code class="xref py py-class docutils literal notranslate"><span class="pre">Point</span></code></a> object corresponding to the
query.</p>
</div>
</div>
<div class="section" id="s-settings">
<span id="settings"></span><h2>Settings<a class="headerlink" href="#settings" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-geoip-path">
<span id="s-std:setting-GEOIP_PATH"></span><span id="geoip-path"></span><span id="std:setting-GEOIP_PATH"></span><h3><code class="docutils literal notranslate"><span class="pre">GEOIP_PATH</span></code><a class="headerlink" href="#geoip-path" title="Permalink to this headline">¶</a></h3>
<p>A string specifying the directory where the GeoIP data files are
located. This setting is <em>required</em> unless manually specified
with <code class="docutils literal notranslate"><span class="pre">path</span></code> keyword when initializing the <a class="reference internal" href="#django.contrib.gis.geoip2.GeoIP2" title="django.contrib.gis.geoip2.GeoIP2"><code class="xref py py-class docutils literal notranslate"><span class="pre">GeoIP2</span></code></a> object.</p>
</div>
<div class="section" id="s-geoip-country">
<span id="s-std:setting-GEOIP_COUNTRY"></span><span id="geoip-country"></span><span id="std:setting-GEOIP_COUNTRY"></span><h3><code class="docutils literal notranslate"><span class="pre">GEOIP_COUNTRY</span></code><a class="headerlink" href="#geoip-country" title="Permalink to this headline">¶</a></h3>
<p>The basename to use for the GeoIP country data file. Defaults to
<code class="docutils literal notranslate"><span class="pre">'GeoLite2-Country.mmdb'</span></code>.</p>
</div>
<div class="section" id="s-geoip-city">
<span id="s-std:setting-GEOIP_CITY"></span><span id="geoip-city"></span><span id="std:setting-GEOIP_CITY"></span><h3><code class="docutils literal notranslate"><span class="pre">GEOIP_CITY</span></code><a class="headerlink" href="#geoip-city" title="Permalink to this headline">¶</a></h3>
<p>The basename to use for the GeoIP city data file. Defaults to
<code class="docutils literal notranslate"><span class="pre">'GeoLite2-City.mmdb'</span></code>.</p>
</div>
</div>
<div class="section" id="s-exceptions">
<span id="exceptions"></span><h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h2>
<dl class="exception">
<dt id="django.contrib.gis.geoip2.GeoIP2Exception">
<em class="property">exception </em><code class="descname">GeoIP2Exception</code><a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2Exception" title="Permalink to this definition">¶</a></dt>
<dd><p>The exception raised when an error occurs in a call to the underlying
<code class="docutils literal notranslate"><span class="pre">geoip2</span></code> library.</p>
</dd></dl>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>GeoIP(R) is a registered trademark of MaxMind, Inc.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../../../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Geolocation with GeoIP2</a><ul>
<li><a class="reference internal" href="#example">Example</a></li>
<li><a class="reference internal" href="#api-reference">API Reference</a></li>
<li><a class="reference internal" href="#methods">Methods</a><ul>
<li><a class="reference internal" href="#instantiating">Instantiating</a></li>
<li><a class="reference internal" href="#querying">Querying</a></li>
<li><a class="reference internal" href="#coordinate-retrieval">Coordinate Retrieval</a></li>
</ul>
</li>
<li><a class="reference internal" href="#settings">Settings</a><ul>
<li><a class="reference internal" href="#geoip-path"><code class="docutils literal notranslate"><span class="pre">GEOIP_PATH</span></code></a></li>
<li><a class="reference internal" href="#geoip-country"><code class="docutils literal notranslate"><span class="pre">GEOIP_COUNTRY</span></code></a></li>
<li><a class="reference internal" href="#geoip-city"><code class="docutils literal notranslate"><span class="pre">GEOIP_CITY</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="geoip.html"
title="previous chapter">Geolocation with GeoIP</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="utils.html"
title="next chapter">GeoDjango Utilities</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../_sources/ref/contrib/gis/geoip2.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Feb 11, 2019</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="geoip.html" title="Geolocation with GeoIP">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="utils.html" title="GeoDjango Utilities">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
