Instructions for using the NC Voter Database "Batch Match" Tool

The purpose of this tool is to match a list of names and addresses
(and perhaps other information) to the NC Voter Database, and display
the voter registration information for each person on the list.
I first built this tool for identifying the partisan political
affiliations of candidates in supposedly non-partisan races (such as
judicial races).  It successfully found the party affiliations for
196 of the 206 "non-partisan" judicial candidates in the 7/20/04
primary election.

It does not just do a simple exact-match comparison for names and
addresses.  It recognizes the equivalence of common given names and
nicknames, it takes into account that some people are called by
their middle names or their initials, and it recognizes that 'RD'
and 'Road' are equivalent, and that "POB 4157" and "Post Office
Box 4157" mean the same thing.  It recognizes that "VAN DYKE" is
a single surname but "SMITH III" is a surname plus a suffix.  It
can usually find voter records for people even if there are minor
misspellings of their town or address.

However, it will not find voter records for people with misspelled
last names (except for spacing differences - e.g., it recognizes
that "VAN DYKE" and "VANDYKE" are equivalent).


The result (output) is a web page showing the most likely voter registration
records for each of the people in your list of names and addresses.

Warning: If you give it a big list, you will get a big web page!
It tends to generate about 3-10 KB of HTML per person (more if the
person is not registered or has a very common name).  When I ran the
206 jducial candidates through it, the resulting page was a little
more than one megabyte.  That's a big web page!  When I ran 1766 local
candidates through it, the resulting page was more than 7 megabytes!

That is large enough to completely overwhelm a small computer.  So
unless your computer has at least 512 megabytes of RAM memory and a
modern browser, you should not even try to view a web page that large.
In fact, even if you do have a big, fast computer, I recommend that
you submit no more than about 1000 names and addresses at one time
to the Batch Match tool.


The input file is your list (batch) of names and addresss,
which you wish to match against the NC Voter Database.

To use this tool, you must first prepare a "CSV" (Comma-Separated Values)
file containing the names and addresses.  If you have Excel, or a
similar spreadsheet, the easiest way is probably to enter the names
and addresses into Excel, and then use "Save As" to save the file in CSV
format.  Alternately, you can export the information from a database,
or create it manually with a text editor.

If you use dBase/FoxBase/Paradox/etc., and your data is in .DBF files,
you can use the free DBF2CSV tool to convert a .DBF file to .CSV format.
You can download DBF2CSV here:  http://www.burtonsys.com/downloads.html

A CSV file is a text file with one line per "record."  Each line
consists of a series of fields separated by commas.  There should be
the same number of fields on each line.  Each field can optionally
be "quoted" with regular (double) quote marks (not 'apostrophes').
If a field contains commas, then it must be quoted!  Otherwise, the
quote marks are optional.  If a field contains a quote mark, it
should be doubled ("").

The first line in the CSV file is special.  It contains the "field
names" or "column headers."  If you are creating the .CSV file by
exporting it from a database, the first line will probably be created
automatically, from the field names.  If you use a spreadsheet, then
you must create the column headers as the first row in your spreadsheet.

The Batch Match Tool uses the field/column names to tell which fields
are voter names and which are addresses (and other fields), so that
it can match the information with the NC Voter Database.  The tool
works by first matching each person's last name to the 'last_name'
fields in the voter database.  Then, for voters with matching last
names, it checks first names or initials, middle names or initials,
name suffixes (Jr/Sr/III/IV), house numbers, city names, counties, zip
codes, etc., to find the voters who most closely match.  The best
match(es) are displayed in a table for each person, with the very
best ones at the top of the table.  In most cases, the correct voter
is the first one in the table.

Note: if you submit mutiple lists, be sure to give them different
file names.  Otherwise, the newer lists will overwrite the older ones.


