Geo::Coder::US 1.00

You can find a live demo of this code at http://geocoder.us/. The demo.cgi script is included in eg/ directory distributed with this module, along with a whole bunch of other goodies. See Geo:Coder:US:Import for how to build your own Geo:Coder:US database.

Consider using a web service to access this geocoder over the Internet, rather than going to all the trouble of building a database yourself. See eg/soap-client.pl, eg/xmlrpc-client.pl, and eg/rest-client.pl for different examples of working clients for the rpc.geocoder.us geocoder web service.

Major Features:

1. Geo:Coder:US->geocode( $string )
   • Given a string containing a street address or intersection, return a list of specifiers including latitude and longitude for all matching entities in the database. To keep from churning over the entire database, the given address string must contain either a city and state, or a ZIP code (or both), or geocode() will return undef.
   • geocode() will attempt to normalize directional prefixes and suffixes, street types, and state abbreviations, as well as substitute TIGER/Line's idea of the "primary street name", if an alternate street name was provided instead.
   • If geocode() can parse the address, but not find a match in the database, it will return a hashref containing the parsed and normalized address or intersection, but without the "lat" and "long" keys specifying the location. If geocode() cannot even parse the address, it will return undef. Be sure to check for the existence of "lat" and "long" keys in the hashes returned from geocode() before attempting to use the values! This serves to distinguish between addresses that cannot be found versus addresses that are completely unparseable.
   • geocode() attempts to be as forgiving as possible when geocoding an address. If you say "Mission Ave" and all it knows about is "Mission St", then "Mission St" is what you'll get back. If you leave off directional identifiers, geocode() will return address geocoded in all the variants it can find, i.e. both "N Main St" and "S Main St".
   • Don't be surprised if geocoding an intersection returns more than one lat/long pair for a single intersection. If one of the streets curves greatly or doglegs even slightly, this will be the likely outcome.
   • geocode() is probably the method you want to use. See more in the following section on the structure of the returned address and intersection specifiers.
2. Geo:Coder:US->geocode_address( $string )
   • Works exactly like geocode(), but only parses addresses.
3. Geo:Coder:US->geocode_intersection( $string )
   • Works exactly like geocode(), but only parses intersections.
4. Geo:Coder:US->filter_ranges( $spec, @candidates )
   • Filters a list of address specifiers (presumably from the database) against a query specifier, filtering by prefix, type, suffix, or primary name if possible. Returns a list of matching specifiers. filter_ranges() will ignore a filtering step if it would result in no specifiers being returned. You probably won't need to use this.
5. Geo:Coder:US->find_ranges( $address_spec )
   • Given a normalized address specifier, return all the address ranges in the database that appear to cover that address. find_ranges() ignores prefix, suffix, and type fields in the specifier for search purposes, and then filters against them ex post facto. The intention for find_ranges() to find the closest match possible in preference to returning nothing. You probably want to use lookup_ranges() instead, which will call find_ranges() for you.
6. Geo:Coder:US->lookup_ranges( $address_spec, @ranges )
   • Given an address specifier and (optionally) some address ranges from the database, interpolate the street address into the street segment referred to by the address range, and return a latitude and longitude for the given address within each of the given ranges. If @ranges is not given, lookup_ranges() calls find_ranges() with the given address specifier, and uses those returned. You probably want to just use geocode() instead, which also parses an address string and determines whether it's a proper address or an intersection automatically.
7. Geo:Coder:US->find_segments( $intersection_spec )
   • Given a normalized intersection specifier, find all of the street segments in the database matching the two given streets in the given locale or ZIP code. find_segments() ignores prefix, suffix, and type fields in the specifier for search purposes, and then filters against them ex post facto. The intention for find_segments() to find the closest match possible in preference to returning nothing. You probably want to use lookup_intersection() instead, which will call find_segments() for you.
8. Geo:Coder:US->lookup_intersection( $intersection_spec )
   • Given an intersection specifier, return all of the intersections in the database between the two streets specified, plus a latitude and longitude for each intersection. You probably want to just use geocode() instead, which also parses an address string and determines whether it's a proper address or an intersection automatically.

Requirements: Perl