This feature saves staff time and increases accuracy when entering patron address information by automatically filling in the City, State and County information based on the ZIP code entered by the staff member.
Released: Evergreen 0.1, available in all versions.
Please be aware of the following when using this feature.
ZIP codes do not always match 1 to 1 with City, State and County. ZIP codes were designed for postal delivery and represent postal delivery zones that may cover more than one city, state or county.
There are no staff client permissions associated with this feature since there is no staff client interface.
This feature affects all users of the system; there is no way to have separate settings per Org Unit.
The default location and name of the data file is /openils/var/data/zips.txt on your Evergreen server. You can choose a different location if needed.
The file format of your zips.txt will look like this (delimited by the .):
ID|StateAbb|City|ZIP|IsDefault|StateID|County|AreaCode|AlertMesg
The only fields that are used are StateAbb, City, ZIP, IsDefault, County and AlertMesg.
Most fields can be left blank if the information is not available and that data will not be entered.
Data Field Descriptions
The Address Alerts feature — described in the Staff Client Sysadmin manual — can also be used to alert staff about certain addresses.
Here is an example of what the data file should look like.
Example zips.txt.
|MN|Moorhead|56561|1||Clay|| |MN|Moorhead|56562|1||Clay|| |MN|Moorhead|56563|1||Clay|| |MN|Sabin|56580|1||Clay|| |MN|Ulen|56585|1||Clay|| |MN|Lake Itasca|56460|1||Clearwater County|| |MN|Bagley|56621|1||Clearwater|| |MN|Clearbrook|56634|1||Clearwater|| |MN|Gonvick|56644|1||Clearwater||
The next step is to tell the system to use the zips.txt file that you created. This is done by editing /openils/conf/opensrf.xml. Look about halfway into the file and you may very well see a commented section in the file that looks similar to this:
<!-- zip code database file --> <!--<zips_file>/openils/var/data/zips.txt</zips_file>--> </app_settings> </open-ils.search>
Uncomment the area by . .. Change the file path if you placed your file in a different location. The file should look like this after you are done.
<!-- zip code database file --> <zips_file>/openils/var/data/zips.txt</zips_file> </app_settings> </open-ils.search>
Save and Restart. Save your changes to the opensrf.xml file, restart Evergreen and restart Apache.
The specific opensrf services you need to restart are "opensrf.setting" and "open-ils.search".
There are several methods you can use to populate your zips.txt with data.
If you only have a few communities that you serve, entering data manually may be the simplest approach.
Geonames.org provides free ZIP code to city, state and county information licensed under the Creative Commons Attribution 3.0 License, which means you need to put a link to them on your website. Their data includes primary city, state and county information only. It doesn’t include info about which other cities are included in a ZIP code. Visit http://www.geonames.org for more info.
The following code example shows you how to download and reformat the data into the zips.txt format. You have the option to filter the data to only include certain states also.
## How to get a generic Evergreen zips.txt for free wget http://download.geonames.org/export/zip/US.zip unzip US.zip cut -f2,3,5,6 US.txt \ | perl -ne 'chomp; @f=split(/\t/); print "|" . join("|", (@f[2,1,0], "1", "", $f[3], "")), "|\n";' \ > zips.txt ##Optionally filter the data to only include certain states egrep "^\|(ND|MN|WI|SD)\|" zips.txt > zips-mn.txt
There are many vendors that sell databases that include ZIP code to city, state and county information. A web search will easily find them. Many of the commercial vendors will include more information on which ZIP codes cover multiple cities, counties and states, which you could use to populate the alert field.
Another possibility is to use your current patron database to build your zips.txt. Pull out the current ZIP, city, state, county unique rows and use them to form your zips.txt.
Small Sites. For sites that serve a small geographic area (less than 30 ZIP codes), an sql query like the following will create a zips.txt for you. It outputs the number of matches as the first field and sorts by ZIP code and number of matches. You would need to go through the resulting file and deal with duplicates manually.
psql egdb26 -A -t -F $'|' \ -c "SELECT count(substring(post_code from 1 for 5)) as zipcount, state, \ city, substring(post_code from 1 for 5) as pc, \ '1', '', county, '', '' FROM actor.usr_address \ group by pc, city, state, county \ order by pc, zipcount DESC" > zips.txt
Larger Sites. For larger sites Ben Ostrowsky at ESI created a pair of scripts that handles deduplicating the results and adding in county information. Instructions for use are included in the files.
If you need to make changes to how this feature works, such as to add support for other postal code formats, here is a list of the files that you need to look at.