Description

This modules contains classes that operate on the US Census Bureau's Zip Code Tabulation Areas. Included with this module is the zcta5.txt file compiled from the 2000 US Census. This file and others can be obtained from the US Census Bureau.

The ZipDB class is a component that allows searching by proximity over the zip codes. Distance is computed using the mathematical formula for distance between points on an ideal sphere. The radius of the idea sphere used to approximate the Earth is 6,372Km.

Version

This document covers the first release version 1.0.0, August 15, 2002.

Author and Copyright

Written by Nathan Denny. This code (zcta5.py) is in the public domain. No warranty on correctness. The zcta5.txt file is provided by the US Census Bureau. See their notes for any restrictions on use or copyright of that text.

Example

#-- Create a zip code database from the supplied tabulation file.
zdb = ZipDB("zcta5.txt")

#-- A point of reference for example.
#-- This retrieves the zipcode data for Carbondale, IL 62901
carbondale_IL = zdb['62901']

print "Ten nearest USPS zip codes to Carbondale, IL"
results = zdb.findNearestTo(carbondale_IL)
for result in results[:10]:
	d, zip = result
	print "%03.2f %s"%(d, zip.zipcode)

print

print "All USPS zip codes within 25Km of Carbondale, IL"
results = zdb.findWithinRadius(carbondale_IL, 25)
for result in results:
	d, zip = result
	print "%03.2f %s"%(d, zip.zipcode)

zcta5.GeoLocation

latitude

The latitude in degrees.

longitude

The longitude in degrees.

distance(z)

z must be another instance of zcta5.GeoLocation (or one of its subclasses). This returns the distance, in Km, between self and z using the ideal sphere radius of the Earth of 6,372Km.

zcta5.ZipArea(GeoLocation)

population

The population of the zipcode area at the time of the census.

state

The two letter state abbreviation.

zipcode

The 5 digit US Postal Service sipcode.

zcta5.ZipDB

ZipDB(filename='zcta5.txt')

Creates a new instance of the ZipDB class by parsing the given file.

findWithinRadius(query, radius)

Returns a list of ZipArea instances that were found to be within radius Km of the query. query must be a GeoLocation, or a string. In the latter case, the GeoLocation (actually a ZipArea) instance is retrieved from self by matching the string to the zipcode.

findNearestTo(query, resultSize=None)

Returns a list of ZipArea instances in order of distance from the query. query must be either a GeoLocation or a string. (See above.) If resultSize is None (the default) then all instances in the database are contained in the resulting list. If only a subset is needed, set resultSize to some integer value to limit the resulting list.

[zip]

The ZipDB maintains a dictionary-like interface to retrieve references to ZipArea instances by zipcode.