django-google-places-autocomplete 0.1.1

Django widget and field for Google Places Autocomplete (address autofill)

django-google-places-autocomplete

Django widget and form field for Google Places Autocomplete, so users can pick an address from Google’s suggestions instead of typing it manually.

Requirements

• Django >= 2.2
• Python >= 3.7
• A Google Places API (or Maps JavaScript API with Places library) key

Installation

pip install django-google-places-autocomplete

Or install in editable mode from source:

pip install -e path/to/django-google-places-autocomplete

Settings

1. Add the package to INSTALLED_APPS so static files are found:

INSTALLED_APPS = [
    # ...
    'django_google_places_autocomplete',
]

2. Set your Google Places API key:

GOOGLE_PLACES_API_KEY = 'your-api-key-here'

Restrict the key to your domain and to the Maps JavaScript API / Places API in Google Cloud Console.

Usage

As a widget (ModelForm)

from django import forms
from django_google_places_autocomplete import GooglePlacesAutocompleteWidget
from .models import MyModel

class MyForm(forms.ModelForm):
    class Meta:
        model = MyModel
        fields = '__all__'
        widgets = {
            'address': GooglePlacesAutocompleteWidget(),
            'business_address': GooglePlacesAutocompleteWidget(country_restriction='ca'),
        }

As a field

from django import forms
from django_google_places_autocomplete import GooglePlacesAddressField

class MyForm(forms.Form):
    address = GooglePlacesAddressField(required=False)
    # Restrict to Canada (default is 'ca')
    us_address = GooglePlacesAddressField(country_restriction='us')

In templates

Include the form’s media so the Google script and the widget script load:

{{ form.media }}
<form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <button type="submit">Submit</button>
</form>

Options

• country_restriction: Limit suggestions to one country (e.g. 'ca', 'us'). Default is 'ca'. Use None for no restriction.

Publishing to PyPI

When ready:

cd path/to/django-google-places-autocomplete
python -m build
twine upload dist/*

License

BSD.

Postal code and formatted address

By default the widget builds the address from Google address_components, so the postal code is included. The country line is omitted unless you pass include_country_in_address=True.

GooglePlacesAutocompleteWidget(
    include_country_in_address=False,  # default; no trailing "Canada"
    format_address_from_components=True,  # default; includes postal_code
)

To use Google’s formatted_address instead (postal code may be missing in some locales):

GooglePlacesAutocompleteWidget(format_address_from_components=False)

Requiring a suggestion (not free typing)

1. Use the widget with require_place_selection=True.
2. Add a companion hidden field per address field: {field_name}_place_id.
3. Render the hidden input in your template (or loop hidden_fields).
4. Call require_places_selection(form, 'address_field', ...) in clean().

from django import forms
from django_google_places_autocomplete import (
    GooglePlacesAutocompleteWidget,
    require_places_selection,
)

class MyForm(forms.ModelForm):
    address_place_id = forms.CharField(required=False, widget=forms.HiddenInput())

    class Meta:
        model = MyModel
        fields = '__all__'
        widgets = {
            'address': GooglePlacesAutocompleteWidget(require_place_selection=True),
        }

    def clean(self):
        cleaned_data = super().clean()
        require_places_selection(self, 'address')
        return cleaned_data

If the user types manually, the hidden place_id is cleared and validation fails when the text box is non-empty.

Note: This check is based on the submitted place_id. It improves UX discipline; for high-assurance verification you would validate place_id server-side with the Places API.