Introduction

DOTS Address Geocode – US is a publicly available XML 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.

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:

http://ws.serviceobjects.com/gcr/GeoCoder.asmx

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the “Service Definition” link.):

http://ws.serviceobjects.com/gcr/GeoCoder.asmx?WSDL

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

//Add a service to your application http://trial.serviceobjects.com/gcr/GeoCoder.asmx?WSDL
GCRClient_Primary = new GCRLibraryClient("DOTSGCR");
response = GCRClient_Primary.GetBestMatch_V3(Address, City, State, PostalCode, licenseKey);
         
if (response.Error != null)
{
    //Process Error
}
else
{
    //Process Response     
}

GeoCoder Java Code Snippet

BestMatch_V3Response resp = null;
BestMatchInfo result = null;
Error error = null;
// Create soap request
GCRLibraryLocator locator = new GCRLibraryLocator();
// use ssl
locator.setDOTSGeoCoderEndpointAddress("https://trial.serviceobjects.com/gcr/GeoCoder.asmx");
IGCRLibrary gcr = locator.getDOTSGeoCoder();
DOTSGeoCoderStub soap = (DOTSGeoCoderStub)gcr;
soap.setTimeout(5000);// set timeout
resp = soap.getBestMatch_V3(address, city, state, postalcode, key);
result = resp.getGetBestMatch_V3Result();
error = resp.getError();
if(resp == null || (error != null && error.getTypeCode() == "3"))
{
    throw new Exception();
}
  
//Process Results
if(error == null){
    //DOTS GeoCode Results 
}
//Process Errors
else{
    //DOTS GeoCode Error Results   
}

GeoCoder PHP Code Snippets

<?php
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/gcr/GeoCoder.asmx?WSDL";
 
$params['Address'] = $address;
$params['City'] = $city;
$params['State'] = $state;
$params['PostalCode'] = $postalCode;
$params['LicenseKey'] = $LicenseKey;
 
$soapClient = new SoapClient($wsdlUrl, array( "trace" => 1 ));
$result = $soapClient->GetBestMatch_V3($params);
if (!isset($result->GetBestMatch_V3Result ->Error)) {
    foreach($result->GetBestMatch_V3Result ->BestMatchInfo as $k=>$v) {
        echo $k . ", " . $v;
    }
} else {
    foreach($result->GetBestMatch_V3Result ->Error as $k=>$v) {
        echo $k . ", " . $v;
    }
}
?>

GeoCoder RoR Code Snippets

