Django Country

A Django middleware that adds current country information to request object. The current country can be set manually or can be detected automatically based on IP address or locale information in the HTTP header.

Getting Started

Install django-country package:

pip install django-country

Add the middleware in django settings:

# settings.py

MIDDLEWARE_CLASSES = (
    ...
    'django_country.middleware.CountryMiddleware',
)

If you use SessionMiddleware, it needs to appear before CountryMiddleware in the list.

Now your can access detected country as a attribute of request object:

request.COUNTRY_CODE # Country code is in ISO 3166-1 alpha-2 format. e.g. "US"

Add an endpoint to set country manually:

# urls.py

urlpatterns = patterns('',
  ...
  url(r'/', include((django_country.urls')),
)

Now you can send POST request to <host>/country/ with country data to set country manually.

Access country in Django templates:

# settings.py
TEMPLATE_CONTEXT_PROCESSORS = (
  ...
  'django_country.context_processors.country',
)

# index.html
<div country-code={{country_code}}>{{country_name}}</div>

How is country detected?

The middleware detects country from the following sources in the given order:

1. session, if country code is set in session.
2. cookie, if country code is set in cookie.
3. IP address, if settings.USE_GEOIP is True (default: False).
4. HTTP_ACCEPT_LANGUAGE HTTP header if settings.USE_LOCALE is True (default: False).

Settings

COUNTRY_CODE

Default: 'US'

Country code to use if no country is detected.

COUNTRIES

Default: A tuple of all countries. This list is retrieved from django-countries library.

This list is a tuble of two-tuples in the format (country code, country name) - for example ('JP', 'Japan'). This specifies which countries are available for country selection.

USE_GEOIP

Default: False

A boolean that specifieds if IP address should be used to detect country. If this flag is set to True, GEOIP_DAT_PATH settings has to be specified.

GEOIP_DAT_PATH

A path to geoip database in .dat format. You can download this from MaxMind.

USE_LOCALE

Default: False

A boolean that specifieds if locale information in ACCEPT-LANGUAGE HTTP header should be used to detect country.

COUNTRY_SESSION_KEY

Default: 'django_country'

Session key under which the active country for the current session is stored.

COUNTRY_COOKIE_NAME

Default: 'country'

Cookie name under which the active country for the current session is stored.

COUNTRY_COOKIE_AGE

Default: None (expires at browser close)

The age of the country cookie, in seconds.

COUNTRY_COOKIE_PATH

Default: /

The path set on the country cookie. This should either match the URL path of your Django installation or be a parent of that path.

This is useful if you have multiple Django instances running under the same hostname. They can use different cookie paths and each instance will only see its own country cookie.

Be cautious when updating this setting on a production site. If you update this setting to use a deeper path than it previously used, existing user cookies that have the old path will not be updated. This will result in site users being unable to switch the country as long as these cookies persist. The only safe and reliable option to perform the switch is to change the country cookie name permanently.