Description of SOAP service providing global place-name geocode data.

Revised December 6, 2004

Provided as a community service by: Transactional Web, Inc., (Earle West, author)

The purpose of this SOAP service is to provide a simple framework for a global facility finder. The key to finding any global facility is first finding out where you want to start in your search to find a nearby facility. To do this, you must first match the desired starting point to one of the more than 5 Million recognizeable global place-names.

The database behind this SOAP service is the United States National Imagery and Mapping Agency (NIMA) database of populated places. We've supplemented that (non-US) data with United States Geological Survey (USGS) data of US place names. We further supplemented that with all of the 5-digit US postal zip codes. In all, we have approximately 5,360,869 place names, each with a latitude and longitude. Our latitude and longitude is shown in signed-decimal degrees. No adjustment has been made for the different datums that might be used by our sources.

To use this service, you must have a 1) 'searchstring' and, 2) an ISO-standard country code. For US locations, we allow an additional qualifier, 3) the USPS standard 2-letter 'statecode' to narrow the search. . We treat the 'searchstring' as a prefix for all place names. We therefore match on any place-name that begins with the provided searchstring. For US locations, the searchstring may be a 5-digit USPS zipcode which will always return exactly one record.

The response includes information on 1) the number of records found matching your query, and 2) an array of arrays containing each of the records and a set of properties for each record. The properties for each record include the names of up to 4 administrative areas associated with your match, 4 descriptors for what kind of administrative area is referred to, and of course, latitude and longitude.

For those of you outside of the US, please accept our humblest appologies for naming every place in the world with a US-English place-name. Whil I'm sure this seems arrogant, our government does that for its own use and we use the data here. If you have other place name databases, please contact me and we will make some accomodation.

Usage of this service is carefully monitored and logged. Abusers will be barred without notice. The response limit is current limited to a maximum of 100 US place names or 200 non-US place names.

The WSDL is located here: http://www.churchzip.com/llserve.php?wsdl

The service and a test client are written in PHP. You may see the test web client here:

http://www.Transactionalweb.com/SOAP/geoserve-testclient.php

Both rely on SOAPx4 published by Dietrich Ayala. His easy-to-use software has been available without charge here: http://dietrich.ganx4.com/nusoap/index.php

 

A fragment of the geoserve-testclient.php (without using the WSDL) is shown below:

 

require_once('nusoap.php');
$parameters = array('searchstring'=>$searchstringfield, 'cc'=>$ccfield, 'statecode'=>$statecodefield);

$soapclient = new soapclient('http://churchzip.com/geosoap.php');
$returndata = $soapclient->call('geosearch',$parameters);

$records = $returndata['list'];

if($returndata['count']>0)
{
foreach($records as $key=>$record)
{
print $key . " ";
print $record['adminarea1'] . " ";
print $record['adminarea2'] . " ";
print $record['adminarea2type'] . " ";
print $record['adminarea3'] . " ";
print $record['adminarea3type'] . " ";
print $record['adminarea4'] . " ";
print $record['adminarea4type'] . " ";
print $record['latitude'] . " ";
print $record['longitude'] . " ";
print "<br>";
}
}

Here is a code snippet that shows what is going on in the server:

while (search string database results remain) (
$property['adminarea1'] = $row->adminarea1;
$property['adminarea1type'] = "Place Name";

$property['adminarea2'] = $row->adminarea2;
$property['adminarea2type'] = $row->adminarea2type;

$property['adminarea3'] = $row->adminarea3;
$property['adminarea3type'] = "Region";

$property['adminarea4'] = $row->adminarea4;
$property['adminarea4type'] = "Township";

$property['latitude'] = $row->lattitude;
$property['longitude'] = $row->longitude;

$count = $count + 1;
$entry[$count] = $property;

}

return array('count'=>$count,'records'=>$entry);

 

Check out our other web services.

Global Ski Resort Finder

Global Church Finder

Transactional Web, Inc. Earle West