class RequestsController < ApplicationController
     
    def show
        @request = Request.find(params[:id])
        #Formats inputs into a hash to pass to Soap Client
        #Hash Keys must be named as they are shown here.
        message =   {
                    "Address" => @request.address,
                    "City" => @request.city,
                    "State" => @request.state,
                    "PostalCode" => @request.postalcode,
                    "LicenseKey" => @request.licensekey,
                    }
         
        #Implemented to make the code more readable when accessing the hash        
        @agusresponse = :get_best_match_v3_response
        @agusresult = :get_best_match_v3_result
        @aguserror = :error
        #Set Primary and Backup URLs here as needed
        dotsAGUSPrimary = "http://trial.serviceobjects.com/gcr/GeoCoder.asmx?WSDL"
        dotsAGUSBackup = "http://trial.serviceobjects.com/gcr/GeoCoder.asmx?WSDL"
 
        begin
            #initializes the soap client. The convert request keys global is necessary to receive a response from the service.
            client = Savon.client(  wsdl: dotsAGUSPrimary,
                                    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_v3, 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: dotsAGUSBackup,
                                            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_v3, 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
    end
    private
    def processresults(response)   
            #Processes Error Response from soap Client 
     
            #Processes Valid response from soap client 
         
    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 = 'http://ws.serviceobjects.com/gcr/GeoCoder.asmx?WSDL'
 backupURL = 'http://ws.serviceobjects.com/gcr/GeoCoder.asmx?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_V3(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.
     #Handel response and check for errors
 
 #Tries the backup URL if the primary URL failed
 except:
     try:
         client = Client(backupURL)
         result = client.service.GetBestMatch_V3(Address=mAddress, City=mCity, State=mState, PostalCode=mPostalCode, LicenseKey=mLicenseKey)
     #Handel response and check for errors
 
     #If the backup call failed then this will display an error to the screen
     except:
         Label(swin.window, text='Error').pack()
         print (result)

Address GeoCoder ColdFusion Code Snippet

<!--Makes Request to web service --->
<cfscript>
        try
        {
            if (isDefined("form.Action") AND Action neq "")
            {
                wsresponse = CreateObject("webservice", "http://ws.serviceobjects.com/gcr/GeoCoder.asmx?WSDL");                          
                outputs = wsresponse.getBestMatch_V3("#Address#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
            }
        }
    catch(any Exception){
        try
            {
                if (isDefined("form.Action") AND Action neq "")
                {
                    wsresponse = CreateObject("webservice", "http://ws.serviceobjects.com/gcr/GeoCoder.asmx?WSDL");                          
                    outputs = wsresponse.getBestMatch_V3("#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 AGUS.DOTSGeoCoderSoapClient
    Dim response As AGUS.Location_V3
    response = ws.GetBestMatch_V3(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 AGUS.DOTSGeoCoderSoapClient
        Dim response As AGUS.Location_V3
        response = wsbackup.GetBestMatch_V3(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_V3 result;
try{
wwwServiceobjectsCom.DOTSGeoCoderSoap client = new wwwServiceobjectsCom.DOTSGeoCoderSoap();
result = client.GetBestMatch_V3([Address], [City], [State], [PostalCode], [LicenseKey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsCom.DOTSGeoCoderSoap backupClient = new wwwServiceobjectsCom.DOTSGeoCoderSoap();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'http://trial.serviceobjects.com/AGUS/api.svc/soap';
result = backupClient.GetBestMatch_V3([Address], [City], [State], [PostalCode], [LicenseKey]);
}

Address GeoCoder TSQL Code Snippet

SET @requestBody ='<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
                   '<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">'+
                   '<GetBestMatch_V3 xmlns="https://www.serviceobjects.com/">'+
                   '<Address>' + @address + '</Address>'+
                   '<City>' + @City + '</City>'+
                   '<State>' + @State + '</State>'+
                   '<PostalCode>' + @postalcode + '</PostalCode>'+
                   '<LicenseKey>' + @key + '</LicenseKey>'+
                   '</GetBestMatch_V3>'+
                   '</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', 'http://ws.serviceobjects.com/gcr/GeoCoder.asmx', 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', '"https://www.serviceobjects.com/GetBestMatch_V3"'
    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', 'http://wsbackup.serviceobjects.com/gcr/GeoCoder.asmx', 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', '"https://www.serviceobjects.com/GetBestMatch_V3"'
        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

GeoCoder C# Rest Code Snippet

string mainURL = WEB_SERVICE_PRIMARY_URL + address + "/" + city + "/" + state + "/" + postalCode + "/" + licenseKey + "?format=json";
            string backupURL = WEB_SERVICE_BACKUP_URL + address + "/" + city + "/" + state + "/" + postalCode + "/" + licenseKey + "?format=json";
            try
            {
                result = HttpGet(mainURL);
                //NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP
                if (result == null || (result.Error != null && result.Error.Number == "3"))
                {
                    return HttpGet(backupURL);
                }
                else
                {
                    return result;
                }
            }
            catch (Exception e)
            {   //ERROR IN MAIN URL - USING BACKUP
                return HttpGet(backupURL);
            }

GeoCoder Java Rest Code Snippet

JSONObject results = RestClient(mainURL);  
try {
    if (ErrorMessages != null || (results.getJSONObject("Location_V3").has("Error") && results.getJSONObject("Location_V3").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/GetBestMatch_V3?".rawurlencode($Address)."/".rawurlencode($City)."/".rawurlencode($State)."/".rawurlencode($PostalCode)."/".rawurlencode($LicenseKey)."?format=json";
    // The actual backup url will be provided to you once you purchase a license key
    $backupURL = "https://trial.serviceobjects.com/rest/GCR/api.svc/BestMatchInfo/V3/".rawurlencode($Address)."/".rawurlencode($City)."/".rawurlencode($State)."/".rawurlencode($PostalCode)."/".rawurlencode($LicenseKey)."?format=json";
    // Get cURL resource
    $curl = curl_init();
    curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $URL, CURLOPT_USERAGENT => 'Service Objects Address Validation 3'));
    //Https peer certification validation turned off
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($curl, CURLOPT_CONNECTTIMEOUT_MS, $TIMEOUT); //timeout in milliseconds
    // Send the request & save response to $resp
    $resp = curl_exec($curl);
    $status = curl_getinfo($curl);
    $decoded = json_decode($resp, TRUE);
    if($resp == FALSE ||
    (isset ($decoded['Error']) != NULL &&
    $decoded['Error']['Number'] == 3) ||
    (isset($status) && $status['http_code'] != 200))
    {
        // the first service has failed over
        // create a new request to the backURL
        $curl2 = curl_init();
        curl_setopt_array($curl2, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $backupURL, CURLOPT_USERAGENT => 'Service Objects Email Validation 3'));
        //Https peer certification validation turned off
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($curl2, CURLOPT_CONNECTTIMEOUT_MS, $TIMEOUT); //timeout in milliseconds
        // Send the request & save response to $resp
        $resp = curl_exec($curl2);
        $decoded = json_decode($resp, TRUE);
        if($resp == false)
        {
            echo "<b> Both rest calls failed </b>";
            curl_close($curl2);
            return;
        }
    }

GeoCoder RoR Rest Code Snippets

@request = Request.find(params[:id])
#This sets the default timeout for HTTParty get operation. This must be set in order to use the gem
default_timeout = 10
address = @request.address
city = @request.city
state = @request.state
postalcode = @request.postalcode
licensekey = @request.licensekey
#Set Primary and Backup URLs as needed. This method encodes and standardizes the URI to pass to the REST service.
primaryURL = URI.encode("http://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey)
backupURL = URI.encode("http://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey)
 
#These are set to access the hash that is returned
@agresult ="Location_V3"
@agerror = "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

 primaryURL = 'http://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?'
 backupURL = 'http://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?'
 #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_V3']:
         #loops through the response from the service and prints the values to the screen.
         for key, value in outputs['Location_V3']['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_V3'].pop("@xmlns:xsi", None)
         outputs['Location_V3'].pop("@xmlns:xsd", None)
         outputs['Location_V3'].pop("@xmlns", None)
         for key, value in outputs['Location_V3'].iteritems():
             Label(swin.window, text=str(key) + " : " + str(value)).pack()
 #Attempts to use the backupURL if the call to the primary URL failed
 except:
     try:
         result = requests.get(backupURL, 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_V3']:
             #loops through the response from the service and prints the values to the screen.
             for key, value in outputs['Location_V3']['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_V3'].pop("@xmlns:xsi", None)
             outputs['Location_V3'].pop("@xmlns:xsd", None)
             outputs['Location_V3'].pop("@xmlns", None)
             for key, value in outputs['Location_V3'].iteritems():
                 Label(swin.window, text=str(key) + " : " + str(value)).pack()

Address GeoCoder ColdFusion Code Snippet

<!--Makes Request to web service --->
<cfIf isDefined("form.Action") AND Action neq "" >
    <cftry>
        <cfset primaryURL = "http://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?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 = "http://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?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

Try
    'encodes the URLs for the get Call. Set the primary and back urls as necessary
    Dim primaryurl As String = "http://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey
    Dim backupurl As String = "http://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey
    Dim wsresponse As AGUSResponse.Location_V3 = 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 = "3") Then
        wsresponse = httpGet(backupurl)
    End If
    If wsresponse.[Error] IsNot Nothing Then
        ProcessErrorResponse(wsresponse.[Error])
    Else
        ProcessSuccessfulResponse(wsresponse)
 
    End If
Catch ex As Exception
    'Displays the relevant error mesasge if both backup and primary urls failed.
    StatusLabel.Text = ex.Message
    StatusLabel.Visible = True
End Try

Address GeoCoder TSQL Rest Code Snippet

SET @requestBody ='<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
                   '<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">'+
                   '<GetBestMatch_V3 xmlns="https://www.serviceobjects.com/">'+
                   '<Address>' + @address + '</Address>'+
                   '<City>' + @City + '</City>'+
                   '<State>' + @State + '</State>'+
                   '<PostalCode>' + @postalcode + '</PostalCode>'+
                   '<LicenseKey>' + @key + '</LicenseKey>'+
                   '</GetBestMatch_V3>'+
                   '</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', 'http://ws.serviceobjects.com/gcr/GeoCoder.asmx', 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', '"https://www.serviceobjects.com/GetBestMatch_V3"'
    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', 'http://wsbackup.serviceobjects.com/gcr/GeoCoder.asmx', 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', '"https://www.serviceobjects.com/GetBestMatch_V3"'
        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

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.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Configuration;
using DOTSAddressGeocodeUS.ServiceReference1;
using System.Net;
using System.Runtime.Serialization.Json;
using System.Data;
namespace DOTSAddressGeocodeUS
{
    public partial class GCR_rest : System.Web.UI.Page
    {
        #region STATICS
        static string WEB_SERVICE_PRIMARY_URL; //Included in email from Service Objects
        static string WEB_SERVICE_BACKUP_URL; //Included in email from Service Objects (LIVE customers only)
        static int WEB_SERVICE_REQUEST_TIMEOUT; //In milliseconds
        #endregion
        protected void Page_Load(object sender, EventArgs e)
        {
            try
            {
                ErrorLabel.Visible = false;
                ErrorGrid.Visible = false;
                ResultGrid.Visible = false;
                WEB_SERVICE_REQUEST_TIMEOUT = Convert.ToInt32(ConfigurationManager.AppSettings["WebServiceRequestTimeout"]);
                WEB_SERVICE_PRIMARY_URL = ConfigurationManager.AppSettings["GCR_PRIMARY.GCR"];
                if (string.IsNullOrWhiteSpace(WEB_SERVICE_PRIMARY_URL))
                    throw new System.Exception("Primary URL not set. Check your Web.config file.");
                WEB_SERVICE_BACKUP_URL = ConfigurationManager.AppSettings["GCR_BACKUP.GCR"];
                if (string.IsNullOrWhiteSpace(WEB_SERVICE_BACKUP_URL))
                    throw new System.Exception("Backup URL not set. Check your Web.config file.");
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = "Page load Error: " + ex.Message;
            }
        }
        protected void btn_GO_Click(object sender, EventArgs e)
        {
            string address, city, state, postalCode, licenseKey;
            address    = inputAddress.Text;
            city       = inputCity.Text;
            state      = inputState.Text;
            postalCode = inputPostalCode.Text;
            licenseKey = inputLicenseKey.Text;
            try
            {
                //NOTE: A missing parameter is not allowed
                if (String.IsNullOrWhiteSpace(address))
                    address = " ";
                if (String.IsNullOrWhiteSpace(city))
                    city = " ";
                if (String.IsNullOrWhiteSpace(state))
                    state = " ";
                if (String.IsNullOrWhiteSpace(postalCode))
                    postalCode = " ";
                if (String.IsNullOrWhiteSpace(licenseKey))
                    licenseKey = "yourDevKey";
                BestMatch_V3Response response = MakeRequest(address, city, state, postalCode, licenseKey);
                ProcessResponse(response);
            }
            catch (Exception ex)
            {
                ErrorLabel.Text = ex.Message;
                ErrorLabel.Visible = true;
            }
        }
        //Creates URL and requests response from service
        private static BestMatch_V3Response MakeRequest(string address, string city, string state, string postalCode, string licenseKey)
        {
            /*
            * Due to RFC compliance, the use of URL Paths has character limitations. 
            * Certain characters are invalid and cause HTTP Errors; these characters 
            * include #, /, ?, as well as some high bit characters. 
            *
            * If you suspect that this may be an issue for you then it is recommended to change your
            * request from the URL path parameter format to the query string parameter format. 
            * Example: 
            *     FROM {data}/{data2}/{key}?format=json 
            *     TO parameter1={data1}&parameter2={data2}&licensekey={key}
            * Another alternative is to use HTTP Post instead of HTTP Get.
            */
            BestMatch_V3Response result = null;
            string mainURL = WEB_SERVICE_PRIMARY_URL + address + "/" + city + "/" + state + "/" + postalCode + "/" + licenseKey + "?format=json";
            string backupURL = WEB_SERVICE_BACKUP_URL + address + "/" + city + "/" + state + "/" + postalCode + "/" + licenseKey + "?format=json";
            try
            {
                result = HttpGet(mainURL);
                //NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP
                if (result == null || (result.Error != null && result.Error.Number == "3"))
                {
                    return HttpGet(backupURL);
                }
                else
                {
                    return result;
                }
            }
            catch (Exception e)
            {   //ERROR IN MAIN URL - USING BACKUP
                return HttpGet(backupURL);
            }
        }
        //HTTP Get Method and parse into user-defined object
        private static BestMatch_V3Response HttpGet(string requestUrl)
        {
            try
            {
                //NOTE: URL encoding occurs automatically when creating the web request
                HttpWebRequest request = WebRequest.Create(requestUrl) as HttpWebRequest;
                request.Timeout = WEB_SERVICE_REQUEST_TIMEOUT;//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));
                    //parse response
                    DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(BestMatch_V3Response));
                    object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
                    BestMatch_V3Response jsonResponse = objResponse as BestMatch_V3Response;
                    return jsonResponse;
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process the returned user-defined object
        private void ProcessResponse(BestMatch_V3Response response)
        {
            try
            {
                //processing result
                if (response.Error == null)
                {
                    ProcessResult(response);
                }
                //processing error
                else
                {
                    ProcessError(response.Error);
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process and display the result values
        private void ProcessResult(BestMatch_V3Response result)
        {
            try
            {
                DataTable dtProvider = new DataTable();
                dtProvider.Columns.Add(new DataColumn("Output", typeof(string)));
                dtProvider.Columns.Add(new DataColumn("Values", typeof(string)));
                dtProvider.Rows.Add("Latitude", result.BestMatchInfo.Latitude);
                dtProvider.Rows.Add("Longitude", result.BestMatchInfo.Longitude);
                dtProvider.Rows.Add("Zip", result.BestMatchInfo.Zip);
                dtProvider.Rows.Add("Tract", result.BestMatchInfo.Tract);
                dtProvider.Rows.Add("Block", result.BestMatchInfo.Block);
                dtProvider.Rows.Add("Level", result.BestMatchInfo.Level);
                dtProvider.Rows.Add("LevelDescription", result.BestMatchInfo.LevelDescription);
                dtProvider.Rows.Add("StateFIPS", result.BestMatchInfo.StateFIPS);
                dtProvider.Rows.Add("CountyFIPS", result.BestMatchInfo.CountyFIPS);
                dtProvider.Rows.Add("Debug", result.BestMatchInfo.Debug);
                ResultGrid.Visible = true;
                ErrorGrid.Visible = false;
                ResultGrid.DataSource = new DataView(dtProvider);
                ResultGrid.DataBind();
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process and display the error values
        private void ProcessError(Error error)
        {
            try
            {
                DataTable dtError = new DataTable();
                //A case statement is used here because it is often useful to do different
                //things depeneding on which general type of error occurs.
                //Handle the errors according to your production needs.
                switch (System.Convert.ToInt32(error.Number))
                {
                    case 1:
                        //Authorization Error
                        break;
                    case 2:
                        //User Input Error
                        break;
                    case 4:
                        //Domain Specific Error
                        break;
                    default:
                        //default (error code 3) Service Objects Fatal Error Error
                        break;
                }
                dtError.Columns.Add(new DataColumn("Output", typeof(string)));
                dtError.Columns.Add(new DataColumn("Values", typeof(string)));
                dtError.Rows.Add("Desc", error.Desc);
                dtError.Rows.Add("Number", error.Number);
                dtError.Rows.Add("Location", error.Location);
                ResultGrid.Visible = false;
                ErrorGrid.Visible = true;
                ErrorGrid.DataSource = new DataView(dtError);
                ErrorGrid.DataBind();
            }
            catch (Exception e)
            {
                throw e;
            }
        }
    }
}

GetZipInfo Example Request and Response

URL Request: 
https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetZipInfo?PostalCode=93117&LicenseKey=yourDevKey

XML Response

<ZipInfoResponse xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <ZipInfo>
    <City>GOLETA</City>
    <State>CA</State>
    <County>SANTA BARBARA</County>
    <AreaCode>805</AreaCode>
    <CityAbbreviation>GAVIOTA</CityAbbreviation>
    <CityType>N</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.511736</Latitude>
    <Longitude>-120.062476</Longitude>
    <Zip>93117</Zip>
    <CityAlternativeName xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      <a:string>SANTA BARBARA</a:string>
      <a:string>ISLA VISTA</a:string>
      <a:string>GAVIOTA</a:string>
      <a:string>GOLETA</a:string>
 
    </CityAlternativeName>
 </ZipInfo>
</ZipInfoResponse>

GetGeoLocation Example Request and Response

<GeoLocationResponse xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <GeoLocationInfo>
    <Latitude>34.418014</Latitude>
    <Longitude>-119.696477</Longitude>
    <Zip>93101-7603</Zip>
    <Tract>0009.00</Tract>
    <Block>2039</Block>
    <Level>S</Level>
 </GeoLocationInfo>
</GeoLocationResponse>

GetDistanceToWaterByAddress Example Request and Response

URL Request:
https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetDistanceToWaterByAddress?Address=27+E+Cota&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=yourDevKey

XML Response

<WaterLocationResponse xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <WaterLocationInfo>
    <MilesToWater>0.605</MilesToWater>
    <Latitude>34.418014</Latitude>
    <Longitude>-119.696477</Longitude>
    <ClosestWaterLatitude>34.413116</ClosestWaterLatitude>
    <ClosestWaterLongitude>-119.687683</ClosestWaterLongitude>
 </WaterLocationInfo>
</WaterLocationResponse>

GetLocationByCityState Example Request and Response

URL Request:
https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetGeoLocationByCityState?City=Santa+Barbara&State=CA&LicenseKey=yourDevKey

XML Response

<GeoLocationResponse xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <GeoLocationInfo>
    <Latitude>34.4488</Latitude>
    <Longitude>-119.733</Longitude>
 </GeoLocationInfo>
</GeoLocationResponse>

GetDistance Example Request and Response

URL Request:
https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetDistance?FromLatitude=37.668044&FromLongitude=-121.769621&ToLatitude=34.414106&ToLongitude=-119.860635&LicenseKey=yourDevKey

XML Response

<DistanceResponse xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <DistanceInfo>
    <MilesBetween>249.096</MilesBetween>
    <KilometersBetween>400.881</KilometersBetween>
    <FeetBetween>1315227</FeetBetween>
 </DistanceInfo>
</DistanceResponse>

GetBestMatch_V3 Example Request and Response

URL Request:
https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=27+E+Cota&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=yourDevKey

XML Response

<BestMatch_V3Response xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <BestMatchInfo>
    <Latitude>34.418014</Latitude>
    <Longitude>-119.696477</Longitude>
    <Zip>93101-7603</Zip>
    <Tract>0009.00</Tract>
    <Block>2039</Block>
    <Level>S</Level>
    <LevelDescription>
        The address matched exactly at the property location.
    </LevelDescription>
    <StateFIPS>06</StateFIPS>
    <CountyFIPS>083</CountyFIPS>
    <Debug/>
 </BestMatchInfo>
</BestMatch_V3Response>

GetGeoLocationByZipPlusTwo Example Request and Response

URL Request:
https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetGeoLocationByZipPlusTwo?PostalCode=9311723&LicenseKey=yourDevKey

XML Response

<GeoLocationResponse xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <GeoLocationInfo>
    <Latitude>34.442159</Latitude>
    <Longitude>-119.823612</Longitude>
 </GeoLocationInfo>
</GeoLocationResponse>

GetReverseLocation Example Request and Response

URL Request:
https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetReverseLocation?Latitude=34.421556&Longitude=-119.697222&LicenseKey=yourDevKey

XML Response

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

GetGeoLocationByZipPlusFour Example Request and Response

URL Request:
https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetGeoLocationByZipPlusFour?PostalCode=931172323&LicenseKey=yourDevKey

XML Response

<GeoLocationResponse xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <GeoLocationInfo>
    <Latitude>34.442415</Latitude>
    <Longitude>-119.821683</Longitude>
 </GeoLocationInfo>
</GeoLocationResponse>

GetDistanceToWater Example Request and Response

URL Request:
https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetDistanceToWater?Latitude=34.421556&Longitude=-119.697222&LicenseKey=yourDevKey

XML Response

<WaterLocationResponse xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <WaterLocationInfo>
    <MilesToWater>0.787</MilesToWater>
    <Latitude>34.421556</Latitude>
    <Longitude>-119.697222</Longitude>
    <ClosestWaterLatitude>34.413002</ClosestWaterLatitude>
    <ClosestWaterLongitude>-119.688103</ClosestWaterLongitude>
 </WaterLocationInfo>
</WaterLocationResponse>

GetGeoLocationWorldwide Example Request and Response

URL Request:
https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetGeoLocationWorldwide?City=Santa+Barbara&Region=&Country=USA&LicenseKey=yourDevKey

XML Response

<ArrayOfGeoLocationWorldwideResponse xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <GeoLocationWorldwideResponse>
    <GeoLocationWorldwideInfo>
     <City>Santa Barbara</City>
     <Region>California</Region>
     <Country>United States</Country>
     <Latitude>34.4119</Latitude>
     <Longitude>-119.7280</Longitude>
    </GeoLocationWorldwideInfo>
 </GeoLocationWorldwideResponse>
</ArrayOfGeoLocationWorldwideResponse>

List of Operations

GetBestMatch_V3 – Returns latitude, longitude, tract, block, state FIPS, county FIPS, and ZIP+4 if available. Will attempt to geocode at the property level, zip+4 level, zip+3, zip+2, zip+1, zip, and city/state. (Recommended operation)
GetbestMatch_V4 – Returns the latitude and longitude for a given US Address, along with additional location information. NOTICE: This operation is currently restricted to trial (beta) use only.
GetGeoLocationByZipPlusFour – Returns latitude/longitude location information for a given zip plus four (99999-9999)
GetGeoLocationByZipPlusTwo – Returns latitude/longitude location information for a given zip plus two (99999-99)
GetGeoLocationByCityState – Returns latitude/longitude location information for a given city and state. Returns data as close to the city centroid as possible.
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.
GetGeolocationWorldwide – Returns Lat Lon information for a given worldwide city. Multiple matches can be filtered by country or region(state, province etc.)
GetReverseLocation – Returns an estimated address for a given latitude and longitude. 
GetGeoLocation – (Deprecated: use GetBestMatch_V3)
GetBestMatch – (Deprecated: use GetBestMatch_V3)
GetBestMatch_V2 – (Deprecated: use GetBestMatch_V3)

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_V3

This operation is identical to GetBestMatch_V2, but additionally returns state and county FIPS codes.

GetBestMatch_V3 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_V3 Inputs

NameTypeDescription
AddressStringAddress line of the address to geocode.
For example, “123 Main Street”.
CityStringThe 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.
StateStringThe 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.
PostalCodeStringThe 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.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetBestMatch_V3 Outputs

NameTypeValuesDescription
LatitudeStringNumberThe latitude of the given
address.
LongitudeStringNumberThe longitude of the given
address.
TractStringNumberThe census tract of the given address.
A census tract is a statistical subdivision of a county.
BlockStringNumberThe census block of the given address.
A block is the smallest geographic unit used by the US Census.
ZipStringVariesThe corrected zip plus four of
the given address.
LevelStringVaries, see
above
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.
StateFIPSStringTwo digitsState FIPS(Federal Information Processing Standard) code; used to
uniquely identity states .
CountyFIPSStringThree digitsCounty FIPS(Federal Information Processing Standard) code; used to
uniquely identify counties across the US.
Error – DescStringVariesIf there was an internal web
service error, the description will
be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

GetBestMatch_V4

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.

This operation is currently restricted to Trial (beta) use only.

HTTP GET Request URL Formats

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

JSON:  http://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:    http://trial.serviceobjects.com/gcr/api.svc/xml/help/operations/GetBestMatch_V4_POST

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

SOAP URL

WSDL:  http://trial.serviceobjects.com/gcr/soap.svc?wsdl

Service XML Request Help Page

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

Service JSON Request Help Page

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

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

NameTypeDescription
AddressStringAddress line of the address to geocode.
For example, “123 Main Street”.
CityStringThe 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.
StateStringThe 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.
PostalCodeStringThe 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.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetBestMatch_V4 Outputs

NameTypeValuesDescription
LevelStringVariesThe level code at which the
address matched. See above for a listing of possible outputs.
LevelDescriptionStringVariesAn explicit description of the level code, described above.
LatitudeStringDecimal NumberThe 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.
LongitudeStringDecimal NumberThe 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. 
ZipStringVariesThe corrected zip plus four of the given address.
InformationComponentsInformationComponent 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.
SLDUSTStringVariesCurrent state legislative district upper (senate) chamber code.
SLDLSTStringVariesCurrent state legislative district lower (house) chamber code

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

GetGeoLocationByZipPlusFour

This operation is almost exactly like GetGeoLocation, but rather than geocoding given a specific address, DOTS Address Geocode – US will geocode given a zip plus four. The coordinates given are an average centroid of a given zip plus four region and oftentimes match precisely to the street location.

GetGeoLocationByZipPlusFour Inputs

NameTypeDescription
ZipStringThe zip plus four to geocode.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetGeoLocationByZipPlusFour Outputs

NameTypeValuesDescription
LatitudeStringNumberThe latitude of the given zip plus
four.
LongitudeStringNumberThe longitude of the given zip
plus four.
Error – DescStringVariesIf there was an internal web
service error, the description will
be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

GetGeoLocationByZipPlusTwo

This operation is almost exactly like GetGeoLocationByZipPlusFour, but instead uses only a Zip plus two. If a zip plus four is provided, this operation will geocode only using the subset zip plus two.

GetGeoLocationByZipPlusTwo Inputs

NameTypeDescription
ZipStringThe zip plus four to geocode.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetGeoLocationByZipPlusTwo Outputs

NameTypeValuesDescription
LatitudeStringNumberThe latitude of the given zip plus
four.
LongitudeStringNumberThe longitude of the given zip
plus four.
Error – DescStringVariesIf there was an internal web
service error, the description will
be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

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

NameTypeDescription
ZipStringThe zip plus four to geocode.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetZipInfo Outputs

NameTypeValuesDescription
CityStringVariesThe city of the given zip
code. Alternate city names are
given below.
StateStringVariesThe state of the given zip code.
CountyStringVariesThe county of the given zip code.
AreaCodeStringVariesThe area code of the given zip code.
CityAbbreviationStringVariesA common abbreviation of
the city name of the given zip code.
CityTypeStringN, 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.
CountyFIPSStringNumberCounty FIPS(Federal
Information Processing Standard)
code; used to uniquely identify
counties across the US.
StateFIPSStringNumberState FIPS(Federal Information
Processing Standard) code;
used to uniquely identity states .
TimeZoneStringNumberThe number of hours offset from
GMT. 5 = Eastern time zone.
DayLightSavingsStringY or NWhether the given zip code
observes Day Light Savings time.
MSAStringVariesThe Metropolitan Statistical Area Code.
Used to uniquely identify a geographic area
with a relatively high population density at
its core.
MDStringVariesThe Metropolitan District Code.
CBSAStringVariesThe 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. 
PMSAStringVariesThe Primary Metropolitan Statistical Area
code. Used to uniquely identify areas
that are part of a larger urban center. 
DMAStringVariesThe Designated Market Area code. Used
to uniquely identify a geographic region
that receive the same(or similar) TV and
radio show programs. 
LatitudeStringNumberThe latitude centroid of the given
zip code.
LongitudeStringNumberThe longitude centroid of
the given zip code.
ZipStringVariesThe zip code input.
CityAlternativeNameArrayOfStringVariesA list of strings that contain
alternate names for the city
of the given zip code.
Error – DescStringVariesIf there was an internal
web service error, the
description will be
displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, 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.

GetGeoLocationByCityState

This operation is almost exactly like GetGeoLocationByZipPlusFour, but rather than geocoding given a zip plus four, DOTS Address Geocode – US will geocode given a city and state. The coordinates given are an average centroid of the entire city.

GetGeoLocationByCityState Inputs

NameTypeDescription
CityStringThe city to geocode.
StateStringThe State to geocode.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetGeoLocationByCityState Outputs

NameTypeValuesDescription
LatitudeStringNumberThe latitude of the given zip plus
four.
LongitudeStringNumberThe longitude of the given zip
plus four.
Error – DescStringVariesIf there was an internal web
service error, the description will
be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

GetDistance

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

GetDistance Inputs

NameTypeDescription
FromLatitudeStringThe latitude for location A.
FromLongitudeStringThe longitude for location A.
ToLatitudeStringThe latitude for location B.
ToLongitudeStringThe longitude for location B.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com
Accepts 9 digit long decimal degree coordinates with a precision of up to 6 decimal places.

GetDistance Outputs

NameTypeValuesDescription
MilesBetweenStringDecimal NumberAn estimate on the number of miles between the two coordinate locations.
KilometersBetweenStringDecimal NumberAn estimate on the number of kilometers between the two coordinate locations.
FeetBetweenStringNumberAn estimate on the number of feet between the two coordinate locations.
Error – DescStringVariesIf there was an internal web service error, the description will be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, 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

NameTypeDescription
LatitudeStringThe latitude of the location.
LongitudeStringThe longitude of the location.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetDistanceToWater Outputs

NameTypeValuesDescription
MilesToWaterStringDecimal NumberAn estimate on the number of miles between the given location and the nearest saltwater.
LatitudeStringDecimal NumberThe latitude of the location.
LongitudeStringDecimal NumberThe longitude of the location.
ClosestWaterLatitudeStringDecimal NumberThe longitude of the closest saltwater location.
ClosestWaterLongitudeStringDecimal NumberThe longitude of the closest saltwater location.
Error – DescStringVariesIf there was an internal web service error, the description will be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

GetDistanceToWaterByaddress

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

GetDistanceToWaterByaddress Input

NameTypeDescription
AddressStringThe address of the location.
CityStringThe city of the the location.
StateStringThe state of the location.
PostalCodeStringThe postal code of the location.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetDistanceToWaterByaddress Output

NameTypeValuesDescription
MilesToWaterStringDecimal NumberAn estimate on the number of miles between the given location and the nearest saltwater.
LatitudeStringDecimal NumberThe latitude of the location.
LongitudeStringDecimal NumberThe longitude of the location.
ClosestWaterLatitudeStringDecimal NumberThe Latitude of the closest saltwater location.
ClosestWaterLongitudeStringDecimal NumberThe longitude of the closest saltwater location.
Error – DescStringVariesIf there was an internal web service error, the description will be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

GetGeoLocationWorldwide

Returns Lat Lon information for a given worldwide city. Multiple matches can be filtered by country or region(state, province etc.)

GetGeoLocationWorldwide Inputs

NameTypeDescription
CityStringThe city to geocode. This is a required input parameter.
RegionStringThe region (state, province etc.) of the city to geocode.
CountryStringThe Country of the city to geocode.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetGeoLocationWorldwide Outputs

This operation is capable of returning multiple matches. All matches are contained in a GetGeoLocationWorldwideResult object. The GetGeoLocationWorldwideResult object returns a list of GeocodeCityWorldwideInfo objects.

GeocodeCityWorldwideInfo

NameTypeValueDescription
CityStringVariesThe name of the city.
RegionStringVariesThe region associated with the city.
CountryStringVariesThe country associated with the city.
LatitudeStringDecimal NumberThe latitude centroid of the city.
LongitudeStringDecimal NumberThe longitude centroid of the city.
Error – DescStringVariesIf there was an internal web service error, the description will be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

GetReverseLocation

Returns an estimated address for a given latitude and longitude.

GetReverseLocation Inputs

NameTypeDescription
LatitudeStringThe latitude of the location.
LongitudeStringThe longitude of the location.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetReverseLocation Outputs

NameTypeValuesDescription
AddressStringVariesThe estimated address of the given coordinates.
CityStringVariesThe city of the given coordinates.
StateStringVariesThe state of the given coordinates.
ZipStringVariesThe zip of the given coordinates.
CountyStringVariesThe county of the given coordinates.
Error – DescStringVariesIf there was an internal web service error, the description will be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

GetGeoLocation

This is the basic operation for finding the latitude/longitude coordinates of an address. This operation takes a standard US address (Address, City, State, Zip) and will try to find the exact street location’s coordinates. It cannot always find the location, especially when it comes to empty lots or new construction areas.

This operation will also return census tract and block, if available, for the given address. This data is valuable for tracking demographics and statistical analysis. If a valid zip code is found for the given address, it will be returned as well.First, DOTS Address Geocode – US will attempt to correct and normalize the address to make it more likely to geocode properly. You don’t need to worry about fixing the address before sending it to DOTS Address Geocode – US, unless you want to filter out invalid or non-existent addresses beforehand. This operation requires the Address value, and either City and State, or the Zip code. Providing all inputs is recommended.

GetGeoLocation Inputs

NameTypeDescription
AddressStringAddress line of the address to geocode.
For example, “123 Main Street”.
CityStringThe 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.
StateStringThe 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.
ZipStringThe 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.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetGeoLocation Outputs

NameTypeValuesDescription
LatitudeStringNumberThe latitude of the given
address.
LongitudeStringNumberThe longitude of the given
address.
TractStringNumberThe census tract of the given address.
A census tract is a statistical subdivision
of a county.
BlockStringNumber The census block of the given address.
A block is the smallest geographic unit
used by the US Census.
ZipStringVariesThe corrected zip plus four of
the given address.
Error – DescStringVariesIf there was an internal web
service error, the description will
be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

GetBestMatch 

Often, users want to geocode as best we can – if we can’t match an address exactly at the street level, they’d like it at the zip plus four level, and if not at zip plus four, then at zip plus two, and so on.

The GetBestMatch operation does exactly that; it tries to find a match at the most granular level that it can:

  1. Street Level Match (most accurate; property-level match)
  2. Zip + 4 Match
  3. Zip + 2 Match
  4. Zip Match
  5. City/State Match(least accurate)

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

S – Street/exact match (property-level match)
P – Zip plus four match
T – Zip plus two match
Z – Zip level match (zip plus zero)
C – City/state match

GetBestMatch Inputs

NameTypeDescription
AddressStringAddress line of the address to geocode.
For example, “123 Main Street”.
CityStringThe 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.
StateStringThe 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.
ZipStringThe 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.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetBestMatch Outputs

NameTypeValuesDescription
LatitudeStringNumberThe latitude of the given
address.
LongitudeStringNumberThe longitude of the given
address.
TractStringNumberThe census tract of the given
address.
BlockStringNumberThe census block of the given
address.
ZipStringVariesThe corrected zip plus four of
the given address.
LevelStringVaries, see
above
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.
Error – DescStringVariesIf there was an internal web
service error, the description will
be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

GetBestMatch_V2

This operation is identical to GetBestMatch, but additionally will attempt to match at the Zip + 3 and Zip + 1 levels.

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

  1. Street Level Match (most accurate; property-level match)
  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 the level at which it matched. The codes are:

S – Street/exact match (property-level 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_V2 Inputs

NameTypeDescription
AddressStringAddress line of the address to geocode.
For example, “123 Main Street”.
CityStringThe 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.
StateStringThe 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.
ZipStringThe 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.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
http://www.serviceobjects.com

GetBestMatch_V2 Outputs

NameTypeValuesDescription
LatitudeStringNumberThe latitude of the given
address.
LongitudeStringNumberThe longitude of the given
address.
TractStringNumberThe census tract of the given
address.
BlockStringNumberThe census block of the given
address.
ZipStringVariesThe corrected zip plus four of
the given address.
LevelStringVaries, see
above
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.
Error – DescStringVariesIf there was an internal web
service error, the description will
be displayed here.
Error – NumberString“1”, “2”, “4”See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, 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. The only namespace that should appear in any element is the http://www.serviceobjects.com namespace on the root ValidateEmail element as so:

<GetGeoLocation xmlns=”http: //www. serviceobjects .com/”>

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. CodeDescription
2Address field was too long, must be 300 characters or less.
2Both a latitude and longitude are required.  Please check your input and try again.
2Invalid Postal Code
2Latitude and longitude must be numeric.  Please check your input and try again.
2Latitude and longitude values must be numeric.
2Latitude and longitude values are required for both locations.
2Latitude and Longitude were not found for this address.  Please check your input and try again.
2Latitude values must be between -90 and 90 degrees.
2Lat/Long value is not near water.
2Location not found.
2No address found.
2Address was not found.
2Longitude values must be between -180 and 180 degrees.
2Please enter at least the first 2 letters of the city name.
2Please input a city and state.
2Please input a street address.
2Please input a valid US Zip Code.
2Please input either zip code or both city and state.
2Please input zip code plus four.
2Please input zip code plus four.
2Please input zip code plus two.
2Please input zip code plus two.
2Please provide a valid license key for this web service.
2Zip 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. CodeDescription
4Address could not be found, search timed out.
4Error initializing service.
4Internal Error.  Please contact customer service.

Frequently Asked Questions

Which Operation Should You Use? GetGeoLocation or GetBestMatch_V3?

Picking which operation you want to use should be decided carefully. Depending on your environment and needs, you will need to use different operations for their corresponding strengths.If you always need precise location coordinates, then stick with GetGeoLocation. The other operations won’t give you the detail you’re looking for. If your application does not require precise coordinate location, but will work with general-area mapping, GetBestMatch_V3 will give you a much higher match count than GetGeoLocation alone. The best suggestion is to try out each of the operations to find the data you need.

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:
http://trial.serviceobjects.com/gcr/GeoCoder.asmx

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.

Do you also provide a RESTful interface?

Yes we do! For more information on how to use our RESTful interface go here DOTS Address Geocode – US – REST.

Conclusion

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

Sign up today for a free trial at:
https://www.serviceobjects.com/products/address/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.

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