the blog

Django geography hacks

If you need to handle some basic geography in your Django application, but can't or don't want to use GeoDjango, here are some quick hacks to accomplish simple geocoding and distance calculations.

When I set out to add these to my app, I looked around for something already written, and of course found GeoDjango, which incorporates tons of GIS functions. But it's its own Django branch, with a hefty list of prerequisite software. It looks great for serious GIS projects, but it was more than I wanted to take on for this. Fortunately, I found a lighter alternative, geopy, which was just what I was after.

First, I had to geocode my locations, finding their latitude and longitude using addresses or postal codes. Google and Yahoo! have mapping APIs with excellent geocoding, but you're only allowed to use their geocoding data to display their maps. Fortunately, geopy supports a number of other geocoding services with better terms. I'll use geocoder.us, which is free for non-commercial use and very reasonable otherwise.

Once you have coordinates, geopy gives you a number of accurate, easy methods to calculate distance. So, on to integrating it into your Django model. Here's an example:

from django.db import models
from django.contrib.localflavor.us.us_states import STATE_CHOICES

import geopy.distance
from geopy import geocoders

class LocationManager(models.Manager):
  def __init__(self):
    super(LocationManager, self).__init__()

  def near(self, latitude=None, longitude=None, distance=None):
    if not (latitude and longitude and distance):
      return []

    queryset = super(LocationManager, self).get_query_set()

    # prune down the set of all locations to something we can quickly check precisely
    rough_distance = geopy.distance.arc_degrees(arcminutes=geopy.distance.nm(miles=distance)) * 2
    queryset = queryset.filter(
          latitude__range=(latitude - rough_distance, latitude + rough_distance), 
          longitude__range=(longitude - rough_distance, longitude + rough_distance)
          )

    locations = []
    for location in queryset:
      if location.latitude and location.longitude:
        exact_distance = geopy.distance.distance(
                  (latitude, longitude),
                  (location.latitude, location.longitude)
                  )
        exact_distance.calculate()
        if exact_distance.miles <= distance:
          locations.append(location)

    queryset = queryset.filter(id__in=[l.id for l in locations])
    return queryset

class Location(models.Model):
  objects = LocationManager()
  name = models.CharField(max_length=100)
  address = models.TextField()
  city = models.CharField(max_length=100)
  state = models.USStateField(choices=STATE_CHOICES)
  zipcode = models.CharField(max_length=10)
  latitude = models.FloatField(blank=True, null=True)
  longitude = models.FloatField(blank=True, null=True)

  def save(self):
    if not (self.latitude and self.longitude):
      geocoder = geocoders.GeocoderDotUS()

      geocoding_results = None

      if self.address:
        # try the full address
        query = '%(address)s, %(city)s, %(state)s %(zipcode)s' % self.__dict__
        geocoding_results = list(geocoder.geocode(query, exactly_one=False))

      # then just city/state/zip
      if not geocoding_results and self.city:
        query = '%(city)s, %(state)s %(zipcode)s' % self.__dict__
        geocoding_results = list(geocoder.geocode(query, exactly_one=False))

      # and finally just zip
      if not geocoding_results and self.zipcode:
        query = '%(zipcode)s' % self.__dict__
        geocoding_results = list(geocoder.geocode(query, exactly_one=False))

      if geocoding_results:
        place, (latitude, longitude) = geocoding_results[0]
        self.latitude = latitude
        self.longitude = longitude
    super(Location, self).save()

Let's work backwards. The fields of the Location class are straightforward (if you're in the U.S., of course; otherwise replace state and zipcode). The geocoding is also pretty obvious: use the most precise address information available to obtain the Location's coordinates. It's worth experimenting with the different geocoders geopy supports to see which works best for you.

On to distance calculation. The LocationManager class has a utility method, near, which given a point's latitude and longitude and a maximum distance, returns all the locations within that distance of the point. I'm using the default method, the Vincenty distance. You could use one of geopy's other methods, like great circle distance. Other things you might want to change:

• On the assumption that there will be a lot of Locations in the database, I'm doing some crude winnowing of Locations before performing the precise calculations; in my testing so far this provides acceptable performance with over a million locations. If that's not necessary for your dataset, it can be easily removed.
• You can easily work with kilometers instead of miles, but again, this app is only going to be used in the U.S.

Now that we have geocoded locations and a way to determine which are within a given distance of a certain point, here's how you might use them. Say you have another Model called Activity, which has a ForeignKey link to Location. The user is looking for activities near his ZIP code, which you also have modeled with latitude and longitude. You could do something like this in your search view:

if zipcode:
  zc = ZipCode.objects.get(zipcode=zipcode)
  if distance:
    distance=int(distance)
    nearby_locations = Location.objects.near(zc.latitude, zc.longitude, distance)
    activities = Activity.objects.filter(location__in=nearby_locations)

It doesn't get much simpler than that, and it's perfectly adequate for rough distance estimates used to narrow down datasets by location.

One last thing. You can get free databases of ZIP codes with latitude and longitude at:

• http://zips.sourceforge.net/
• http://www.populardata.com/downloads.html