postgis/extras/tiger_geocoder/tiger_2010

$Id$

Installing The Tiger Geocoder

This is a customized version of Steve Frost's tiger geocoder revisions
(http://www.snowman.net/git/tiger_geocoder/).

This version includes a loader that is portable between Linux and
Windows but loads a full state of data.  The loader helper tables and
functions are prefixed with loader and stored in the tiger schema.  If
you only want to load a county, revise the wget call that is generated
for the state to just download the statewide and specific counties or
just download them by hand.  The loader will only process files that
exist.

If you are on windows, you will need 7zip and wget.  7zip you can get
from http://www.7-zip.org/ and wget you can get from
http://gnuwin32.sourceforge.net/packages/wget.htm

Tiger Geocoder is now part of the PostGIS documentation
for further details about function use, refer to:
http://www.postgis.org/documentation/manual-svn/Extras.html#Tiger_Geocoder

Steps to install and load:

1.  Create a PostGIS enabled db if you don't have one already

2.	From command line, cd into the tiger_geocoder_2010 folder

3.  Edit the tiger_loader.sql to the paths of your executables server etc.

4.	Edit the create_geocode.bat or create_geocode.sh and run

(NOTE: if you installed soundex in its own schema, you will need to
add it to the set path of the create_geocode.sql file and also have it
in the search_path of your database)

5.	Now add tiger schema to your database search path by doing
something like: 
ALTER DATABASE geocoder SET search_path=public, tiger;

6. Create a folder called gisdata on root of server or your local pc
if you have a fast network connection to the server. This folder is
where the tiger files will be downloaded to.

7. Create a folder called temp in the gisdata folder.  This will be
the folder where we extract the downloaded tiger data.

8. Run the following commands at psql or pgAdmin III query window to
generate the script, replacing 'DC', 'RI' with list of states you want
and save contents to a .bat or sh file in YOUR CURRENT DIRECTORY. This
will generate CODE for each state and append it to the script.

(IF YOU ARE AT A PSQL PROMPT, FIRST RUN "\a", "\t", AND "\o
script.xxx".  THIS WILL MAKE YOUR OUTPUT UNALIGNED AND REDIRECT IT TO
script.xxx.  WITHOUT "\a" and "\t", THE SCRIPT WILL HAVE EXTRA
WHITESPACE AND POSSIBLY NON-SCRIPT CHARACTERS THAT CAUSE IT TO BREAK.)

-- UNIX /LINUX USERS --
--To generate a bash script suitable for Unix command lines
SELECT loader_generate_script(ARRAY['DC','RI'], 'sh');

ONCE YOU GENERATE THIS SCRIPT, EDIT IT TO ADD "set -e -u" AT THE TOP;
THIS SETTING WILL MAKE IT STOP ON ERROR OR UNITIALIZED VARIABLE AND
MAKE IT EASIER TO DEBUG ANY PROBLEMS.  THEN RUN THE SCRIPT AT THE
COMMAND LINE, REDIRECTING STANDARD OUTPUT AND STANDARD ERROR TO USEFUL
FILES.  YOU MAY WANT TO RUN "tail -f " TO SEE THE STANDARD ERROR AS IT
GETS WRITTEN.  FOR EXAMPLE:

$ sh foo.sh 1>out 2>err; tail -f err

-- WINDOWS USERS --
--To generate a WINDOWS DOS script
SELECT loader_generate_script(ARRAY['DC','RI'], 'windows');

If your script disappears without loading anything, 
most likely one of your path settings is wrong.  
To troubleshoot run the batch script by 
first opening up a commandline and executing the file.

That will keep the window open for you to see the error.

-- Next run the script to install any missing indexes --
SELECT install_missing_indexes();

Alternatively if you want to see what indexes will be created before
you create them run the below and manually run the steps generated:
SELECT missing_indexes_generate_script();


9. Copy and paste the generated script into a .bat or .sh file and put
in gisdata folder you created and then run it, OR IF YOU REDIRECTED
THE OUTPUT TO A FILE WITH "\o" MOVE THAT FILE TO GISDATA.

10. Test out the geocoder run these queries

-- To get the best rated answer --
-- this is generally faster
SELECT g.rating, 
	ST_X(geomout) As lon, 
	ST_Y(geomout) As lat, (addy).* 
FROM geocode('1731 New Hampshire Avenue Northwest, Washington, DC 20010', 1) As g;

--To get multiple answers if there is more than 1
SELECT g.rating, 
	ST_X(geomout) As lon, 
	ST_Y(geomout) As lat, (addy).* 
FROM geocode('1731 New Hampshire Avenue Northwest, Washington, DC 20010') As g;

STEPS TO UPGRADE YOUR INSTALL:
If you need to upgrade the geocoder/tiger loader from a pre-release
2.0.0 install -- run the upgrade_geocoder.sh or upgrade_geocoder.bat
script.

CAUTION: The upgrade script will drop any table columns that have a
norm_addy type for a column type.  This is rare if ever done so you
should be fine.  We plan to fix this later. It will also drop any
customizations you have made to the tiger_loader configuration tables.
To prevent this, you can remark out the install loader part.  This we
plan to remedy in the future.

It will also install any missing indexes that are deemed needed by
queries.

It will fail on some steps such as addition of new columns 
to lookup tables if they already exist in your intall.  
These errors can be safely ignored.