geocoder.us

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

• RESTful ASP Sample by Jay Turley
• PHP SOAP example by Kenny Wickstrom
• PHP with Pear by Ben Ramsey, with setCredentials call by Rob Hunter
• C# by Pat Palmer
• PHP Quickie by Todd Gardiner of Broomfield Designers

Special Note - 10/6/2005

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

http://support.microsoft.com/kb/887606" and http://support.microsoft.com/kb/832414

Other browsers still support the standard. Geocoder.us 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

Geocoder.us 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.

Methods

Return Values

Integration

Geocoder.us 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.

XML-RPC

    use XMLRPC::Lite;
    use strict;

    my $result = XMLRPC::Lite
	-> proxy( 'http://username:password@geocoder.us/member/service/xmlrpc')
	-> 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.

SOAP

    use SOAP::Lite;
    use strict;

    my $result = SOAP::Lite
	-> uri( 'http://rpc.geocoder.us/Geo/Coder/US' )
	-> proxy( 'http://username:password@geocoder.us/member/service/soap')
	-> 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!

REST-RDF

The REST interface allows you to make queries directly via an HTTP GET request.

http://username:password@geocoder.us/member/service/rest/geocode?address=1600+Pennsylvania+Ave,+Washington+DC

Fetching the above URL yields the following RDF/XML:

<rdf:RDF
  xmlns:dc="http://purl.org/dc/elements/1.1/"
  xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" >

<geo:Point rdf:nodeID="aid80564110">
    <dc:description>1600 Pennsylvania Ave NW, Washington DC 20502</dc:description>
    <geo:long>-77.037684</geo:long>
    <geo:lat>38.898748</geo:lat>
</geo:Point>
</rdf:RDF>

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
	->new
	->parse_uri( "http://username:password\@geocoder.us/member/service/rest/geocode"
	    . "?address=$addr" );

    print Dumper \@result;

The resulting graph structure looks like this:

@result = (
          [
            '_:id4280ab4aa61e',
            'http://www.w3.org/1999/02/22-rdf-syntax-ns#type',
            'http://www.w3.org/2003/01/geo/wgs84_pos#Point'
          ],
          [
            '_:id4280ab4aa61e',
            'http://purl.org/dc/elements/1.1/description',
            '1600 Pennsylvania Ave NW, Washington DC 20502'
          ],
          [
            '_:id4280ab4aa61e',
            'http://www.w3.org/2003/01/geo/wgs84_pos#long',
            '-77.037684'
          ],
          [
            '_:id4280ab4aa61e',
            'http://www.w3.org/2003/01/geo/wgs84_pos#lat',
            '38.898748'
          ]
        );

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

REST-CSV

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

http://username:password@geocoder.us/member/service/csv/geocode?address=1600+Pennsylvania+Ave,+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", "geocoder.us");      

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:

    http://geocoder.us/service/xmlrpc
    http://geocoder.us/service/soap
    http://geocoder.us/service/rest/...
    http://geocoder.us/service/csv/...

The absolute simplest way to get a geocode from the free service is to use the csv interface. Entering this in your browser:

 http://rpc.geocoder.us/service/csv?address=1600+Pennsylvania+Ave,+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 csv.pl 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 Geocoder.us for Address Parsing

You can use Geocoder.us for simple address parsing (but not standardization - this is not a USPS CASS product).

 http://rpc.geocoder.us/service/namedcsv?address=1600+Pennsylvania+Ave,+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 geocoder.us. 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'

http://rpc.geocoder.us/service/namedcsv?address=2101+Carr+Lakewood+CO&parse_address=1

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.