Page tree
Skip to end of metadata
Go to start of metadata

Introduction

DOTS Address Geocode – US is a publicly available XML and JSON web service that provides latitude/longitude and metadata information about a physical US address. The service provides geocoding information, such as the latitude and longitude location of a US address, along with demographic information, such as the census tract, block and other metadata.

DOTS Address Geocode – US can help provide instant address locations to websites or enhancement to contact lists.


NOTE: The DOTS Address Geocode web service has recently been updated, and as such some of the older operations have been deprecated.  If you are still currently using the older operations of the service, you can refer to the developer's guide below for information concerning integration, inputs and outputs for the deprecated operations.

DOTS Address Geocode - US (Includes deprecated operations)

Integration

Integrating DOTS Address Geocode – US into your application should be easy and straightforward. If you are using a common platform, Service Objects may already have sample code built that you can use:
https://www.serviceobjects.com/developers/sample-code/address-geocode-us

However, if you are using a common platform that does not already have sample code, you can ask Service Objects to build you an example. Email support@serviceobjects.com for more details.

Web Service Structure:

Web services are methods that integrate with other applications via the web, and encapsulate complex business logic. Web services are too large a topic to cover in this document, but Service Objects has developed its web services to be as easy to integrate and as accessible as possible.
DOTS Address Geocode – US is a public XML web service that supports SOAP, POST and GET operations.

The host path, or physical location of the web service is here:
https:/trial.serviceobjects.com/GCR/

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the "Service Definition" link.):
https://trial.serviceobjects.com/gcr/soap.svc?wsdl

Service XML Request Help Page

https://trial.serviceobjects.com/gcr/api.svc/xml/help

Service JSON Request Help Page

https://trial.serviceobjects.com/gcr/api.svc/json/help

Important Note!
SOAP is done via POST, only with special XML markup in the post-body.

This XML is the definition of the web service, meaning its inputs, outputs, operations, and the like. Most likely, you will have another tool read this WSDL and make the operations available to you in your application. Whenever your utilities or IDE asks for a WSDL path to DOTS Address Geocode – US, you can provide this one.

Every web service has operations that it offers to subscribers – methods that do different work and return different output. Examining the link above, you will notice several of these operations available, which are described in detail later on.


Code Snippets




GeoCoder C# Code Snippet
GCRService.GCRSoapServiceClient client = new GCRService.GCRSoapServiceClient();
GCRService.GCRSoapServiceClient clientbackup = new GCRService.GCRSoapServiceClient();
GCRService.Location_V4 response = new GCRService.Location_V4();
try
{
    response = client.GetBestMatch_V4(Address.Text, City.Text, State.Text, PostalCode.Text, LicenseKey.Text);
    if (response == null || (response.Error != null && response.Error.Number == "4"))
    {
        throw new Exception();
    }
}
catch
{
    response = clientbackup.GetBestMatch_V4(Address.Text, City.Text, State.Text, PostalCode.Text, LicenseKey.Text);
}
if (response.Error == null)
{
    ProcessValidResponse(response);
}
else
{
    ProcessErrorResponse(response.Error);
}


GeoCoder Java Code Snippet
GCRSoapServiceLocator locator = new GCRSoapServiceLocator();
//use ssl
locator.setDOTSGeoCoderEndpointAddress("https://trial.serviceobjects.com/GCR/soap.svc/SOAP");
IGCRSoapService gcr = locator.getDOTSGeoCoder();
DOTSGeoCoderStub soap = (DOTSGeoCoderStub)gcr;
soap.setTimeout(5000);

try
{
	outputs = soap.getBestMatch_V4(address, city, state, postalcode, licenseKey);
	gcrerror = outputs.getError();
	
	if(gcrerror !=null && gcrerror.getNumber() == "4")
	{
		throw new Exception();	
	}
}
catch(Exception e)
{	//FAILOVER- USE BACKUP NOW
	try{
		//CALL SOAP USING BACKUP URL (Change the endpoint)
		outputs = soap.getBestMatch_V4(address, city, state, postalcode, licenseKey);
		gcrerror = outputs.getError();
	}
	catch(Exception ex)
	{
	
		throw new Exception("Both Primary and Backup soap calls failed: " + ex.getMessage());
	}
}


GeoCoder PHP Code Snippets
$URL = "https://trial.serviceobjects.com/GCR/soap.svc?singleWsdl";
//use backup url once given purchased license key
$backupURL = "https://trial.serviceobjects.com/GCR/soap.svc?singleWsdl";
 
$client = new SoapClient($URL);
//$soapClient = new SoapClient($URL, array( "trace" => 1 ));
$outputs = $client->GetBestMatch_V4($params)->GetBestMatch_V4Result;
if (empty($outputs))
{
    $backupClient = new SoapClient($backupURL);
    $outputs = $client->GetBestMatch_V4($params)->GetBestMatch_V4Result;
}


GeoCoder RoR Code Snippets
dotsGCRPrimary = "https://trial.serviceobjects.com/gcr/soap.svc?wsdl"
dotsGCRBackup = "https://trial.serviceobjects.com/gcr/soap.svc?wsdl"

begin
	#initializes the soap client. The convert request keys global is necessary to receive a response from the service.
	client = Savon.client(	wsdl: dotsGCRPrimary,
							element_form_default: :qualified,
							convert_request_keys_to: :camelcase
						 )
	#Calls the with given inptus and converts response to a hash.
	response = client.call(:get_best_match_v4, message: message).to_hash
	#Checks to see what results came back from the service
	processresults(response)			
	
#If an error occurs during the call, this will use the Backup url and attempt to retrieve data.
rescue Savon::Error => e
	begin
	backupclient = Savon.client(	wsdl: dotsGCRBackup,
									element_form_default: :qualified,
									convert_request_keys_to: :camelcase
							   )
	#Sets the response to the backclient call to the operation and converts response to a hash.
	response = backupclient.call(:get_best_match_v4, message: message).to_hash
	processresults(response)
	#If the backup url failed, this will display the error received from the server
	rescue Savon::Error =>error
		@status = error
		@displaydata = {"error" => "A Big Error Occured"}
	end
end


Address Geocode US Python Code Snippet
    
mAddress =  Address.get()
if mAddress is None or  mAddress == "":
    mAddress = " "
mCity = City.get()
if mCity is None or mCity == "":
    mCity = " "
mState = State.get()
if mState is None or mState == "":
    mState = " "
mPostalCode = PostalCode.get()
if mPostalCode is None or mPostalCode == "":
    mPostalCode = " "
