Devil Killer Is Here MiNi Shell
MiNi SheLL

Current Path : /proc/thread-self/root/usr/local/man/man3/
Linux boscustweb5002.eigbox.net 5.4.91 #1 SMP Wed Jan 20 18:10:28 EST 2021 x86_64
Current File : //proc/thread-self/root/usr/local/man/man3/Geo::StreetAddress::US.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "US 3"
.TH US 3 "2005-05-17" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Geo::StreetAddress::US \- Perl extension for parsing US street addresses
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Geo::StreetAddress::US;
.Ve
.PP
.Vb 2
\&  my $hashref = Geo::StreetAddress::US->parse_location(
\&                "1005 Gravenstein Hwy N, Sebastopol CA 95472" );
.Ve
.PP
.Vb 2
\&  my $hashref = Geo::StreetAddress::US->parse_location(
\&                "Hollywood & Vine, Los Angeles, CA" );
.Ve
.PP
.Vb 2
\&  my $hashref = Geo::StreetAddress::US->parse_address(
\&                "1600 Pennsylvania Ave, Washington, DC" );
.Ve
.PP
.Vb 2
\&  my $hashref = Geo::StreetAddress::US->parse_intersection(
\&                "Mission Street at Valencia Street, San Francisco, CA" );
.Ve
.PP
.Vb 2
\&  my $normal = Geo::StreetAddress::US->normalize_address( \e%spec );
\&      # the parse_* methods call this automatically...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Geo::StreetAddress::US is a regex-based street address and street intersection
parser for the United States. Its basic goal is to be as forgiving as possible
when parsing user-provided address strings. Geo::StreetAddress::US knows about
directional prefixes and suffixes, fractional building numbers, building units,
grid-based addresses (such as those used in parts of Utah), 5 and 9 digit \s-1ZIP\s0
codes, and all of the official \s-1USPS\s0 abbreviations for street types and state
names.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
Most Geo::StreetAddress::US methods return a reference to a hash containing
address or intersection information as one of their arguments. This
\&\*(L"address specifier\*(R" hash may contain any of the following fields for a
given address. If a given field is not present in the address, the 
corresponding key will be set to \f(CW\*(C`undef\*(C'\fR in the hash.
.Sh "\s-1ADDRESS\s0 \s-1SPECIFIER\s0"
.IX Subsection "ADDRESS SPECIFIER"
.IP "number" 4
.IX Item "number"
House or street number.
.IP "prefix" 4
.IX Item "prefix"
Directional prefix for the street, such as N, \s-1NE\s0, E, etc.  A given prefix
should be one to two characters long.
.IP "street" 4
.IX Item "street"
Name of the street, without directional or type qualifiers.
.IP "type" 4
.IX Item "type"
Abbreviated street type, e.g. Rd, St, Ave, etc. See the \s-1USPS\s0 official
type abbreviations at <http://www.usps.com/ncsc/lookups/abbr_suffix.txt> 
for a list of abbreviations used.
.IP "suffix" 4
.IX Item "suffix"
Directional suffix for the street, as above.
.IP "city" 4
.IX Item "city"
Name of the city, town, or other locale that the address is situated in.
.IP "state" 4
.IX Item "state"
The state which the address is situated in, given as its two-letter
postal abbreviation. See <http://www.usps.com/ncsc/lookups/abbr_state.txt>
for a list of abbreviations used.
.IP "zip" 4
.IX Item "zip"
Five digit \s-1ZIP\s0 postal code for the address, including leading zero, if needed.
.Sh "\s-1INTERSECTION\s0 \s-1SPECIFIER\s0"
.IX Subsection "INTERSECTION SPECIFIER"
.IP "prefix1, prefix2" 4
.IX Item "prefix1, prefix2"
Directional prefixes for the streets in question.
.IP "street1, street2" 4
.IX Item "street1, street2"
Names of the streets in question.
.IP "type1, type2" 4
.IX Item "type1, type2"
Street types for the streets in question.
.IP "suffix1, suffix2" 4
.IX Item "suffix1, suffix2"
Directional suffixes for the streets in question.
.IP "city" 4
.IX Item "city"
City or locale containing the intersection, as above.
.IP "state" 4
.IX Item "state"
State abbreviation, as above.
.IP "zip" 4
.IX Item "zip"
Five digit \s-1ZIP\s0 code, as above.
.SH "GLOBAL VARIABLES"
.IX Header "GLOBAL VARIABLES"
Geo::StreetAddress::US contains a number of global variables which it
uses to recognize different bits of \s-1US\s0 street addresses. Although you
will probably not need them, they are documented here for completeness's
sake.
.IP "%Directional" 4
.IX Item "%Directional"
Maps directional names (north, northeast, etc.) to abbreviations (N, \s-1NE\s0, etc.).
.IP "%Direction_Code" 4
.IX Item "%Direction_Code"
Maps directional abbreviations to directional names.
.IP "%Street_Type" 4
.IX Item "%Street_Type"
Maps lowercased \s-1USPS\s0 standard street types to their canonical postal
abbreviations as found in TIGER/Line.  See eg/get_street_abbrev.pl in
the distrbution for how this map was generated.
.IP "%State_Code" 4
.IX Item "%State_Code"
Maps lowercased \s-1US\s0 state and territory names to their canonical two-letter
postal abbreviations. See eg/get_state_abbrev.pl in the distrbution
for how this map was generated.
.IP "%State_FIPS" 4
.IX Item "%State_FIPS"
Maps two-digit \s-1FIPS\-55\s0 \s-1US\s0 state and territory codes (including the
leading zero!) as found in TIGER/Line to the state's canonical two-letter
postal abbreviation. See eg/get_state_fips.pl in the distrbution for
how this map was generated. Yes, I know the \s-1FIPS\s0 data also has the state
names. Oops.
.IP "%Addr_Match" 4
.IX Item "%Addr_Match"
A hash of compiled regular expressions corresponding to different
types of address or address portions. Defined regexen include
type, number, fraction, state, direct(ion), dircode, zip, corner,
street, place, address, and intersection.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.RE
.ie n .IP "Geo::StreetAddress::US\->parse_location( $string )"
.el .IP "Geo::StreetAddress::US\->parse_location( \f(CW$string\fR )"
.IX Item "Geo::StreetAddress::US->parse_location( $string )"
Parses any address or intersection string and returns the appropriate
specifier, by calling \fIparse_intersection()\fR or \fIparse_address()\fR as needed.
.RE
.ie n .IP "Geo::StreetAddress::US\->parse_address( $address_string )"
.el .IP "Geo::StreetAddress::US\->parse_address( \f(CW$address_string\fR )"
.IX Item "Geo::StreetAddress::US->parse_address( $address_string )"
Parses a street address into an address specifier, returning undef if
the address cannot be parsed. You probably want to use \fIparse_location()\fR
instead.
.RE
.ie n .IP "Geo::StreetAddress::US\->parse_intersection( $intersection_string )"
.el .IP "Geo::StreetAddress::US\->parse_intersection( \f(CW$intersection_string\fR )"
.IX Item "Geo::StreetAddress::US->parse_intersection( $intersection_string )"
Parses an intersection string into an intersection specifier, returning
undef if the address cannot be parsed. You probably want to use
\&\fIparse_location()\fR instead.
.RE
.ie n .IP "Geo::StreetAddress::US\->normalize_address( $spec )"
.el .IP "Geo::StreetAddress::US\->normalize_address( \f(CW$spec\fR )"
.IX Item "Geo::StreetAddress::US->normalize_address( $spec )"
Takes an address or intersection specifier, and normalizes its components,
stripping out all leading and trailing whitespace and punctuation, and
substituting official abbreviations for prefix, suffix, type, and state values.
Also, city names that are prefixed with a directional abbreviation (e.g. N, \s-1NE\s0,
etc.) have the abbreviation expanded.  The normalized specifier is returned.
.PP
Typically, you won't need to use this method, as the \f(CW\*(C`parse_*()\*(C'\fR methods
call it for you.
.PP
N.B., \f(CW\*(C`normalize_address()\*(C'\fR crops 9\-digit \s-1ZIP\s0 codes to 5 digits. This is for
the benefit of Geo::Coder::US and may not be what you want. E\-mail me if this
is a problem and I'll see what I can do to fix it.
.SH "BUGS, CAVEATS, MISCELLANY"
.IX Header "BUGS, CAVEATS, MISCELLANY"
Geo::StreetAddress::US might not correctly parse house numbers that contain
hyphens, such as those used in parts of Queens, New York. Also, some addresses
in rural Michigan and Illinois may contain letter prefixes to the building
number that may cause problems. Fixing these edge cases is on the to-do list,
to be sure. Patches welcome!
.PP
This software was originally part of Geo::Coder::US (q.v.) but was split apart
into an independent module for your convenience. Therefore it has some
behaviors which were designed for Geo::Coder::US, but which may not be right
for your purposes. If this turns out to be the case, please let me know.
.PP
Geo::StreetAddress::US does \fB\s-1NOT\s0\fR perform USPS-certified address normalization.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This software was originally part of \fIGeo::Coder::US\fR\|(3pm).
.PP
\&\fILingua::EN::AddressParse\fR\|(3pm) and \fIGeo::PostalAddress\fR\|(3pm) both do something
very similar to Geo::StreetAddress::US, but are either too strict/limited in
their address parsing, or not really specific enough in how they break down
addresses (for my purposes). If you want USPS-style address standardization,
try \fIScrape::USPS::ZipLookup\fR\|(3pm). Be aware, however, that it scrapes a form on
the \s-1USPS\s0 website in a way that may not be officially permitted and might break
at any time. If this module does not do what you want, you might give the
othersa try. All three modules are available from the \s-1CPAN\s0.
.PP
You can see Geo::StreetAddress::US in action at <http://geocoder.us/>.
.SH "APPRECIATION"
.IX Header "APPRECIATION"
Many thanks to Dave Rolsky for submitting a very useful patch to fix fractional
house numbers, dotted directionals, and other kinds of edge cases, e.g. South
St. He even submitted additional tests!
.SH "AUTHOR"
.IX Header "AUTHOR"
Schuyler D. Erle <schuyler@geocoder.us>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2005 by Schuyler D. Erle.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.4 or,
at your option, any later version of Perl 5 you may have available.
Creat By MiNi SheLL
Email: devilkiller@gmail.com