============
dj-geocoding
============
.. image:: https://travis-ci.org/bennylope/dj-geocoding.svg?branch=master
:target: https://travis-ci.org/bennylope/dj-geocoding
Django features for simple geocoding. Current support for the Geocodio geocoding service
Read the full docs on `Read the Docs <http://dj-geocoding.readthedocs.org/en/latest/>`_.
Installing
==========
Install dj-geocoding::
pip install dj-geocoding
Then use it in a project::
import dj-geocoding
Add your geocoding service API credentials to your `settings.py` file::
GEOCODIO_API_KEY="SOMEAPIKEY"
Model
=====
Use the optional model mixin to your model if you aren't using PostGIS::
from dj_geocoding.models import GeoBase
class MyModel(GeoBase, models.Model):
pass
This adds the followng fields::
latitude = models.DecimalField(decimal_places=15, max_digits=18, null=True,
blank=True)
longitude = models.DecimalField(decimal_places=15, max_digits=18, null=True,
blank=True)
Adds a geocode method::
def geocode(self, \*args, \**kwargs):
return geocode()
You should extend this in your model, providing the field(s) from which the
address will be pulled::
def geocode(self):
return super(MyModel, self).geocode('address')
You can choose the separator for providing a single address, too::
def geocode(self):
return super(MyModel, self).geocode('street_address', 'city', 'state',
seperator=", ")
And additional property attributes for the `point` attribute.
Bulk geocoding
==============
The `bulk_geocode` function takes a queryset and geocodes its member objects.
.. note::
The model *must* implement a point-type field that behaves like a
Point field.
Example::
geocoded_qs = bulk_geocode(MyModel.objects.all())
Specifying the field name::
geocoded_qs = bulk_geocode(MyModel.objects.all(), field='point')
Manager
-------
The manager class implements a subclassed `QuerySet` with a `geocode` method::
MyModel.objects.all().geocode()
This returns a queryset of the objects updated (or not) that fit within the
limits of the geocoding service. It is a convenient interface tot he
`bulk_geocode` function.
Admin site
==========
The `GeocodedFilter` filter can be used to filter locations in the admin based
on whether they have been geolocated or not.
The `GeolocateMixin` class can be added to your `ModelAdmin` definition to add
the `geocode_address` admin action. This adds the "geocode address" action to
the admin actions dropdown menu and then will allow you to geocode an entire
queryset from the admin.
History
-------
0.2.1 (2014-12-02)
++++++++++++++++++
* Removes reliance on queryset `geocode` method in admin action
* Adds docs
0.2.0 (2014-09-08)
++++++++++++++++++
* Revise `has_geolocation` method, remove property status
* Added list filter class `GeocodedFilter`
0.1.1 (2014-08-26)
++++++++++++++++++
* Bug fix for handling single None value in _set_point
0.1.0 (2014-08-26)
++++++++++++++++++
* First release on PyPI.
