Client Documentation

Jan 31, 2012

Other Documentation

Read about Bulk Geocoding - you send a file, you get results

City/State or Zip code geocoding for incomplete addresses

Calculating distances

Code Samples!

Slowly code samples are being gathered like wayward kindergartners from a field trip to the candy factory. Do you want your name in lights? Or at least a blink tag :-) Send in your code and it shall be added

Special Note - 10/6/2005

Microsoft has changed IE to disable passing login credentials in a URL. This sort of complicates things. See:" and

Other browsers still support the standard. user Jeremy Walker has sent in a C# .NET sample of a work around for this issue that would probably also work for other strongly typed languages. Thank you Jeremy! (update: Apr 21, fixed apparent typo in the sample. the lat was the long and the long was the lat :-)

Overview offers four different ways to access our web services: an XML-RPC interface, a SOAP interface, a REST interface that returns an RDF/XML document, and a REST interface that returns a plain text comma separated values result. The methods and return values are equivalent across all three interfaces.


GeocoderResult[] geocode ( string location )
Takes a US address or intersection and returns a list of results. All results from a single lookup will be either of type GeocoderAddressResult or of type GeocoderInterectionResult. If the address can be parsed but not found, a single result is returned with lat and long left undefined. If the address cannot be parsed, an empty list is returned. If the address cannot be found exactly, the closest result is returned. If a city and state, or a ZIP code, is not provided, the lookup will fail.
GeocoderAddressResult[] geocode_address ( string address )
Works exactly like geocode(), but only accepts street addresses.
GeocoderIntersectionResult[] geocode_intersection ( string intersection )
Works exactly like geocode(), but only accepts street intersections.

The functioning of these methods is described in further detail by the Geo::Coder::US documentation.

Return Values

The following objects might be returned by an address lookup:

class GeocoderResult:
string city
string state
string zip
float lat
float long
class GeocoderAddressResult: inherits from GeocoderResult
string number
string prefix
string street
string type
string suffix
class GeocoderInteresectionResult: inherits from GeocoderResult
string prefix1
string street1
string type1
string suffix1
string prefix2
string street2
string type2
string suffix2

In implementation languages that implement hashes or dicts (e.g. Perl, Python, PHP), results are returned using the native dict-type structures, rather than as typed objects.

Integration supports the XML-RPC and SOAP web services protocols, and also supports a REST-ful interface that returns RDF/XML documents. Although our code examples are in Perl, we believe that our services should be accessible from any language or platform that speaks one of our supported protocols. If you are a Premium User, you must supply your username and password via HTTP Basic Authentication for each request. As the examples will show, this should not be difficult to do.


    use XMLRPC::Lite;
    use strict;

    my $result = XMLRPC::Lite
	-> proxy( '')
	-> geocode( '1600 Pennsylvania Av, Washington, DC' )
	-> result;