mLicenseKey = LicenseKey.get()
if mLicenseKey is None or mLicenseKey == "":
    mLicenseKey = " "
#Set the primary and backup URLs as needed
primaryURL = 'https://trial.serviceobjects.com/gcr/soap.svc?wsdl'
backupURL = 'https://trial.serviceobjects.com/gcr/soap.svc?wsdl'
#This block of code calls the web service and prints the resulting values to the screen
try:
    client = Client(primaryURL)
    result = client.service.GetBestMatch_V4(Address=mAddress, City=mCity, State=mState, PostalCode=mPostalCode, LicenseKey=mLicenseKey)
    #Loops through either the error result or proper result and displays values to the screen.
    if hasattr(result, 'Error') :
        for value in result.Error:
            Label(swin.window, text=str(value[0]) + " : " + str(value[1]) if value[1] else str(value[0])+": None").pack()
    #If a valid response was received from this service, this will print the result
    else:
        for value in result:
            if value[0] != 'InformationComponents':
                Label(swin.window, text=str(value[0]) + ":  " + str(value[1]) if str(value[1]) else str(value[0]) + " : None").pack()
        if "InformationComponents" in result:
            infoComponent = result.InformationComponents.InformationComponent
            for i in range(0, len(infoComponent)):
                Label(swin.window, text=str(infoComponent[i].Name) + ": " + str(infoComponent[i].Value)).pack()
    


Address GeoCoder ColdFusion Code Snippet
<cfscript>
		try
		{
			if (isDefined("form.Action") AND Action neq "")
			{
				wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/gcr/soap.svc?wsdl");							  
				outputs = wsresponse.getBestMatch_V4("#Address#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
			}
		}
	catch(any Exception){
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/gcr/soap.svc?wsdl");							  
					outputs = wsresponse.getBestMatch_V4("#Address#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
				}
			}
			catch(any Exception)	
				{
		  		 writeoutput("An Error Has Occured. Please Reload and try again #Exception.message#");		  		 
		 		}
	    }
</cfscript>


Address GeoCoder VB Code Snippet
Try
    Dim ws As New GCRService.GCRSoapServiceClient
    Dim response As GCRService.Location_V4
    response = ws.GetBestMatch_V4(Address.Text, City.Text, State.Text, PostalCode.Text, LicenseKey.Text)
    If (response.Error Is Nothing) Then
        ProcessValidResponse(response)
    Else
        ProcessErrorResponse(response.Error)
    End If

Catch
    ''Set the Primary and Backup Service References as necessary
    Try
        Dim wsbackup As New GCRService.GCRSoapServiceClient
        Dim response As GCRService.Location_V4
        response = wsbackup.GetBestMatch_V4(Address.Text, City.Text, State.Text, PostalCode.Text, LicenseKey.Text)
        If (response.Error Is Nothing) Then
            ProcessValidResponse(response)
        Else
            ProcessErrorResponse(response.Error)
        End If
    Catch ex As Exception
        resultsLabel.Visible = True
        resultsLabel.Text = ex.Message

    End Try

End Try


Address GeoCoder Apex Code Snippet
wwwServiceobjectsCom.Location_V4 result;
try{
wwwServiceobjectsCom.DOTSGeoCoder client = new wwwServiceobjectsCom.DOTSGeoCoder();
result = client.GetBestMatch_V4([Address], [City], [State], [PostalCode], [LicenseKey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsCom.DOTSGeoCoder backupClient = new wwwServiceobjectsCom.DOTSGeoCoder();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'https://trial.serviceobjects.com/GCR/soap.svc/SOAP';
result = backupClient.GetBestMatch_V4([Address], [City], [State], [PostalCode], [LicenseKey]);
}


Address GeoCoder TSQL Code Snippet
SET @requestBody ='<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
				   '<s:Body>'+
				   '<GetBestMatch_V4 xmlns="http://www.serviceobjects.com">'+
				   '<Address>' + @address + '</Address>'+
				   '<City>' + @City + '</City>'+
				   '<State>' + @State + '</State>'+
				   '<PostalCode>' + @postalcode + '</PostalCode>'+
				   '<LicenseKey>' + @key + '</LicenseKey>'+
				   '</GetBestMatch_V4>'+
				   '</s:Body>'+
				   '</s:Envelope>'
SET @requestLength = LEN(@requestBody)
	--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/GCR/soap.svc/SOAP', false
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'ws.serviceobjects.com'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/IGCRSoapService/GetBestMatch_V4"'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
	EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
	EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
	EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/GCR/soap.svc/SOAP', false
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'wsbackup.serviceobjects.com'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/IGCRSoapService/GetBestMatch_V4"'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
		EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
		EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
		EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
	END
END


Address GeoCoder NodeJS Code Snippet
var args = {Address: 'Address', 
			City: 'City', 
			State: 'State', 
			PostalCode: 'PostalCode', 
			LicenseKey: 'Your-License-Key'};
soap.createClient(primaryUrl, function(err, client) {
	
  	client.GetBestMatch_V4(args, function(err, result) {
  		//This is where you will handle the service results. Your business logic will determine
  		//how the validated information is used.
  		//The exact output can be found in our documentation:
  		//https://docs.serviceobjects.com/display/devguide/DOTS+Address+Geocode++-++US
  		if(err != null || result == null)
  		{
  			//There was an error that occurred that wasn't part of the normal service response
  			return;
  		}
  		else{
  			//Check for an error object
  			if(result.GetBestMatch_V4Result.Error != null)
  			{
  				//An error object was returned by the service and you will want to use 
  				//the following failover logic.
  				//If it was a Service Objects Fatal exception we recommend trying 
  				//a backup server. 
  				if(result.GetBestMatch_V4Result.Error.Number == "4")
  				{
  					//The actual backup url will be provided when you purchase a license key
  					var backupUrl = 'https://trial.serviceobjects.com/gcr/soap.svc?wsdl';
  					soap.createClient(backupUrl, function(failoverErr, backupClient) {
	
  						backupClient.GetBestMatch_V4(args, function(failoverErr, failoverResult) {
  							//Handle the failoverErr or failoverResult objects.
  							return;
  						});
  					});
  				}
  				else{
  					//The Error object isn't of the type "Service Objects Fatal" so
  					//there is no need to use the failover logic. There was some Error of
  					//type Authorization, User Input, or Domain Specific.
  					response.writeHead(200, "OK", {'Content-Type': 'text/html'});
 	     			response.end(JSON.stringify(result));
  					return;
  				}
  			}
  			else{
  				//You have a non Error response.
  				//All of the data will reside within result.GetBestMatchesResult
  				//As an easy to see what the service returns I am returning a JSON 
 	     		//serialized version as the response.
      			response.writeHead(200, "OK", {'Content-Type': 'text/html'});
 	     		response.end(JSON.stringify(result));
      			return;
  			}
  		}
 		});
});



GeoCoder C# Rest Code Snippet
string primaryURL = "https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey;
string backupURL = "https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey;
Location_V4 response = httpGet(primaryURL);
if (response == null || (response.Error != null && response.Error.Number == "4"))
{
    response = httpGet(backupURL);
}
if (response.Error == null)
{
    ProcessValidResponse(response);
}
else
{
    ProcessErrorResponse(response.Error);
}


GeoCoder Java Rest Code Snippet
JSONObject results = RestClient(mainURL);	
try {
	if (ErrorMessages != null || (results.getJSONObject("Location_V4").has("Error") && results.getJSONObject("Location_V4").getJSONObject("Error").get("Number") == "3")) {
		// BACKUP
		results = RestClient(backupURL);
	}
} catch (JSONException e) {
	// TODO Auto-generated catch block
	e.printStackTrace();
}

return results;


GeoCoder PHP Rest Code Snippets
$URL = "https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=".urlencode($Address)."&City=".urlencode($City)."&State=".urldecode($State)."&PostalCode=".urldecode($PostalCode)."&LicenseKey=".urlencode($LicenseKey);
//use backup url once given purchased license key
$backupURL = "https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=".urlencode($Address)."&City=".urlencode($City)."&State=".urldecode($State)."&PostalCode=".urldecode($PostalCode)."&LicenseKey=".urlencode($LicenseKey);
try{
	// Get cURL resource
	$curl = curl_init();
	curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $URL, CURLOPT_USERAGENT => 'Service Objects Geocode US'));
	curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
	// Send the request & save response to $resp
	$resp = curl_exec($curl);
                curl_close($curl);
	$outputs = new SimpleXMLElement($resp);
	// Close request to clear up some resources
	if($outputs == null || ($outputs->Error != null || $outputs->Error->Number == "4"))
	{
                        $curl = curl_init();
		echo "IN back up block";
		curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $backupURL, CURLOPT_USERAGENT => 'Service Objects Geocode US'));
		curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
		// Send the request & save response to $resp
		$resp = curl_exec($curl);
		if($resp == false)
		{
			curl_close($curl);
			return;
		}
                        curl_close($curl);
                        $outputs = new SimpleXMLElement($resp);
                        
	}


