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 settings.py
:
INSTALLED_APPS = [
# ...
'address',
# ...
]
You can either store your Google API key in an environment variable as GOOGLE_API_KEY
or you can
specify the key in settings.py
. If you have an environment variable set it will override what you put in settings.py.
For more information, including enabling the Google Places API, refer to the example site.
GOOGLE_API_KEY = 'AIzaSyD--your-google-maps-key-SjQBE'
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
name
code
State
name
code
country -> Country
Locality
name
postal_code
state -> State
Address
raw
street_number
route
locality -> Locality
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.
By default, if you delete an Address that is related to another object,
Django's cascade behavior
is used. This means the related object will also be deleted. You may also choose
to set null=True
when defining an address field to have the address set
to Null instead of deleting the related object. For more information and an example,
see the readme for the django-address
example_site.
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)
Values can be set either by assigning an Address object:
addr = Address(...)
addr.save()
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'
When accessed, the address field simply returns an Address object. This way all components may be accessed naturally through the