If a valid username and password are provided, then the following data structure is stored in $result:

    $result = [
            'number' => '1600',
            'prefix' => ''
            'street' => 'Pennsylvania',
            'type' => 'Ave',
            'suffix' => 'NW',
            'city' => 'Washington',
            'state' => 'DC',
            'zip' => '20502',
            'lat' => '38.898748',
            'long' => '-77.037684',

Addresses that can be parsed but not found will return the following structure:

    $result = [
            'number' => '1600',
            'prefix' => ''
            'street' => 'Pennsyltoonia',
            'type' => 'Ave',
            'suffix' => '',
            'city' => 'Washington',
            'state' => 'DC',
            'zip' => '',

Addresses that cannot even be parsed will return an empty list.

If you have trouble with XMLRPC::Lite, try the following incantation:

    use XMLRPC::Lite +trace;

Multiple matching addresses may be found. You can obtain XMLRPC::Lite from the CPAN.


    use SOAP::Lite;
    use strict;

    my $result = SOAP::Lite
	-> uri( '' )
	-> proxy( '')
	-> geocode( '1600 Pennsylvania Av, Washington, DC' )
	-> result;

The returned data structures are identical to those returned from the XML-RPC interface. Users of strongly typed languages like Java, C++, C# may wish to make use of the WSDL description file written by Scott Gunn. You may need to alter this file in order to add your HTTP Basic Auth credentials, depending on your SOAP client libraries. Douglass Davis emailed to say we there were non-printable characters in that WSDL file that PHP5 won't process. He sent us this WSDL description that apparantly works with PHP5. Many thanks to Scott and Douglass!


The REST interface allows you to make queries directly via an HTTP GET request.,+Washington+DC

Fetching the above URL yields the following RDF/XML:

  xmlns:rdf="" >

<geo:Point rdf:nodeID="aid80564110">
    <dc:description>1600 Pennsylvania Ave NW, Washington DC 20502</dc:description>

You can use RDF::Simple::Parser or XML::Simple to parse this into a data structure, e.g.:

    use RDF::Simple::Parser;
    use URI::Escape;
    use Data::Dumper;

    my $addr = uri_escape( "1600 Pennsylvania Ave, Washington, DC" );

    my @result = RDF::Simple::Parser
	->parse_uri( "http://username:password\"
	    . "?address=$addr" );

    print Dumper \@result;

The resulting graph structure looks like this:

@result = (
            '1600 Pennsylvania Ave NW, Washington DC 20502'

The Redland project provides an RDF parser with bindings for many languages.


The CSV interface allows you to make queries directly via an HTTP GET request and get a plain text result.,+Washington+DC

Fetching the above URL yields the following CSV:

38.898748,-77.037684,1600 Pennsylvania Ave NW,Washington,DC,20502
A geocoder user, Shaun W. Taylor, says that encoding the username and password on the URL did not work for him using Java. He offered this sample: writes:
String authorization = Base64Coder.encodeString(“myusername:mypassword”);
httpUrlConnection.addRequestProperty("Authorization", "Basic " + authorization);
httpUrlConnection.addRequestProperty("WWW-Authenticate", "");      
can be found here Perhaps it will save someone some time." Thanks Shaun!

Using the Free Service

The free service is available for non-commercial uses only. The service URLs are as follows:
The absolute simplest way to get a geocode from the free service is to use the csv interface. Entering this in your browser:,+Washington+DC
Returns this result:

38.898748,-77.037684,1600 Pennsylvania Ave NW,Washington,DC,20502
In Perl you can use the LWP::Simple module. See for an example.

It is not necessary to use a username and password with the free service, but we encourage you to sign up for an account, so that we can keep you informed of changes and improvements to the service.

If you are acting on behalf of a for-profit business entity, or planning to use the information as part of a profit making activity, you must purchase a commercial license. If you have a commercial license, you may not use the free service under any circumstances. You should be aware that the free service is actively throttled, and so the commercial service will be faster. Please see our Terms and Conditions of Service for more information.

Using for Address Parsing

You can use for simple address parsing (but not standardization - this is not a USPS CASS product).,+Washington+DC&parse_address=1
Returns this result:

number=1600,prefix=,street=Pennsylvania,type=Ave,suffix=,city=Washington,state=DC,zip=,original address
lat=38.898748,long=-77.037684,number=1600,prefix=,street=Pennsylvania,type=Ave,suffix=NW,city=Washington,state=DC,zip=20502,geocoder modified
The first line ending with'original address' is the original address you passed in, broken into parts by The second line ending 'geocoder modified' adds the lat, long, as well as any fields which the geocoder was able to identify-in this case the zip code.

In this example we pass an incomplete address, '2101 Carr Lakewood, CO'
Returns this result:

number=2101,prefix=,street=Carr,type=,suffix=,city=Lakewood,state=CO,zip=,original address
lat=39.748719,long=-105.090900,number=2101,prefix=,street=Carr,type=St,suffix=,city=Lakewood,state=CO,zip=80214,geocoder modified
lat=39.678687,long=-105.090740,number=2101,prefix=S,street=Carr,type=St,suffix=,city=Lakewood,state=CO,zip=80227,geocoder modified
The first line is the original address, split into fields. the second line is for '2101 Carr Street, Lakewood, CO 80214,' while the second is for South Carr Street, 80227. So both the zip code and street prefix were added. Because this case is ambiguous - both addresses are equally valid, you are forced to make a judgment call on which one you really meant.