Client Documentation

Updated 04 December 2005

Geocoding without a full address

Geocoder.us was originally designed for geocoding from a full street address, but people don't always have all the information. Geocoder.us now supports geocoding to the centroid of a ZIP code, or a city, state pair. These new forms are in BETA status (read what BETA means), and so far only work in the comma separated values form.

ZIP Code-CSV

This returns the centroid of a passed ZIP code. Zip codes were designed for mail delivery, not for the convenience of geo-spatial programmers, which means that they are not the best source of information. But they are ubiquitous in the US-and ubiquitous and messy beats clean and unavailable any day.

http://username:password@geocoder.us/member/service/csv/geocode?zip=95472

or with the free service:

http://geocoder.us/service/csv/geocode?zip=95472

Fetching the above URL yields the following CSV:

38.393314, -122.83666, Sebastopol, CA, 95472

City/State Code-CSV

This returns the location based on the GNIS (Geographic Names Information Service) location of a passed city and state. This uses the populated places data, so the idea of a 'city' can be rather stretched. There are some very very small places that are populated places, but hardly 'cities!'

http://username:password@geocoder.us/member/service/csv/geocode?city=san+francisco&state=ca

or with the free service:

http://geocoder.us/service/csv/geocode?city=san+francisco&state=ca

Fetching the above URL yields the following CSV:

37.775, -122.418333333333, San Francisco, San Francisco, CA

The results are latitude, longitude, County, City, State. Sometimes there can be multiple cities with the same name in a state. In that case all of the cities are returned, sorted in descending order by estimated population. In my case there are two Sebastopols in California.

http://geocoder.us/service/csv/geocode?city=sebastopol&state=ca
Returns multiple results:
38.4022222222222, -122.822777777778, Sonoma, Sebastopol, CA
39.3627777777778, -121.12, Nevada, Sebastopol, CA

The first is my own fair city in Sonoma County, the second is in Nevada County. My city is the largest. Google Maps doesn't even find the one in Nevada County, while Mapquest does (it is between Sweetland and North San Juan north of Nevada City-grand metropoli all). The theory is that the largest city with the same name is probably what you are looking for.