Skip to main content

A django application for describing addresses.

Project description

Django Address

Django models for storing and retrieving postal addresses.


Django Address is a set of models and methods for working with postal addresses.


  • Python (3.5, 3.6, 3.7, 3.8)
  • Django (2.2, 3.0)

We recommend and only officially support the latest patch release of each Python and Django series.


For more detailed instructions, view the Readme for the example site included with this package.

pip install django-address

Then, add address to your INSTALLED_APPS list in


You wil need to add your Google Maps API key to too:

GOOGLE_API_KEY = 'AIzaSyD--your-google-maps-key-SjQBE'

The Model

The rationale behind the model structure is centered on trying to make it easy to enter addresses that may be poorly defined. The model field included uses Google Maps API v3 (via the nicely done geocomplete jquery plugin) to determine a proper address where possible. However if this isn't possible the raw address is used and the user is responsible for breaking the address down into components.

It's currently assumed any address is represent-able using four components: country, state, locality and street address. In addition, country code, state code and postal code may be stored, if they exist.

There are four Django models used:


    country -> Country

    state -> State

    locality -> Locality

Address Field

To simplify storage and access of addresses, a subclass of ForeignKey named AddressField has been created. It provides an easy method for setting new addresses.


It can be created using the same optional arguments as a ForeignKey field. For example:

  from address.models import AddressField

  class MyModel(models.Model):
    address1 = AddressField()
    address2 = AddressField(related_name='+', blank=True, null=True)

Setting Values

Values can be set either by assigning an Address object:

  addr = Address(...)
  obj.address = addr

Or by supplying a dictionary of address components:

  obj.address = {'street_number': '1', 'route': 'Somewhere Ave', ...}

The structure of the address components is as follows:

    'raw': '1 Somewhere Ave, Northcote, VIC 3070, AU',
    'street_number': '1',
    'route': 'Somewhere Ave',
    'locality': 'Northcote',
    'postal_code': '3070',
    'state': 'Victoria',
    'state_code': 'VIC',
    'country': 'Australia',
    'country_code': 'AU'

All except the raw field can be omitted. In addition, a raw address may be set directly:

obj.address = 'Out the back of 1 Somewhere Ave, Northcote, Australia'

Getting Values

When accessed, the address field simply returns an Address object. This way all components may be accessed naturally through the object. For example::

  route = obj.address.route
  state_name =


Included is a form field for simplifying address entry. A Google maps auto-complete is performed in the browser and passed to the view. If the lookup fails the raw entered value is used.

TODO: Talk about this more.

Partial Example

The model:

from address.models import AddressField

class Person(models.Model):
  address = AddressField(on_delete=models.CASCADE)

The form:

from address.forms import AddressField

class PersonForm(forms.Form):
  address = AddressField()

The template:

{{ }} <!-- needed for JS/GoogleMaps lookup -->
  {{ form }}

Project Status Notes

This library was created by Luke Hodkinson originally focused on Australian addresses.

In 2015 Luke began working to abstract the project so it could handle a wider variety of international addresses.

This became the current dev branch. While good progress was made on this, the branch became stale and releases continued under the current model architecture on master.

The project is currently in triage, for releases 0.2.2 and 0.2.3, with a both a model re-architecture and updated requirements for 0.3.0. Read more about the project path forward in this issue.

If you have questions, bug reports or suggestions please create a New Issue for the project.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-address, version 0.2.2
Filename, size File type Python version Upload date Hashes
Filename, size django_address-0.2.2-py3-none-any.whl (28.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-address-0.2.2.tar.gz (16.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page