You have quite a bit of flexibility for formatting the names and
addresses in your .CSV input file.  For voter names, the Batch Match
tool recognizes any or all of the following field names:

  'fullname'  (Voter's entire name, first name first, e.g., "Joe E. Stansbury III")
  'lastnamefirst'  (Voter's entire name, last name first with comma, e.g., "Stansbury, Joe E. III")
  'last_name'  (Surname alone, or surname and Jr/Sr/III/IV suffix)
  'first_midl_name'  (Voter's first name or first and middle name)
  'first_name'  (First name or initial, only.  2+ names, like "John, Sue & Toby," are OK.)
  'midl_name'  (Middle name or initial)
  'sufx'  (Jr/Sr/III/IV)
  'name_sufx_cd'  (synonym for 'sufx')

Important Note: every input record MUST have either 'fullname' field,
a 'lastnamefirst' field, or a 'last_name' field, because the tool completely
ignores voter records which do not match any specified surnames.

Note #2: everything is case-insensitive.  So "john" is equivalent
to "John" or "JOHN" or even "jOhN."


For street addresses it recognizes the following fields:

  'res_street_address'  (e.g., "109 Black Bear Ct" or "PO Box 4157")
  'res_city_state_zip'  (e.g., "Cary NC 27513")
  'house_num'  (e.g., the "109" of "109 Black Bear Ct")
  'boxnumber'  (e.g., "4157" of "POB 4157")
  'res_city'  (e.g., "Cary")
  'city'  (synonym for 'res_city')
  'res_zip'  (e.g., "27513")
  'zip'  (synonym for 'res_zip')
  'county'  (e.g., "Wake" or "92" -- see counties.html)
  'county_id'  (synonym for 'county')
  (Note: the state should always be NC!)

In addition, it recognizes many other field/column names from the voter
database files, though these must match exactly for the tool to recognize
that they are the same:

  'voter_reg_num'
  'status_cd'  or             'stat'
  'name_prefx_cd'  or         'prfx'
  'full_phone_number' (note: most counties have no phone numbers in the database)
  'drivers_lic'  or           'ncdl'
  'race_code'  or             'race'
  'ethnic_code'  or           'eth'
  'party_cd'  or              'party'
  'sex_code'  or              'sex'
  'age'  or                   'birth_age'
  'birth_place'  or           'birthplace'
  'registr_dt'  or            'date_of_registr'
  'precinct_abbrv'  or        'precinct'
  'municipality_desc'  or     'municipality'
  'ward_abbrv'  or            'ward'
  'cong_dist_abbrv'  or       'cong_dist'
  'super_court_abbrv'  or     'superior_ct'
  'judic_dist_abbrv'  or      'judic_dist'
  'nc_senate_abbrv'  or       'nc_senate'
  'nc_house_abbrv'  or        'nc_house'
  'county_commiss_abbrv'  or  'cnty_comm'
  'school_dist_abbrv'  or     'sch_dist'
  'fire_dist_abbrv'  or       'fire_dist'
  'water_dist_abbrv'  or      'water_dist'
  'sewer_dist_abbrv'  or      'sewer_dist'
  'sanit_dist_abbrv'  or      'sanit_dist'
  'rescue_dist_abbrv'  or     'rescue_dist'
  'munic_dist_abbrv'  or      'muni_dist'
  'munic_dist_desc'  or       'muni_dist_desc'
  'dist_1_abbrv'  or          'dist_1'
  'dist_1_desc'  or           'dist_1_desc'
  'dist_2_abbrv'  or          'dist_2'
  'dist_2_desc'  or           'dist_2_desc'
  'Confidential_ind'  or      'conf_ind'

Note: the BOE now stores age, rather than date-of-birth, in what used
to be the date_of_birth/birth_dt field.  So this tool used to accept
'birth_dt' or 'date_of_birth' instead of 'age' or 'birth_age'.  This
changes causes a minor problem, since ages change, and birth-dates don't.
So I really should do an approximate match on age, rather than an exact
match; however, I have yet to see a list that includes ages, anyhow, so
I haven't bothered to implement this change.


Here are some sample input and output files: samples.html

-Dave Burton
Tel: 1-919-481-0149