Metadata-Version: 2.4
Name: django-google-places-autocomplete
Version: 0.1.1
Summary: Django widget and field for Google Places Autocomplete (address autofill)
Home-page: https://github.com/FlavienLouis/django-google-places-autocomplete
Author: FlavienLouis
Author-email: flouis@reptile.tech
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: Django>=2.2
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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](https://developers.google.com/maps/documentation/places/web-service) (or Maps JavaScript API with Places library) key

## Installation

```bash
pip install django-google-places-autocomplete
```

Or install in editable mode from source:

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

### Settings

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

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

2. Set your Google Places API key:

```python
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)

```python
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

```python
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:

```html
{{ 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:

```bash
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`.

```python
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):

```python
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()`.

```python
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.
