docs/modules/admin/pages/patron_address_by_zip_code.adoc

   1 = Patron Address City/State/County Pre-Populate by ZIP Code =
   2 :toc:
   3
   4 indexterm:[zips.txt, Populate Address by ZIP Code, ZIP code]
   5
   6 This feature saves staff time and increases accuracy when entering patron address information by
   7 automatically filling in the City, State and County information based on the
   8 ZIP code entered by the staff member.
   9
  10 *Released:* Evergreen 0.1, available in all versions.
  11
  12 Please be aware of the following when using this feature.
  13
  14 * 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.
  15 ** It is currently only possible to have one match per ZIP code, but you can add an alert to those entries to prompt staff to double check the entered data.
  16 * Only the first 5 digits of the ZIP are used.  ZIP+4 is not currently supported.
  17 * The zips.txt data is loaded once at service startup and stored in memory, so changes to the zips.txt data file require that Evergreen be restarted.  Specifically, you need to restart the "open-ils.search" OpenSRF service.
  18
  19
  20 == Scoping and Permissions ==
  21
  22 There are no staff client permissions associated with this feature since there is no staff client interface.
  23
  24 This feature affects all users of the system; there is no way to have separate settings per Org Unit.
  25
  26 == Setup Steps ==
  27
  28 === Step 1 - Setup Data File ===
  29
  30 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.
  31
  32 The file format of your zips.txt will look like this (delimited by the .):
  33
  34 ID|*StateAbb*|*City*|*ZIP*|*IsDefault*|StateID|*County*|AreaCode|*AlertMesg*
  35
  36 The only fields that are used are *StateAbb*, *City*, *ZIP*, *IsDefault*, *County* and *AlertMesg*.
  37
  38 Most fields can be left blank if the information is not available and that data will not be entered.
  39
  40 .Data Field Descriptions
  41 . ID - ID field to uniquely identify this row.  Not required, can be left blank.
  42 . *StateAbb* - State abbreviation like "MN" or "ND".
  43 . *City* - Name of city.
  44 . *ZIP* - ZIP code, only first 5 digits used.
  45 . *IsDefault* - Must be set to 1 for the row to be used.  Easy way to disable/enable a row.
  46 . StateID - Unknown and unused.
  47 . *County* - County name.
  48 . AreaCode - Phone number area code, unused.
  49 . *AlertMesg* - Message to display to staff to alert them of any special circumstances.
  50
  51 TIP: The Address Alerts feature -- described in the Staff Client Sysadmin manual -- can also be used to alert staff about certain addresses.
  52
  53 Here is an example of what the data file should look like.
  54
  55 .Example zips.txt
  56 ----
  57 |MN|Moorhead|56561|1||Clay||
  58 |MN|Moorhead|56562|1||Clay||
  59 |MN|Moorhead|56563|1||Clay||
  60 |MN|Sabin|56580|1||Clay||
  61 |MN|Ulen|56585|1||Clay||
  62 |MN|Lake Itasca|56460|1||Clearwater County||
  63 |MN|Bagley|56621|1||Clearwater||
  64 |MN|Clearbrook|56634|1||Clearwater||
  65 |MN|Gonvick|56644|1||Clearwater||
  66 ----
  67
  68 === Step 2 - Enable Feature ===
  69
  70 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:
  71
  72 ----
  73           <!-- zip code database file -->
  74           <!--<zips_file>/openils/var/data/zips.txt</zips_file>-->
  75      </app_settings>
  76 </open-ils.search>
  77 ----
  78
  79 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.
  80
  81 ----
  82           <!-- zip code database file -->
  83           <zips_file>/openils/var/data/zips.txt</zips_file>
  84      </app_settings>
  85 </open-ils.search>
  86 ----
  87
  88 .Save and Restart
  89 Save your changes to the opensrf.xml file, restart Evergreen and restart Apache.
  90
  91 NOTE: The specific opensrf services you need to restart are "opensrf.setting" and "open-ils.search".
  92
  93 === Step 3 - Test ===
  94
  95 Open up the staff client and try to register a new patron.  When you get to the address section, enter a ZIP code that you know is in your zips.txt file.  The data from the file that matches your ZIP will auto fill the city, state and county fields.
  96
  97 == ZIP Code Data ==
  98
  99 There are several methods you can use to populate your zips.txt with data.
 100
 101 === Manual Entry ===
 102
 103 If you only have a few communities that you serve, entering data manually may be the simplest approach.
 104
 105 === Geonames.org Data ===
 106
 107 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.
 108
 109 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.
 110
 111 [source,bash]
 112 ----
 113 ## How to get a generic Evergreen zips.txt for free
 114 wget http://download.geonames.org/export/zip/US.zip
 115 unzip US.zip
 116 cut -f2,3,5,6 US.txt \
 117 | perl -ne 'chomp; @f=split(/\t/); print "|" . join("|", (@f[2,1,0], "1", "", $f[3], "")), "|\n";' \
 118 > zips.txt
 119
 120 ##Optionally filter the data to only include certain states
 121 egrep "^\|(ND|MN|WI|SD)\|" zips.txt  > zips-mn.txt
 122 ----
 123
 124 === Commercial Data ===
 125
 126 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.
 127
 128 === Existing Patron Database ===
 129
 130 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.
 131
 132 .Small Sites
 133
 134 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.
 135
 136 [source,bash]
 137 ----
 138 psql egdb26 -A -t -F $'|' \
 139  -c "SELECT count(substring(post_code from 1 for 5)) as zipcount, state, \
 140  city, substring(post_code from 1 for 5) as pc, \
 141  '1', '', county, '', '' FROM actor.usr_address \
 142  group by pc, city, state, county \
 143  order by pc, zipcount DESC" > zips.txt
 144 ----
 145
 146 .Larger Sites
 147 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.
 148
 149 * http://git.esilibrary.com/?p=migration-tools.git;a=blob;f=elect_ZIPs
 150 * http://git.esilibrary.com/?p=migration-tools.git;a=blob;f=enrich_ZIPs
 151
 152
 153 == Development ==
 154
 155 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.
 156
 157 . *Zips.pm* - contains code for loading the zips.txt file into memory and replying to search queries.  Open-ILS / src / perlmods / lib / OpenILS / Application / Search / Zips.pm
 158 . *register.js* - This is where patron registration logic is located.  The code that queries the ZIP search service and fills the address is located here.  Open-ILS / web / js / ui / default / actor / user / register.js