GeoCoder RoR Rest Code Snippets
#Set Primary and Backup URLs as needed. This method encodes and standardizes the URI to pass to the REST service.
primaryURL = URI.encode("https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey)
backupURL = URI.encode("https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey)
#These are set to access the hash that is returned
@gcrresult ="Location_V4"
@gcrerror = "Error"
  #Begins the call the RESTful web service
begin
  response = HTTParty.get(primaryURL, timeout: default_timeout)
  #processes the response to display to the screen
  
  #Passes the response returned from HTTParty and processes them depending on the results
  processresults(response)
  
 rescue StandardError => e
 		begin
 		#uses the backupURl in the event that the service encountered an error
 		response = HTTParty.get(backupURL, timeout: default_timeout)
    
    #processes the response returned from using the backupURL
 		processresults(response)
    #If the backup url railed this will raise an error and display the 
    #error message returned from the HTTParty gem.
 		rescue StandardError => error
 			@status = error.message
 			@displaydata = {"Error" => "A Big Error Occured"}
 		end
end


Address Geocode US Python Code Snippet
    
#Set the primary and backup URLs as necessary
primaryURL = 'https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?'
backupURL = 'https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?'
#The Requests package allows the user to format the path parameters like so instead of having to manually insert them into the URL
inputs = {'Address': mAddress, 'City': mCity, 'State': mState, 'PostalCode': mPostalCode, 'LicenseKey': mLicenseKey}
try:
    result = requests.get(primaryURL, params=inputs)
    #Parses the XML response from the service into a python dictionary type
    outputs = xmltodict.parse(result.content)
    #checks the output for Errors and displays the info accordingly
    if 'Error' in outputs['Location_V4']:
        #loops through the response from the service and prints the values to the screen.
        for key, value in outputs['Location_V4']['Error'].iteritems():
            Label(swin.window, text=str(key) + " : " + str(value)).pack()
    else:
        #Removes unnecessary entries that were parsed into the python dictionary from XML response of service
        outputs['Location_V4'].pop("@xmlns:i", None)
        outputs['Location_V4'].pop("@xmlns:xsd", None)
        outputs['Location_V4'].pop("@xmlns", None)
        for key, value in outputs['Location_V4'].iteritems():
            if key!= 'InformationComponents':
                Label(swin.window, text=str(key) + " : " + str(value)).pack()
        if 'InformationComponents' in outputs['Location_V4']:
            infoComponent = outputs['Location_V4']['InformationComponents']['InformationComponent']
            for i in range(0, len(infoComponent)):
                Label(swin.window, text=str(infoComponent[i]["Name"]) + ": " + str(infoComponent[i]["Value"])).pack()
    


Address GeoCoder ColdFusion Code Snippet
<!--Makes Request to web service --->
<cfIf isDefined("form.Action") AND Action neq "" >
	<cftry>
		<cfset primaryURL = "https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=#Address#&City=#City#&State=#State#&PostalCode=#PostalCode#&LicenseKey=#LicenseKey#">
		<cfhttp url="#primaryURL#" 
		method="get"
		result="response">
		<cfset outputs = XmlParse(response.FileContent)>
		<cfcatch>
			<cftry>
				<cfset backupURL = "https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=#Address#&City=#City#&State=#State#&PostalCode=#PostalCode#&LicenseKey=#LicenseKey#">
				<cfhttp url="#backupURL#" 
				method="get"
				result="response">
				<cfset outputs = XmlParse(response.FileContent)>				
				<cfcatch >
					<cfoutput >
						The Following Error Occured: #response.StatusCode#
					</cfoutput>
				</cfcatch>
			</cftry>
		</cfcatch>
	</cftry>
</cfif>


Address GeoCoder VB Rest Code Snippet
'encodes the URLs for the get Call. Set the primary and back urls as necessary
Dim primaryurl As String = "https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey
Dim backupurl As String = "https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey
Dim wsresponse As GCRResponse.Location_V4 = httpGet(primaryurl)

'checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
If wsresponse Is Nothing OrElse (wsresponse.[Error] IsNot Nothing AndAlso wsresponse.[Error].Number = "4") Then
    wsresponse = httpGet(backupurl)
End If
If wsresponse.[Error] IsNot Nothing Then
    ProcessErrorResponse(wsresponse.[Error])
Else
    ProcessSuccessfulResponse(wsresponse)


Address GeoCoder TSQL Rest Code Snippet
--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	SET @sUrl = 'https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=' + @address + '&City=' + @city + '&State=' + @state + '&PostalCode=' + @postalcode + '&LicenseKey=' + @key
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sUrl, false
	EXEC sp_OAMethod @obj, 'send'
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		SET @sBackupUrl = 'https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=' + @address + '&City=' + @city + '&State=' + @state + '&PostalCode=' + @postalcode + '&LicenseKey=' + @key
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sBackupUrl, false
		EXEC sp_OAMethod @obj, 'send'
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
	END
END


Address GeoCoder NodeJS REST Code Snippet
var primaryUrl = 'https://trial.serviceobjects.com/gcr/api.svc/XML/GetBestMatch_V4?Address='+Address+ '&City=' + City +'&State=' + State +'&PostalCode=' + PostalCode +'&LicenseKey=' + LicenseKey;
var backupUrl = 'https://trial.serviceobjects.com/gcr/api.svc/XML/GetBestMatch_V4?Address='+Address+ '&City=' + City +'&State=' + State +'&PostalCode=' + PostalCode +'&LicenseKey=' + LicenseKey;

var req = http.get(primaryUrl, function(res) {
res.setEncoding('utf8');
res.on('data', function (results) {
	var parser = require('xml2js').Parser({explicitArray: false,ignoreAttrs: true});
	parser.parseString(results, function (err, outputs) {
		if (outputs.Location_V4.Error !=  null)
		{
			//Indicates a Fatal error has occured. If this happens, the logic will then failover to the backup url
			if (outputs.Location_V4.Error.Number == "4")
			{
				var backupReq = http.get(backupUrl, function(backupRes) {
					backupRes.setEncoding('utf8');
					backupRes.on('data', function (results) {
							var parser = require('xml2js').Parser({explicitArray: false,ignoreAttrs: true});
							parser.parseString(results, function (err, outputs) {
								console.log("Backup Call Was Used.");
								response.end(JSON.stringify(outputs , null, 3));
							});
						});
					});
			}
			else
			{
				//Will Display the JSON Formatted Error Response here
				response.end(JSON.stringify(outputs, null, 3));
				return;
			}
		}
		else
		{
			//Will Display the JSON Formatted Valid Response here
			response.end(JSON.stringify(outputs, null, 3));
			return;
		}
	});

You can find and download full sample code to our services in various languages (PHP, JAVA and C#) by clicking here. Below is a C# version.

If you are looking for a particular integration not listed in our documentation please contact us at support@serviceobjects.com.

C#
using System;
using System.Collections.Generic;
using System.Data;
using System.IO;
using System.Linq;
using System.Net;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Xml.Serialization;
using GCRResponse;
namespace DOTSGCR_Csh_REST_GetBestMatchV4
{
    public partial class GCRForm : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
        }
        protected void SubmitBtn_Click(object sender, EventArgs e)
        {
            string address, city, state, postalcode, licensekey = null;
            address = Address.Text.Trim();
            city = City.Text.Trim();
            state = State.Text.Trim();
            postalcode = PostalCode.Text.Trim();
            licensekey = LicenseKey.Text.Trim();
            try
            {
                string primaryURL = "https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey;
                string backupURL = "https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey;
                Location_V4 response = httpGet(primaryURL);
                if (response == null || (response.Error != null && response.Error.Number == "4"))
                {
                    response = httpGet(backupURL);
                }
                if (response.Error == null)
                {
                    ProcessValidResponse(response);
                }
                else
                {
                    ProcessErrorResponse(response.Error);
                }
            }
            catch (Exception ex)
            {
                resultsLabel.Text = ex.Message + "<br /><br />" + ex.StackTrace + "<br /><br />" + ex.Source;
                resultsLabel.ForeColor = System.Drawing.Color.Red;
                resultsLabel.Font.Bold = true;
                resultsLabel.Visible = true;
            }
        }
        private static Location_V4 httpGet(string url)
        {
            try
            {
                //NOTE: URL encoding occurs automatically when creating the web request
                HttpWebRequest request = WebRequest.Create(url) as HttpWebRequest;
                request.Timeout = 5000;//timeout for get operation
                using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
                {
                    if (response.StatusCode != HttpStatusCode.OK)
                        throw new Exception(String.Format(
                        "Server error (HTTP {0}: {1}).",
                        response.StatusCode,
                        response.StatusDescription));
                    //parses XML response into the AVIResponse object
                    XmlSerializer serializer = new XmlSerializer(typeof(Location_V4));
                    StreamReader reader = new StreamReader(response.GetResponseStream());
                    Location_V4 output = new Location_V4();
                    output = (Location_V4)serializer.Deserialize(reader);
                    return output;
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        protected void ProcessValidResponse(Location_V4 validResponse)
        {
            DataTable dtoutTable = new DataTable();
            dtoutTable.Columns.Add(new DataColumn("Outputs"));
            dtoutTable.Columns.Add(new DataColumn("Values"));
            dtoutTable.Rows.Add("Level", validResponse.Level);
            dtoutTable.Rows.Add("LevelDescription", validResponse.LevelDescription);
            dtoutTable.Rows.Add("Latitude", validResponse.Latitude);
            dtoutTable.Rows.Add("Longitude", validResponse.Longitude);
            dtoutTable.Rows.Add("Zip", validResponse.Zip);

            //Checks for existence of the InformationComponents array, if it exists it will loop through the values and display them as results.  
            if (validResponse.InformationComponents != null)
            {
                for (int i = 0; i < validResponse.InformationComponents.InformationComponent.Length; i++)
                {
                    dtoutTable.Rows.Add(validResponse.InformationComponents.InformationComponent[i].Name, validResponse.InformationComponents.InformationComponent[i].Value);
                }
            }
            outputGrid.Visible = true;
            resultsLabel.Visible = true;
            resultsLabel.Text = "Web Service Results";
            resultsLabel.Font.Bold = true;
            outputGrid.DataSource = new DataView(dtoutTable);
            outputGrid.DataBind();
        }
        protected void ProcessErrorResponse(Error errorResponse)
        {
            resultsLabel.Text = "Errors found!";
            DataTable dtErrorTable = new DataTable();
            dtErrorTable.Columns.Add(new DataColumn("Outputs"));
            dtErrorTable.Columns.Add(new DataColumn("Values"));
            dtErrorTable.Rows.Add("Desc", errorResponse.Desc);
            dtErrorTable.Rows.Add("Number", errorResponse.Number);
            outputGrid.Visible = true;
            resultsLabel.Visible = true;
            outputGrid.DataSource = new DataView(dtErrorTable);
            outputGrid.DataBind();
        }

    }
}


GetBestMatch_V4 Example Request and Response

URL Request: 
https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address=27+E+Cota+st+Ste+500&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=YourDevKey


XML Response
<Location_V4 xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Level>S</Level>
<LevelDescription>
The address matched exactly at the property location.
</LevelDescription>
<Latitude>34.418014</Latitude>
<Longitude>-119.696477</Longitude>
<Zip>93101-7602</Zip>
<InformationComponents>
<InformationComponent>
<Name>StateFIPS</Name>
<Value>06</Value>
</InformationComponent>
<InformationComponent>
<Name>CountyFIPS</Name>
<Value>083</Value>
</InformationComponent>
<InformationComponent>
<Name>CensusTract</Name>
<Value>0009.00</Value>
</InformationComponent>
<InformationComponent>
<Name>CensusBlock</Name>
<Value>2039</Value>
</InformationComponent>
<InformationComponent>
<Name>CensusGeoID</Name>
<Value>060830009002039</Value>
</InformationComponent>
<InformationComponent>
<Name>CongressCode</Name>
<Value>24</Value>
</InformationComponent>
<InformationComponent>
<Name>SLDUST</Name>
<Value>019</Value>
</InformationComponent>
<InformationComponent>
<Name>SLDLST</Name>
<Value>37</Value>
</InformationComponent>
<InformationComponent>
<Name>ClassFP</Name>
<Value>C1</Value>
</InformationComponent>
</InformationComponents>
<Debug/>
</Location_V4>


URL Request: 
https://trial.serviceobjects.com/GCR/api.svc/JSON/GetBestMatch_V4?Address=27+E+Cota+st+Ste+500&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=YourDevKey


JSON Response
{"Level":"S","LevelDescription":"The address matched exactly at the property location.","Latitude":"34.418014","Longitude":"-119.696477","Zip":"93101-7602","InformationComponents":[{"Name":"StateFIPS","Value":"06"},{"Name":"CountyFIPS","Value":"083"},{"Name":"CensusTract","Value":"0009.00"},{"Name":"CensusBlock","Value":"2039"},{"Name":"CensusGeoID","Value":"060830009002039"},{"Name":"CongressCode","Value":"24"},{"Name":"SLDUST","Value":"019"},{"Name":"SLDLST","Value":"37"},{"Name":"ClassFP","Value":"C1"}],"Debug":""}

GetZipInfo Example Request and Response

URL Request: 
https://trial.serviceobjects.com/GCR/api.svc/xml/GetZipInfo?PostalCode=93101&LicenseKey=yourDevKey


XML Response
<ZipCodeInfo xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<City>SANTA BARBARA</City>
<State>CA</State>
<County>SANTA BARBARA</County>
<AreaCode>805</AreaCode>
<CityAbbreviation>SANTA BARBARA</CityAbbreviation>
<CityType>P</CityType>
<CountyFIPS>083</CountyFIPS>
<StateFIPS>06</StateFIPS>
<TimeZone>8</TimeZone>
<DayLightSavings>Y</DayLightSavings>
<MSA>7480</MSA>
<MD/>
<CBSA>42200</CBSA>
<PMSA/>
<DMA>Santa Barbara - Santa Maria - San Luis Obispo</DMA>
<Latitude>34.419120</Latitude>
<Longitude>-119.703421</Longitude>
<Zip>93101</Zip>
<CityAlternativeName>
<string>SANTA BARBARA</string>
</CityAlternativeName>
</ZipCodeInfo>


URL Request: 
https://trial.serviceobjects.com/GCR/api.svc/json/GetZipInfo?PostalCode=93101&LicenseKey=yourDevKey


JSON Response
{"City":"SANTA BARBARA","State":"CA","County":"SANTA BARBARA","AreaCode":"805","CityAbbreviation":"SANTA BARBARA","CityType":"P","CountyFIPS":"083","StateFIPS":"06","TimeZone":"8","DayLightSavings":"Y","MSA":"7480","MD":"","CBSA":"42200","PMSA":"","DMA":"Santa Barbara - Santa Maria - San Luis Obispo","Latitude":"34.419120","Longitude":"-119.703421","Zip":"93101","CityAlternativeName":["SANTA BARBARA"]}

GetDistanceToWater Example Request and Response

URL Request:
https://trial.serviceobjects.com/GCR/api.svc/xml/GetDistanceToWater?Latitude=34.418014&Longitude=-119.696477&LicenseKey=yourDevKey


XML Response
<DistanceToWaterInfo xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"><DistanceToWater>0.605</DistanceToWater><Latitude>34.418014</Latitude><Longitude>-119.696477</Longitude><WaterLat>34.413116</WaterLat><WaterLon>-119.687683</WaterLon></DistanceToWaterInfo>


URL Request:
https://trial.serviceobjects.com/GCR/api.svc/json/GetDistanceToWater?Latitude=34.418014&Longitude=-119.696477&LicenseKey=yourDevKey


JSON Response
{"DistanceToWater":"0.605","Latitude":"34.418014","Longitude":"-119.696477","WaterLat":"34.413116","WaterLon":"-119.687683"}

GetDistance Example Request and Response

URL Request:
https://trial.serviceobjects.com/GCR/api.svc/xml/GetDistance?FromLatitude=38.8976094&FromLongitude=-77.0367349&ToLatitude=34.418014&ToLongitude=-119.696477&LicenseKey=yourDevKey


XML Response
<DistanceBetweenInfo xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"><MilesBetween>2365.728</MilesBetween><KilometersBetween>3807.27</KilometersBetween><FeetBetween>12491043</FeetBetween></DistanceBetweenInfo>


URL Request:
https://trial.serviceobjects.com/GCR/api.svc/json/GetDistance?FromLatitude=38.8976094&FromLongitude=-77.0367349&ToLatitude=34.418014&ToLongitude=-119.696477&LicenseKey=yourDevKey


JSON Response
{"MilesBetween":"2365.728","KilometersBetween":"3807.27","FeetBetween":"12491043"}

GetReverseLocation Example Request and Response

URL Request:
https://trial.serviceobjects.com/GCR/api.svc/xml/GetReverseLocation?Latitude=34.421556&Longitude=-119.697222&LicenseKey=yourDevKey


XML Response
<ReverseAddress xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Address>118 E DE LA GUERRA ST</Address>
<City>SANTA BARBARA</City>
<State>CA</State>
<Zip>93101</Zip>
<County>SANTA BARBARA</County>
</ReverseAddress>


URL Request:
https://trial.serviceobjects.com/GCR/api.svc/json/GetReverseLocation?Latitude=34.421556&Longitude=-119.697222&LicenseKey=yourDevKey


JSON Response
{"Address":"118 E DE LA GUERRA ST","City":"SANTA BARBARA","State":"CA","Zip":"93101","County":"SANTA BARBARA"}

GetDistanceToWaterByAddress Example Request and Response

URL Request:
https://trial.serviceobjects.com/gcr/api.svc/xml/GetDistanceToWaterByAddress?Address=27+E+Cota+st+Ste+500&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=yourDevKey


XML Response
 <DistanceToWaterInfo xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<DistanceToWater>0.605</DistanceToWater>
<Latitude>34.418014</Latitude>
<Longitude>-119.696477</Longitude>
<WaterLat>34.413116</WaterLat>
<WaterLon>-119.687683</WaterLon>
</DistanceToWaterInfo>


URL Request:
https://trial.serviceobjects.com/gcr/api.svc/xml/GetDistanceToWaterByAddress?Address=27+E+Cota+st+Ste+500&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=yourDevKey


JSON Response
{"DistanceToWater":"0.605","Latitude":"34.418014","Longitude":"-119.696477","WaterLat":"34.413116","WaterLon":"-119.687683"}


List of Operations

GetBestMatch_V4 (Recommended Operation) – Returns the latitude and longitude for a given US Address, along with additional location information. Will attempt to geocode at the property level, zip+4 level, zip+3, zip+2, zip+1, zip, and city/state. (Recommended operation)
GetZipInfo – Returns extensive and various information about a given zip code, including census information and centroid latitude/longitude coordinates. 
GetDistance – Returns an estimated distance between two given locations.
GetDistanceToWater – Returns an estimated distance from a given latitude and longitude to the nearest saltwater.
GetDistanceToWaterByaddress – Returns an estimated distance from a given address to the nearest saltwater.

NOTE: If you are not using any of these operations you may be using the older version of the DOTS Address Geocode US service. Please refere to the developers guide below for information about integration with that service.

DOTS Address Geocode - US - Old

Operation Definitions

This document defines the input, output and behavior of the web service operations in DOTS Address Geocode – US. Each operation has its own unique behavior and output, though some of the operations are very similar.

Important Note!
Every geocoding system is different, and some even use different standards for gathering and calculating coordinates. Because of this, using coordinates from one system may not look to be at the exact location on a different system. For example, Google Maps is a great tool for plotting geocoding coordinates on a viewable map. However, the data used for generating these maps is different than the data that Service Objects uses for generating geocoding coordinates. Thus, some points plotted on Google Maps may not look to be in the precise location; they may look exactly right or look to be several hundred feet away.

You should examine your own business needs first before exploring what DOTS Address Geocode – US can provide. Different operations may be necessary based on the information you have, and the granularity of data you need.

GetBestMatch_V4 (Recommended Operation)

Returns the latitude and longitude for a given US address. This operation will use cascading logic when an exact address match is not found and it will return the next closest level match available. The operation output is designed to allow the service to return new pieces of data as they become available without having to re-integrate.

HTTP GET Request URL Formats

XML:    https://trial.serviceobjects.com/GCR/api.svc/xml/GetBestMatch_V4?Address={ADDRESS}&City={CITY}&State={STATE}&PostalCode={POSTALCODE}&LicenseKey={LICENSEKEY}

JSON:  https://trial.serviceobjects.com/GCR/api.svc/json/GetBestMatch_V4?Address={ADDRESS}&City={CITY}&State={STATE}&PostalCode={POSTALCODE}&LicenseKey={LICENSEKEY}

HTTP POST Request Help Page

XML:    https://trial.serviceobjects.com/gcr/api.svc/xml/help/operations/GetBestMatch_V4_POST

JSON:  https://trial.serviceobjects.com/gcr/api.svc/json/help/operations/GetBestMatch_V4_POST

GetBestMatch_V4 tries to find a match at the most granular level that it can:

  1. Property Match on the street level
  2. Zip + 4 Match
  3. Zip + 3 Match
  4. Zip + 2 Match
  5. Zip + 1 Match
  6. Zip Match
  7. City/State Match (least accurate)

This operation will also return a code indicating the level at which it matched. The codes are:

S – Street Level Property Match
P – Zip plus four match
R – Zip plus three match
T – Zip plus two match
N – Zip plus one match
Z – Zip level match (zip plus zero)
C – City/state match

GetBestMatch_V4 Inputs

Name

Type

Description

Address

String

Address line of the address to geocode. For example, "123 Main Street".

City

String

The city of the address to geocode. For example, "New York". The city isn't required, but if one is not provided, the Zip code is required.

State

String

The state of the address to geocode. For example, "NY". This does not need to be contracted, full state names will work as well.The state isn't required, but if one is not provided, the Zip code is required.

PostalCode

String

The zip code of the address to geocode. A zip code isn't required, but if one is not provided, the City and State are required.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address/address-geocode-us

GetBestMatch_V4 Outputs

Name

Type

Values

Description

Level

String

Varies

The level code at which the
address matched. See above for a listing of possible outputs.

LevelDescriptionStringVariesAn explicit description of the level code, described above.

Latitude

String

Decimal Number 

The latitude of the given address.
A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point.

Longitude

String

Decimal Number

The longitude of the given address.
A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point. 

Zip

String

Varies

The corrected zip plus four of the given address.

InformationComponents


InformationComponent array or NULLVariesA name-value pair collection containing additional information about the location. See the InformationComponent table and the list of Components for more details.

InformationComponent

NameTypeValuesDescription
NameStringVariesThe component name of the Name-Value pair. Possible examples are "CountyFIPS", "CensusTract" "CensusGeoID"
ValueStringVariesThe component value of the Name-Value pair.

Current List of Components

NameTypeValuesDescription
StateFIPSString2 Digit NumberState FIPS(Federal Information Processing Standard) code; used to
uniquely identity states .
CountyFIPSString3 Digit NumberCounty FIPS(Federal Information Processing Standard) code; used to
uniquely identify counties across the US.
CensusTractString6 Digit
Decimal Number
The census tract of the given address.
A census tract is a statistical subdivision of a county.
CensusBlockString4 Digit NumberThe census block of the given address.
A block is the smallest geographic unit used by the US Census.
CensusGeoIDString15 Digit NumberA Census based geographic identification code that uniquely identifies a geographic statistical area.
ClassFPStringAlpha-NumericA code that defines the current class of the geographic location.
CongressCodeStringVariesThe congressional district number.
SLDUSTStringVariesCurrent state legislative district upper (senate) chamber code.
SLDLSTStringVariesCurrent state legislative district lower (house) chamber code
PlaceNameStringVaries

The name of the place that the coordinates are associated with. Most commonly the name of a municipality, city, town, village or community.

NOTICE: For street level property matches the place name will reflect the name of the area where the exact coordinates reside. Coordinates for some unincorporated areas lie outside of known city/community boundaries. In this case the place name will reflect the name of the place that the address is associated with, which is most commonly derived from USPS postal data.

IsUnincorporatedStringVaries

Indicates if the coordinates are for an unincorporated area. Only appears for street level property matches (S).

1 - Indicates that the coordinates fall within the boundaries of a known unincorporated area.
2 - Indicates that the coordinates fall outside of the boundaries of a known area.

Current List of ClassFP Codes

ClassFP CodeClass Code DescriptionAssociated Geographic Entity
C1An active incorporated place that does not serve as a county subdivision equivalentEconomic Census Place, Incorporated Place
C2An active incorporated place that is legally coextensive with a county subdivision but treated as independent of any county subdivisionCounty Subdivision, Economic Census Place, Incorporated Place
C3Consolidated CityConsolidated City
C4Alternate official common name for an incorporated placeLocality Point
C5An active incorporated place that is independent of any county subdivision and serves as a county subdivision equivalentCounty Subdivision, Economic Census Place, Incorporated Place
C6An active incorporated place that partially is independent of any county subdivision and serves as a county subdivision equivalent or partially coextensive with a county subdivision but treated as independent of any county subdivisionIncorporated Place
C7An incorporated place that is independent of any countyCounty or Equivalent Feature, County Subdivision, Economic Census Place, Incorporated Place
C8The balance of a consolidated city excluding the separately incorporated place(s) within that consolidated governmentEconomic Census Place, Incorporated Place
C9An inactive or nonfunctioning incorporated placeEconomic Census Place, Incorporated Place
M1A military or other defense installation that is not entirely within a census designated placeLocality Point, Military Installation
M2A military or other defense installation entirely within a placeCensus Designated Place, Economic Census Place, Military Installation
U1A census designated place with an official federally recognized nameCensus Designated Place, Economic Census Place
U2A census designated place without an official federally recognized nameCensus Designated Place, Economic Census Place


GetZipInfo

This operation provides valuable information about a specific zip code. Included are many demographics codes that many users find valuable for tracking customers and statistical analysis.

GetZipInfo Inputs

Name

Type

Description

Zip

String

The zip for which to find demographic data.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address/address-geocode-us


GetZipInfo Outputs

Name

Type

Values

Description

City

String

Varies

The city of the given zip
code. Alternate city names are
given below.

State

String

Varies

The state of the given zip code.

County

String

Varies

The county of the given zip code.

AreaCode

String

Varies

The area code of the given zip code.

CityAbbreviation

String

Varies

A common abbreviation of
the city name of the given zip code.

CityType

String

N, P, U, B,
A, C, S, K

The city type of the given zip code. The city
type of the given zip code. The code refers
to the type of postal station in a given zip
code. See table below for descriptions
for each of the codes.

CountyFIPS

String

Number

County FIPS(Federal
Information Processing Standard)
code; used to uniquely identify
counties across the US.

StateFIPS

String

Number

State FIPS(Federal Information
Processing Standard) code;
used to uniquely identity states .

TimeZone

String

Number

The number of hours offset from
GMT. 5 = Eastern time zone.

DayLightSavings

String

Y or N

Whether the given zip code
observes Day Light Savings time.

MSA

String

Varies

The Metropolitan Statistical Area Code.
Used to uniquely identify a geographic area
with a relatively high population density at
its core.

MD

String

Varies

The Metropolitan District Code.

CBSA

String

Varies

The Core Based Statistical Area Code.
A code used to identify an urban center
of at least 10,000 people and adjacent
areas that are socioeconomically tied to
the urban center. 

PMSA

String

Varies

The Primary Metropolitan Statistical Area
code. Used to uniquely identify areas
that are part of a larger urban center. 

DMA

String

Varies

The Designated Market Area code. Used
to uniquely identify a geographic region
that receive the same(or similar) TV and
radio show programs. 

Latitude

String

Number

The latitude centroid of the given
zip code.

Longitude

String

Number

The longitude centroid of
the given zip code.

Zip

String

Varies

The zip code input.

CityAlternativeName

ArrayOfString

Varies

A list of strings that contain
alternate names for the city
of the given zip code.

Error – Desc

String

Varies

If there was an internal
web service error, the
description will be
displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, no longer
used.

CityType Code Definitions
CodeDescription
NNon Postal Community Name: Former Postal Facility 
PPost Office: An official post office branch.
UUrbanization: A postal designation specific to Puerto Rico.
BBranch: A postal facility that is not the main post office and is outside the corporate limits of a city.
AAirport Mail Facility: Facilities through which US mail is flown in and out of a city.
CCommunity Post Office: a contract postal unit providing mail services to small communities.
SStation: A post office that is not the main office for a city but is in corporate city limits.
KBulk Mail Center: Centers that handle bulk mail. Typically commercial, business and advertising mail.


GetDistance

This operation returns an estimate on the number of miles, kilometers and feet between two sets of coordinates.

GetDistance Inputs

Name

Type

Description

FromLatitude

String

The latitude for location A.

FromLongitude

String

The longitude for location A.

ToLatitude

String

The latitude for location B.

ToLongitude

String

The longitude for location B.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address/address-geocode-us

GetDistance Outputs

Name

Type

Value

Description

MilesBetween

String

Decimal Number

An estimate on the number of miles between the two coordinate locations.

KilometersBetween

String

Decimal Number

An estimate on the number of kilometers between the two coordinate locations.

FeetBetween

String

Number

An estimate on the number of feet between the two coordinate locations.

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, no longer used.

Miles and kilometers are rounded to the third decimal position.

GetDistanceToWater

Returns an estimated distance from a given latitude and longitude to the nearest saltwater.

GetDistanceToWater Inputs

Name

Type

Description

Latitude

String

The latitude of the location.

Longitude

String

The longitude of the location.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address/address-geocode-us

GetDistanceToWater Outputs

Name

Type

Value

Description

MilesToWater

String

Decimal Number

An estimate on the number of miles between the given location and the nearest saltwater.

Latitude

String

Decimal Number

The latitude of the location.

Longitude

String

Decimal Number

The longitude of the location.

ClosestWaterLatitude

String

Decimal Number

The longitude of the closest saltwater location.

ClosestWaterLongitude

String

Decimal Number

The longitude of the closest saltwater location.

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, no longer used.

GetDistanceToWaterByAddress

Returns an estimated distance from a given address to the nearest saltwater.

GetDistanceToWaterByaddress Input

Name

Type

Description

Address

String

The address of the location.

City

String

The city of the the location.

State

String

The state of the location.

PostalCode

String

The postal code of the location.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address/address-geocode-us

GetDistanceToWaterByaddress Output

Name

Type

Value

Description

MilesToWater

String

Decimal Number

An estimate on the number of miles between the given location and the nearest saltwater.

Latitude

String

Decimal Number

The latitude of the location.

Longitude

String

Decimal Number

The longitude of the location.

ClosestWaterLatitude

String

Decimal Number

The latitude of the closest saltwater location.

ClosestWaterLongitude

String

Decimal Number

The longitude of the closest saltwater location

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, no longer used.


GetReverseLocation

Returns an estimated address for a given latitude and longitude.

GetReverseLocation Inputs

Name

Type

Description

Latitude

String

The latitude of the location.

Longitude

String

The longitude of the location.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address/address-geocode-us

GetReverseLocation Outputs

Name

Type

Value

Description

Address

String

Varies

The estimated address of the given coordinates.

City

String

Varies

The city of the given coordinates.

State

String

Varies

The state of the given coordinates.

Zip

String

Varies

The zip of the given coordinates.

County

String

Varies

The county of the given coordinates.

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, no longer used.


Error Codes

Error codes in DOTS Address Geocode – US are the same for all operations. They are as follows:

Error Code 1 – "Input cannot be less than zero length"

This error means the web service did not get any input. The connection to the service was made, and data was transferred, but no parameters were passed that the service could understand. This error often happens when input is passed to the service with namespaces that the service does not understand. Applying a namespace to any of the parameters (Email or LicenseKey, in this service) will cause this error. Additionally, requests made in the "rpc/encoded" format will cause this error. 


Important Note!
The namespace is not applied to the GetGeoLocation element, it is only present.

Error Code 2 – "Various Descriptions"

This error code appears when various errors occur, but are of the expected nature. Oftentimes, maligned or incomplete input will cause an error 2.

Desc. Code

Description

2

Address field was too long, must be 300 characters or less.

2

Both a latitude and longitude are required.  Please check your input and try again.

2

Invalid Postal Code

2

Latitude and longitude must be numeric.  Please check your input and try again.

2

Latitude and longitude values must be numeric.

2

Latitude and longitude values are required for both locations.

2

Latitude and Longitude were not found for this address.  Please check your input and try again.

2

Latitude values must be between -90 and 90 degrees.

2

Lat/Long value is not near water.

2

Location not found.

2

No address found.

2

Address was not found.

2

Longitude values must be between -180 and 180 degrees.

2

Please enter at least the first 2 letters of the city name.

2

Please input a city and state.

2

Please input a street address.

2

Please input a valid US Zip Code.

2

Please input either zip code or both city and state.

2

Please input zip code plus four.

2

Please input zip code plus four

2

Please input zip code plus two.

2

Please input zip code plus two

2

Please provide a valid license key for this web service.

2

Zip code does not exist.

Error Code 4 – "Various Descriptions"

An error code 4 is a fatal error and it means something has seriously gone wrong. You will never see an error code 4 in a live production environment.

Desc. Code

Description

4

Address could not be found, search timed out.

4

Error initializing service.

4

Internal Error.  Please contact customer service.

Frequently Asked Questions

The Sample Code is Giving Strange Errors or is Crashing!

Most likely, the sample code cannot connect to Service Objects. Many environments will not allow you to connect out on port 80, or will clip out XML data from these requests/responses.

The easiest way to check for this is to open a browser on the machine running the sample code. In your browser, navigate to:
https:/trial.serviceobjects.com/GCR/

Then try to run one of the operations with your trial key. If you get a browser error, or get no data back, then the sample code isn't able to connect either.
Contact your systems administrator to resolve why you are not able to connect to Service Objects.

DOTS Address Geocode – US says it can't find my address!

DOTS Address Geocode – US doesn't know about every address, especially empty lots or new streets. Often, it won't be able to find coordinates to these locations. We do our best to try to improve the data as often as possible. However, it will often be able to match a zip plus four or zip plus two. If it cannot match the exact street location, try the GetBestMatch operation to find how close it can find your data.We are constantly striving to improve our data! DOTS Address Geocode – US may not be able to find your location now, but may in the future as we improve our databases.

DOTS Address Geocode – US is giving coordinates that aren't anywhere near my address!

If you are using the GetBestMatch operation, most likely the service is matching at Zip+4, Zip+2, or Zip level, which return an averaged centroid. The service isn't saying your address is at that location, it is saying the centroid of the zip/+4/+2 is at that location.If DOTS Address Geocode – US is giving what it says is a street-level match that doesn't look like it's at the right location plotted on a map, the issue is most often a stylistic difference between your mapping solution and our data. Because geocoding information is gathered in very different ways, your mapping solution is probably using a very different method than Service Objects does. If the location given is a street-level match, and it's very far away from the target location, please let us know at support@serviceobjects.com

No Census tract or block data was returned for a street level match.

The geocoding service makes use of multiple data sources and the census data is disparate from the coordinate datasets. There is not always a one to one match for the two, so the census tract and block code will not always be available. Cases for this should be very rare overall, but it may be more noticeable for some rural areas or new developments. If you encounter this issue then please contact support@serviceobjects.com with one or more example addresses so that we can investigate.

I'm Not a Programmer. How Do I Use DOTS Address Geocode – US?

Service Objects runs batches for you! A free batch trial is available at https://www.serviceobjects.com/batch/upload.

Conclusion

Service Objects is proud to offer you a free trial of DOTS Address Geocode – US.

Other technical questions or concerns can be directed to support@serviceobjects.com

If you are interested in purchasing DOTS Address Geocode – US, please contact sales@serviceobjects.com.

  
We want to hear from you! We're always looking to improve our developer guides. 
Please email your suggestions to devguidefeedback@serviceobjects.com.

 
  • No labels