Introduction

DOTS Address Plus US (AV-Plus) is a publicly available XML web service that provides comprehensive address validation, latitude/longitude and demographic metadata information about a physical US address. The service provides validated and parsed address information, geocoding information, and demographic information, such as the census tract, block or other statistical codes. AV-Plus can provide instant address validation/geocoding data to websites or enhancement to contact lists. The extensive demographic statistics help you identify and enhance your service to your best customers.

This is a deprecated service. New clients and existing clients that would be interested in switching should look here:

DOTS Address Insight – US

This Developers Guide exists for informational purposes for active clients that use the older service.

Integration

Integrating AV-Plus 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/

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 tricky business logic. Web services are too large of 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. AV-Plus 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/ap/AddressPlus.asmx

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/ap/AddressPlus.asmx?WSDL

Important Note!

Note that 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 AV-Plus, 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 only one operation available, which is described in detail later on.

Code Snippets

Address Validation Plus C# Code Snippet

//Add a service to your application https://trial.serviceobjects.com/ap/AddressPlus.asmx
APClient_Primary = new APLibraryClient("DOTSAP");
response = APClient_Primary.GetAddressPlus(Address, Address2, City, State, PostalCode, licenseKey);
         
if (response.Error != null)
{
    //Process Error
}
else
{
    //Process Response     
}

Address Validation Plus Java Code Snippet

AddressPlusResponse resp = null;
AddressPlusInfo result = null;
Error error = null;
// Create soap request
APLibraryLocator locator = new APLibraryLocator();
// use ssl
locator.setDOTSDOTSAddressPlusEndpointAddress("https://trial.serviceobjects.com/rest/ap/api.svc/soap");
IAPLibrary ap = locator.getDOTSAddressPlus();
DOTSAddressPlusStub soap = (DOTSAddressPlusStub)ap;
soap.setTimeout(5000);// set timeout
resp = soap.getAddressPlus(Address, Address2, City, State, PostalCode, licenseKey);
result = resp.getAddressPlusInfo();
error = resp.getError();
if(resp == null || (error != null && error.getTypeCode() == "3"))
{
    throw new Exception();
}
  
//Process Results
if(error == null){
    //DOTS Address Validation Plus Results 
}
//Process Errors
else{
    //DOTS Address Validation Plus Error
}

Address Validation Plus PHP Code Snippets

<?php
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/ap/AddressPlus.asmx?WSDL";
 
$params['Address'] = $Address;
$params['Address2'] = $Address2;
$params['City'] = $City;
$params['State'] = $State;
$params['PostalCode'] = $PostalCode;
$params['LicenseKey'] = $LicenseKey;
 
$soapClient = new SoapClient($wsdlUrl, array( "trace" => 1 ));
$result = $soapClient->GetAddressPlus($params);
if (!isset($result->GetAddressPlusResult ->Error)) {
    foreach($result->GetAddressPlusResult ->AddressPlusInfo as $k=>$v) {
        echo $k . ", " . $v;
    }
} else {
    foreach($result->GetAddressPlusResult ->Error as $k=>$v) {
        echo $k . ", " . $v;
    }
}
?>

Address Validation Plus 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,
                    "Address2" => @request.address2,
                    "City" => @request.city,
                    "State" => @request.state,
                    "PostalCode" => @request.postalcode,
                    "LicenseKey" => @request.licensekey,
                    }
         
        #Implemented to make the code more readable when accessing the hash        
        @avpresponse = :get_address_plus_response
        @avpresult = :get_address_plus_result
        @avperror = :error
 
        #Set Primary and Backup URLs here as needed
        dotsAVPPrimary = "https://trial.serviceobjects.com/ap/AddressPlus.asmx?WSDL"
        dotsAVPBackup = "https://trial.serviceobjects.com/ap/AddressPlus.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: dotsAVPPrimary)
            #Calls the operation with given inptus and converts response to a hash.
            response = client.call(:get_address_plus, message: message).to_hash
 
            #Checks to see what results came back from the service
            processresults(response)           
             
        #If an error occurs set the response to the backupclient call to the operation and converts response to a hash.
            response = backupclient.call(:get_address_plus, message: message).to_hash
            processresults(response)
 
            #If the backup url failed, this will display the error received from the server
            end
        end
    end
    private
    def processresults(response)   
            #Processes Error Response from soap Client     
            #Processes Valid response from soap client 
    end
end

Address Validation Plus US Python Code Snippet

mAddress = Address.get()
if mAddress is None or mAddress == "":
    mAddress = " "
mAddress2 = Address2.get()
if mAddress2 is None or mAddress2 == "":
    mAddress2 = " "
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/ap/AddressPlus.asmx?WSDL'
backupURL = 'https://trial.serviceobjects.com/ap/AddressPlus.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.GetAddressPlus(Address=mAddress, Address2=mAddress2, City=mCity, State=mState, PostalCode=mPostalCode, LicenseKey=mLicenseKey)
    #Handel response and check for errors
#Tries the backup URL if the primary URL failed
except:
    try:
        client = Client(backupURL)
        result = client.service.GetAddressPlus(Address=mAddress, Address2=mAddress2, 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 Validation Plus US ColdFusion Code Snippet

<!--Makes Request to web service --->
<cfscript>
        try
        {
            if (isDefined("form.Action") AND Action neq "")
            {
                wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/ap/AddressPlus.asmx?WSDL");                            
                outputs = wsresponse.getAddressPlusWithDPV("#Address#", "#Address2#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
            }
        }
    catch(any Exception){
        try
            {
                if (isDefined("form.Action") AND Action neq "")
                {
                    wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/ap/AddressPlus.asmx?WSDL");                            
                    outputs = wsresponse.getAddressPlusWithDPV("#Address#", "#Address2#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
                }
            }
            catch(any Exception)   
                {
                 writeoutput("An Error Has Occured. Please Reload and try again #Exception.message#");              
                }
        }
</cfscript>

Address Validation Plus US VB Code Snippet

Try
    Dim ws As New AVP.DOTSAddressPlusSoapClient
    Dim response As AVP.AddressPlus
    response = ws.GetAddressPlus(Address.Text, Address2.Text, City.Text, State.Text, PostalCode.Text, LicenseKey.Text)
    If (response.Error Is Nothing) Then
        ProcessValidResponse(response)
    Else
        ProcessErrorResponse(response.Error(0))
    End If
 
Catch er As Exception
    ''Set the Primary and Backup Service References as necessary
    Try
        Dim wsbackup As New AVP.DOTSAddressPlusSoapClient
        Dim response As AVP.AddressPlus
        response = wsbackup.GetAddressPlus(Address.Text, Address2.Text, City.Text, State.Text, PostalCode.Text, LicenseKey.Text)
        If (response.Error Is Nothing) Then
            ProcessValidResponse(response)
        Else
            ProcessErrorResponse(response.Error(0))
        End If
    Catch ex As Exception
        resultsLabel.Visible = True
        resultsLabel.Text = ex.Message
    End Try
End Try

Address Validation Plus US Apex Code Snippet

wwwServiceobjectsCom.AddressPlus result;
try{
wwwServiceobjectsCom.DOTSAddressPlusSoap client = new wwwServiceobjectsCom.DOTSAddressPlusSoap();
result = client.GetAddressPlus([Address], [Address2], [City], [State], [PostalCode], [LicenseKey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsCom.DOTSAddressPlusSoap backupClient = new wwwServiceobjectsCom.DOTSAddressPlusSoap();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'https://trial.serviceobjects.com/AVP/api.svc/soap';
result = backupClient.GetAddressPlus([Address], [Address2], [City], [State], [PostalCode], [LicenseKey]);
}

Address Validation Plus US 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">'+
                   '<GetAddressPlus xmlns="https://www.serviceobjects.com/">'+
                   '<Address>' + @address + '</Address>'+
                   '<Address2>' + @address2 + '</Address2>'+
                   '<City>' + @city + '</City>'+
                   '<State>' + @state + '</State>'+
                   '<PostalCode>' + @postalcode + '</PostalCode>'+
                   '<LicenseKey>' + @key + '</LicenseKey>'+
                   '</GetAddressPlus>'+
                   '</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/ap/AddressPlus.asmx', false
    EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'trial.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/GetAddressPlus"'
    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
    SET @XMLOutput = CONVERT(XML, @response, 2)
     
    --Checks the Response for a fatal error or if null.
    --;WITH XMLNAMESPACES(DEFAULT 'https://www.serviceobjects.com/', 'http://schemas.xmlsoap.org/soap/envelope/' as soap, 'http://www.w3.org/2001/XMLSchema-instance' as xsi, 'http://www.w3.org/2001/XMLSchema' as xsd )
    IF @response IS NULL
    BEGIN
        EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
        EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/ap/AddressPlus.asmx', false
        EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'trial.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/GetAddressPlus"'
        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
        SET @XMLOutput = CONVERT(XML, @response, 2)
        SELECT 'BACK UP CALL WAS USED' as OutputMessage
    END
END

Address Validation Plus US NodeJS Code Snippet

var args = {Address: 'Address',
            Address2: 'Address2',
            City: 'City',
            State: 'State',
            PostalCode: 'PostalCode',
            LicenseKey: 'Your-License-Key'};
soap.createClient(primaryUrl, function(err, client) {
     
    client.GetAddressPlusWithDPV(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://www.serviceobjects.com/docs/dots-address-validation-plus-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.GetAddressPlusWithDPVResult.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.GetAddressPlusWithDPVResult.Error.Number == "4")
                {
                    //The actual backup url will be provided when you purchase a license key
                    var backupUrl = 'https://trial.serviceobjects.com/ap/AddressPlus.asmx?WSDL';
                    soap.createClient(backupUrl, function(failoverErr, backupClient) {
     
                        backupClient.GetAddressPlusWithDPV(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;
            }
        }
    });
});

Address Validation Plus C# Rest Code Snippet

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

Address Validation Plus Java Code Snippet

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

Address Validation Plus PHP Rest Code Snippets

$URL = "https://trial.serviceobjects.com/rest/AP/api.svc/AddressPlusInfo/DPV/".rawurlencode($Address)."/".rawurlencode($Address2)."/".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/AP/api.svc/AddressPlusInfo/DPV/".rawurlencode($Address)."/".rawurlencode($Address2)."/".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 Plus'));
//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']['TypeCode'] == 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 Address Validation Plus'));
    //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;
    }
}

Address Validation Plus 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
      address2 = @request.address2
      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("https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlus?Address=" + address + "&Address2=" + address2 + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey)
      backupURL = URI.encode("https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlus?Address=" + address + "&Address2=" + address2 + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey)
       
      #These are set to access the hash that is returned
      @avpresult ="AddressPlus"
      @avperror = "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 Validation Plus Python Rest Code Snippets

primaryURL = 'https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlus?'
backupURL = 'https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlus?'
#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, 'Address2': mAddress2, '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['AddressPlus']:
        #loops through the response from the service and prints the values to the screen.
        for key, value in outputs['AddressPlus']['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['AddressPlus'].pop("@xmlns:xsi", None)
        outputs['AddressPlus'].pop("@xmlns:xsd", None)
        outputs['AddressPlus'].pop("@xmlns", None)
        for key, value in outputs['AddressPlus'].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['AddressPlus']:
            #loops through the response from the service and prints the values to the screen.
            for key, value in outputs['AddressPlus']['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['AddressPlus'].pop("@xmlns:xsi", None)
            outputs['AddressPlus'].pop("@xmlns:xsd", None)
            outputs['AddressPlus'].pop("@xmlns", None)
            for key, value in outputs['AddressPlus'].iteritems():
                Label(swin.window, text=str(key) + " : " + str(value)).pack()

Address Validation Plus ColdFusion Rest Code Snippets

<cfIf isDefined("form.Action") AND Action neq "" >
    <cftry>
        <cfset primaryURL = "https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlus?Address=#Address#&Address2=#Address2#&City=#City#&State=#State#&PostalCode=##&LicenseKey=#LicenseKey#">
        <cfhttp url="#primaryURL#"
        method="get"
        result="response">
        <cfset outputs = XmlParse(response.FileContent)>
        <cfcatch>
            <cftry>
                <cfset backupURL = "https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlus?Address=#Address#&Address2=#Address2#&City=#City#&State=#State#&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 Validation Plus VB Rest Code Snippets

'encodes the URLs for the get Call. Set the primary and back urls as necessary
Dim primaryurl As String = "https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlus?Address=" + address + "&Address2=" + address2 + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey
Dim backupurl As String = "https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlus?Address=" + address + "&Address2=" + address2 + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey
Dim wsresponse As AVPResponse.AddressPlus = 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

Address Validation Plus TSQL Rest Code Snippets

BEGIN
    SET @sUrl = 'https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlus?Address=' + @address + '&Address2=' + @address2 + '&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/ap/AddressPlus.asmx/GetAddressPlus?Address=' + @address + '&Address2=' + @address2 + '&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 Validation Plus NodeJS Rest Code Snippets

var Address = 'Address';
var Address2 ='Address2';
var City ='City';
var State ='State';
var PostalCode ='PostalCode';
var LicenseKey ='LicenseKey';
//Set backup and primary URL as necessary
var primaryUrl = 'https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlusWithDPV?Address='+Address+'&Address2='+ Address2 + '&City=' + City +'&State=' + State +'&PostalCode=' + PostalCode +'&LicenseKey=' + LicenseKey;
var backupUrl = 'https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlusWithDPV?Address='+Address+'&Address2='+ Address2 + '&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.AddressPlus.Error !=  null)
            {
                //Indicates a Fatal error has occured. If this happens, the logic will then failover to the backup url
                if (outputs.AddressPlus.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.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Configuration;
using System.Net;
using DOTSAddressPlus.ServiceReference1;
using System.Runtime.Serialization.Json;
using System.Data;
namespace DOTSAddressPlus
{
    public partial class AP_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["AP_PRIMARY.AP"];
                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["AP_BACKUP.AP"];
                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 address1, address2, city, state, postalCode, licenseKey;
            address1 = inputAddress1.Text;
            address2 = inputAddress2.Text;
            city = inputCity.Text;
            state = inputState.Text;
            postalCode = inputPostalCode.Text;
            licenseKey = inputLicenseKey.Text;
            try
            {
                //NOTE: A missing parameter is not allowed
                if (String.IsNullOrWhiteSpace(address1))
                    address1 = " ";
                if (String.IsNullOrWhiteSpace(address2))
                    address2 = " ";
                if (String.IsNullOrWhiteSpace(city))
                    city = " ";
                if (String.IsNullOrWhiteSpace(state))
                    state = " ";
                if (String.IsNullOrWhiteSpace(postalCode))
                    postalCode = " ";
                if (String.IsNullOrWhiteSpace(licenseKey))
                    licenseKey = "yourDevKey";
                AddressPlusResponse response = MakeRequest(address1, address2, 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 AddressPlusResponse MakeRequest(string address1, string address2, 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.
            */
            AddressPlusResponse result = null;
            string mainURL = WEB_SERVICE_PRIMARY_URL + address1 + "/" + address2 + "/" + city + "/" + state + "/" + postalCode + "/" + licenseKey + "?format=json";
            string backupURL = WEB_SERVICE_BACKUP_URL + address1 + "/" + address2 + "/" + city + "/" + state + "/" + postalCode + "/" + licenseKey + "?format=json";
            try
            {
                result = HttpGet(mainURL);
                //NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP
                if (result == null || (result.Errors != null && (result.Errors.Where(er => (er.Number == "3")).Count()>0)))
                {
                    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 AddressPlusResponse 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(AddressPlusResponse));
                    object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
                    AddressPlusResponse jsonResponse = objResponse as AddressPlusResponse;
                    return jsonResponse;
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process the returned user-defined object
        private void ProcessResponse(AddressPlusResponse response)
        {
            try
            {
                //processing result
                if (response.Errors == null)
                {
                    ProcessResult(response);
                }
                //processing error
                else
                {
                    ProcessError(response.Errors);
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process and display the result values
        private void ProcessResult(AddressPlusResponse 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("Address", result.AddressPlusInfo.Address);
                dtProvider.Rows.Add("City", result.AddressPlusInfo.City);
                dtProvider.Rows.Add("State", result.AddressPlusInfo.State);
                dtProvider.Rows.Add("Zip", result.AddressPlusInfo.Zip);
                dtProvider.Rows.Add("Address2", result.AddressPlusInfo.Address2);
                dtProvider.Rows.Add("BarcodeDigits", result.AddressPlusInfo.BarcodeDigits);
                dtProvider.Rows.Add("CarrierRoute", result.AddressPlusInfo.CarrierRoute);
                dtProvider.Rows.Add("CongressCode", result.AddressPlusInfo.CongressCode);
                dtProvider.Rows.Add("CountyCode", result.AddressPlusInfo.CountyCode);
                dtProvider.Rows.Add("CountyName", result.AddressPlusInfo.CountyName);
                dtProvider.Rows.Add("Fragment", result.AddressPlusInfo.Fragment);
                dtProvider.Rows.Add("FragmentHouse", result.AddressPlusInfo.FragmentHouse);
                dtProvider.Rows.Add("FragmentPMBNumber", result.AddressPlusInfo.FragmentPMBNumber);
                dtProvider.Rows.Add("FragmentPMBPrefix", result.AddressPlusInfo.FragmentPMBPrefix);
                dtProvider.Rows.Add("FragmentPostDir", result.AddressPlusInfo.FragmentPostDir);
                dtProvider.Rows.Add("FragmentPreDir", result.AddressPlusInfo.FragmentPreDir);
                dtProvider.Rows.Add("FragmentStreet", result.AddressPlusInfo.FragmentStreet);
                dtProvider.Rows.Add("FragmentSuffix", result.AddressPlusInfo.FragmentSuffix);
                dtProvider.Rows.Add("FragmentUnit", result.AddressPlusInfo.FragmentUnit);
                dtProvider.Rows.Add("DPV", result.AddressPlusInfo.DPV);
                dtProvider.Rows.Add("DPVDesc", result.AddressPlusInfo.DPVDesc);
                dtProvider.Rows.Add("DPVNotes", result.AddressPlusInfo.DPVNotes);
                dtProvider.Rows.Add("DPVNotesDesc", result.AddressPlusInfo.DPCNotesDesc);
                dtProvider.Rows.Add("Corrections", result.AddressPlusInfo.Corrections);
                dtProvider.Rows.Add("CorrectionDesc", result.AddressPlusInfo.CorrectionDesc);
                dtProvider.Rows.Add("Latitude", result.AddressPlusInfo.Latitude);
                dtProvider.Rows.Add("Longitude", result.AddressPlusInfo.Longitude);
                dtProvider.Rows.Add("Tract", result.AddressPlusInfo.Tract);
                dtProvider.Rows.Add("Block", result.AddressPlusInfo.Block);
                dtProvider.Rows.Add("AreaCode", result.AddressPlusInfo.AreaCode);
                dtProvider.Rows.Add("CityAbbreviation", result.AddressPlusInfo.CityAbbreviation);
                dtProvider.Rows.Add("CityType", result.AddressPlusInfo.CityType);
                dtProvider.Rows.Add("CountyFIPS", result.AddressPlusInfo.CountyFIPS);
                dtProvider.Rows.Add("StateFIPS", result.AddressPlusInfo.StateFIPS);
                dtProvider.Rows.Add("TimeZone", result.AddressPlusInfo.TimeZone);
                dtProvider.Rows.Add("DayLightSavings", result.AddressPlusInfo.DayLightSavings);
                dtProvider.Rows.Add("MSA", result.AddressPlusInfo.MSA);
                dtProvider.Rows.Add("MD", result.AddressPlusInfo.MD);
                dtProvider.Rows.Add("CBSA", result.AddressPlusInfo.CBSA);
                dtProvider.Rows.Add("PMSA", result.AddressPlusInfo.PMSA);
                dtProvider.Rows.Add("DMA", result.AddressPlusInfo.DMA);
                dtProvider.Rows.Add("ZipLatitude", result.AddressPlusInfo.ZipLatitude);
                dtProvider.Rows.Add("ZipLongitude", result.AddressPlusInfo.ZipLongitude);
                dtProvider.Rows.Add("MedianIncome2000", result.AddressPlusInfo.MedianIncome2000);
                dtProvider.Rows.Add("MedianIncome2005", result.AddressPlusInfo.MedianIncome2005);
                dtProvider.Rows.Add("AreaHouseholdIncome", result.AddressPlusInfo.AreaHouseholdIncome);
                dtProvider.Rows.Add("CountyHouseholdIncome", result.AddressPlusInfo.CountyHouseholdIncome);
                dtProvider.Rows.Add("StateHouseholdIncome", result.AddressPlusInfo.StatehouseholdIncome);
                dtProvider.Rows.Add("GeocodeLevel", result.AddressPlusInfo.GeocodeLevel);
                dtProvider.Rows.Add("GeocodeLevelDescription", result.AddressPlusInfo.GeocodeLevelDescription);
                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[] errors)
        {
            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.
                //This service has the potential to return 2 error objects
                switch (System.Convert.ToInt32(errors[0].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)));
                foreach (Error err in errors)
                {
                    dtError.Rows.Add("Desc", err.Desc);
                    dtError.Rows.Add("Number", err.Number);
                    dtError.Rows.Add("Location", err.Location);
                }
                ResultGrid.Visible = false;
                ErrorGrid.Visible = true;
                ErrorGrid.DataSource = new DataView(dtError);
                ErrorGrid.DataBind();
            }
            catch (Exception e)
            {
                throw e;
            }
        }
    }
}

GetAddressPlusNoCensus Example Request and Response

URL Request: 
https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlusNoCensus?Address=27+E+Cota&Address2=&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=yourDevKey

XML Response

<AddressPlusResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <AddressPlusInfo>
    <Address>27 E Cota St</Address>
    <City>Santa Barbara</City>
    <State>CA</State>
    <Zip>93101-7603</Zip>
    <Address2/>
    <BarcodeDigits>931017603992</BarcodeDigits>
    <CarrierRoute>C006</CarrierRoute>
    <CongressCode>24</CongressCode>
    <CountyCode>083</CountyCode>
    <CountyName>Santa Barbara</CountyName>
    <Fragment/>
    <FragmentHouse>27</FragmentHouse>
    <FragmentPMBNumber/>
    <FragmentPMBPrefix/>
    <FragmentPostDir/>
    <FragmentPreDir>E</FragmentPreDir>
    <FragmentStreet>Cota</FragmentStreet>
    <FragmentSuffix>St</FragmentSuffix>
    <FragmentUnit/>
    <Latitude>34.418014</Latitude>
    <Longitude>-119.696477</Longitude>
    <Tract>0009.00</Tract>
    <Block>2039</Block>
    <GeocodeLevel>S</GeocodeLevel>
    <GeocodeLevelDescription>
        The address matched exactly at the street location.
    </GeocodeLevelDescription>
 </AddressPlusInfo>
</AddressPlusResponse>

GetAddressPlusWithDPV Example Request and Response

URL Request:
https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlusWithDPV?Address=27+E+Cota&Address2=&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=yourDevKey

XML Response

<AddressPlusResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <AddressPlusInfo>
    <Address>27 E Cota St</Address>
    <City>Santa Barbara</City>
    <State>CA</State>
    <Zip>93101-7603</Zip>
    <Address2/>
    <BarcodeDigits>931017603992</BarcodeDigits>
    <CarrierRoute>C006</CarrierRoute>
    <CongressCode>24</CongressCode>
    <CountyCode>083</CountyCode>
    <CountyName>Santa Barbara</CountyName>
    <Fragment/>
    <FragmentHouse>27</FragmentHouse>
    <FragmentPMBNumber/>
    <FragmentPMBPrefix/>
    <FragmentPostDir/>
    <FragmentPreDir>E</FragmentPreDir>
    <FragmentStreet>Cota</FragmentStreet>
    <FragmentSuffix>St</FragmentSuffix>
    <FragmentUnit/>
    <DPV>4</DPV>
    <DPVDesc>
        The input record is a valid mailing address, but is missing the apartment or rural route box number
    </DPVDesc>
    <DPVNotes>1, 8</DPVNotes>
    <DPVNotesDesc>
        The input address matched the ZIP+4 record, The input address matched a DPV highrise but a secondary was not input
    </DPVNotesDesc>
    <Corrections>39</Corrections>
    <CorrectionsDesc>ZIP changed</CorrectionsDesc>
    <Latitude>34.418014</Latitude>
    <Longitude>-119.696477</Longitude>
    <Tract>0009.00</Tract>
    <Block>2039</Block>
    <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>
    <ZipLatitude>34.419120</ZipLatitude>
    <ZipLongitude>-119.703421</ZipLongitude>
    <MedianIncome2000>54042</MedianIncome2000>
    <MedianIncome2005>63700</MedianIncome2005>
    <AreaHouseholdIncome>51021</AreaHouseholdIncome>
    <CountyHouseholdIncome>72310.0</CountyHouseholdIncome>
    <StateHouseholdIncome>69758.0</StateHouseholdIncome>
    <GeocodeLevel>S</GeocodeLevel>
    <GeocodeLevelDescription>
        The address matched exactly at the street location.
    </GeocodeLevelDescription>
 </AddressPlusInfo>
</AddressPlusResponse>

GetAddressPlus Example Request and Response:

URL Request:
https://trial.serviceobjects.com/ap/AddressPlus.asmx/GetAddressPlus?Address=27+E+Cota&Address2=&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=yourDevKey

XML Response

<AddressPlusResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <AddressPlusInfo>
    <Address>27 E Cota St</Address>
    <City>Santa Barbara</City>
    <State>CA</State>
    <Zip>93101-7603</Zip>
    <Address2/>
    <BarcodeDigits>931017603992</BarcodeDigits>
    <CarrierRoute>C006</CarrierRoute>
    <CongressCode>24</CongressCode>
    <CountyCode>083</CountyCode>
    <CountyName>Santa Barbara</CountyName>
    <Fragment/>
    <FragmentHouse>27</FragmentHouse>
    <FragmentPMBNumber/>
    <FragmentPMBPrefix/>
    <FragmentPostDir/>
    <FragmentPreDir>E</FragmentPreDir>
    <FragmentStreet>Cota</FragmentStreet>
    <FragmentSuffix>St</FragmentSuffix>
    <FragmentUnit/>
    <DPV>4</DPV>
    <DPVDesc>
        The input record is a valid mailing address, but is missing the apartment or rural route box number
    </DPVDesc>
    <DPVNotes>1, 8</DPVNotes>
    <DPVNotesDesc>
        The input address matched the ZIP+4 record, The input address matched a DPV highrise but a secondary was not input
    </DPVNotesDesc>
    <Corrections>39</Corrections>
    <CorrectionsDesc>ZIP changed</CorrectionsDesc>
    <Latitude>34.418014</Latitude>
    <Longitude>-119.696477</Longitude>
    <Tract>0009.00</Tract>
    <Block>2039</Block>
    <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>
    <ZipLatitude>34.419120</ZipLatitude>
    <ZipLongitude>-119.703421</ZipLongitude>
    <MedianIncome2000>54042</MedianIncome2000>
    <MedianIncome2005>63700</MedianIncome2005>
    <AreaHouseholdIncome>51021</AreaHouseholdIncome>
    <CountyHouseholdIncome>72310.0</CountyHouseholdIncome>
    <StateHouseholdIncome>69758.0</StateHouseholdIncome>
    <GeocodeLevel>S</GeocodeLevel>
    <GeocodeLevelDescription>
        The address matched exactly at the street location.
    </GeocodeLevelDescription>
 </AddressPlusInfo>
</AddressPlusResponse>

List of Operations

Operation Definitions

This document defines the input, output and behavior of the web service operations in AVP.  Each operation has its own unique behavior and output, although 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.

GetAddressPlusWithDPV(Recommended Operation)

This operation is the same as GetAddressPlus with addition 6 fields of DPV data.

GetAddressPlusWithDPV Inputs

NameTypeDescription
AddressStringAddress line of the address to validate.
For example, “123 Main Street”.
Address2StringSecond address line of the address to validate. Usually ignored.
CityStringThe city of the address to validate.
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 validate. 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 validate. 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:
https://www.serviceobjects.com/address-insight/

GetAddressPlusWithDPV Outputs

NameTypeValuesDescription
AddressStringVariesThe corrected Address line 1.
CityStringVariesThe corrected city name.
StateStringVariesThe corrected state name.
ZipStringVariesThe corrected zip code + 4.
Address2StringVariesThe corrected Address line 2.
BarcodeDigitsStringVariesThe post office delivery barcode digits.
CarrierRouteStringEmptyNo longer supported.
CongressCodeStringVariesThe congress code of the given address.
CountyCodeStringVariesThe county code of the given address. Same as the CountyFIPS. This code is used to uniquely identify counties on a national level. 
CountyNameStringVariesThe name of the county in which the given address lies.
FragmentStringVariesThe parsed “Fragment” box, apartment or unit number. Same as FragmentPMBNumber.
FragmentHouseStringVariesThe parsed house number of the given address.
FragmentPMBNumberStringVariesThe parsed apartment, box, unit, etc. number of the given address.
FragmentPMBPrefixStringVariesThe parsed type of the apartment, box, unit, etc. For example, “APT” or “BOX”.
FragmentPostDirStringVariesThe parsed post-directional of the address’s street. “West” in “North Main St West”.
FragmentPreDirStringVariesThe parsed pre-directional of the address’s street. “North” in “North Main St West”.
FragmentStreetStringVariesThe parsed name of the street in the given address. “Main” in “North Main St West”.
FragmentSuffixStringVariesThe parsed suffix of the street in the given address. “St” in “North Main St West”.
LatitudeStringNumberThe closest geocoding latitude match of the given address. See “GeocodeLevel” below for different levels of matching.
DPV*String1-8Number that correlates to a DPV(Delivery Point Validation)
result. An indicator displaying whether or not the address
is recognized as deliverable by the USPS.
DPVDesc*StringVariesExplains DPV result.
DPVNotes*String1-14Number that correlates to DPV notes description.
DPVNotesDesc*StringVariesDetails about the DPV result.
Corrections*String1-41Number that correlates to a Corrections Description.
CorrectionsDesc*StringVariesDetails about the Correction.
LongitudeStringNumberThe closest geocoding longitude match of the given address. See “GeocodeLevel” below for different levels of matching.
TractStringNumberThe Census Tract of the given address.
BlockStringNumberThe Census Block of the given address.
AreaCodeStringVariesThe phone Area Code of the given address.
CityAbbreviationStringVariesA common alternate contraction of the city’s name.
CityTypeStringN, P, U, B,
A, C, S, K
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.
CountyFIPSStringVariesThe county code of the address’s county.
StateFIPSStringVariesThe state code of the address’s state.
TimeZoneStringNumberThe number of hours offset from GMT. 5 = Eastern time zone, 8 = Pacific time zone, etc.
DayLightSavingsStringY or NWhether the given zip code observes DayLight 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. 
ZipLatitudeStringNumberThe Zip centroid’s latitude.
ZipLongitudeStringNumberThe Zip centroid’s longitude.
MedianIncome2000StringNumberThe median income for the zip code in 2000.
MedianIncome2005StringNumberThe median income for the zip code in 2005.
AreaHouseholdIncomeStringNumberThe average income for the immediate area in 2000.
CountyHouseholdIncomeStringNumberThe average income for the county in 2000.
StateHouseholdIncomeStringNumberThe average income for the state in 2000.
GeocodeLevelStringS, P, T,
Z, C
The closest level of geocoding that matched.
S = Street
P = Zip + 4
T = Zip + 2
Z = Zip
C = City & State
GeocodeLevelDescriptionStringVariesA verbose description of GeocodeLevel.
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.

*See tables below for possible values.

DPV Codes

DPVDPV Desc
1Yes, the input record is a valid mailing address
2No, the input record is not in the DPV database of valid mailing addresses
3The apartment or rural route box number is not valid, although the house number or rural route is valid
4The input record is a valid mailing address, but is missing the apartment or rural route box number
5Internal error. Please contact customer service
6Internal error. Please contact customer service
7Internal error. Please contact customer service
8Internal error. Please contact customer service
DPVNotesDPVNotesDesc:
1The input address matched the ZIP+4 record
2The input address did not match the ZIP+4 record
3The input address matched the DPV record
4The input address primary matched DPV but the secondary did not
5The input address is a military APO/FPO address
6The input address is a general delivery address
7The input address is a building name, and the primary is missing
8The input address matched a DPV high-rise but a secondary was not input
9The input address primary is invalid
10The input address is missing a PO box, rural route, or highway contract box number
11The input address (PO box, rural route, or highway contract) primary is invalid
12The input address specified a PMB and matched a CMRA
13The input address did not include a PMB and matched a CMRA
14The input address matched and retained a unique ZIP code
15SuiteLink did not find Suite or Unit data to append to the address
19Household or residence indicated by RDI
23Highrise apartment/office building address
CorrectionsCorrectionDesc
1State not found
2City not found
3Street not found
4Address not found
5Uncomputable +4 range
6+4 unavailable
7Multiple streets match
8Multiple addresses match
9Time ran out
10Output too long
11Unused and reserved
12Company phonetic match used
13First company match used
14State determined from city
15State determined from ZIP
16City phonetic match used
17City determined from ZIP
18Acceptable city name used
19Street phonetic match used
20Predirection dropped
21Predirection added
22Suffix dropped
23Suffix added
24Postdirection dropped
25Postdirection added
26Predirection standardized
27Street standardized
28Suffix standardized
29Postdirection standardized
30Street missing
31Alternate address used
32Unit standardized
33Unit missing
34Unit not found
35Unit unverified
36Rural box not found
37Leftovers found
38ZIP not found
39ZIP changed
40+4 changed
41Route changed
42Suite or Unit data appended using SuiteLink
43Directional or Suffix is either missing or unused

GetAddressPlus

This operation takes a standard US address (Address, Address2, City, State, Zip) and will try to find the all of the information that it can about the given address. It cannot always find all information, especially when it comes to empty lots or new construction areas.

Some of the return values may seem cryptic, but they’re merely US census demographics and city planning codes.

This operation requires the Address value, and either City and State, or the Zip code. Address2 is entirely optional, and will most likely not play into any of the information generated.

GetAddressPlus Inputs

NameTypeDescription
AddressStringAddress line of the address to validate.
For example, “123 Main Street”.
Address2StringSecond address line of the address to validate. Usually ignored.
CityStringThe city of the address to validate.
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 validate. 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 validate. 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: https://www.serviceobjects.com/address-insight/

GetAddressPlus Outputs

NameTypeValueDescription
AddressStringVariesThe corrected Address line 1.
CityStringVariesThe corrected city name.
StateStringVariesThe corrected state name.
ZipStringVariesThe corrected zip code + 4.
Address2StringVariesThe corrected Address line 2.
BarcodeDigitsStringVariesThe post office delivery barcode digits.
CarrierRouteStringEmptyNo longer supported.
CongressCodeStringVariesThe congress code of the given address.
CountyCodeStringVariesThe county code of the given address. Same as the CountyFIPS. This code is used to uniquely identify counties on a national level. 
CountyNameStringVariesThe name of the county in which the given address lies.
FragmentStringVariesThe parsed “Fragment” box, apartment or unit number. Same as FragmentPMBNumber.
FragmentHouseStringVariesThe parsed house number of the given address.
FragmentPMBNumberStringVariesThe parsed apartment, box, unit, etc. number of the given address.
FragmentPMBPrefixStringVariesThe parsed type of the apartment, box, unit, etc. For example, “APT” or “BOX”.
FragmentPostDirStringVariesThe parsed post-directional of the address’s street. “West” in “North Main St West”.
FragmentPreDirStringVariesThe parsed pre-directional of the address’s street. “North” in “North Main St West”.
FragmentStreetStringVariesThe parsed name of the street in the given address. “Main” in “North Main St West”.
FragmentSuffixStringVariesThe parsed suffix of the street in the given address. “St” in “North Main St West”.
LatitudeStringNumberThe closest geocoding latitude match of the given address. See “GeocodeLevel” below for different levels of matching.
DPV*String1-8Number that correlates to a DPV(Delivery Point Validation) result. An indicator displaying whether or not the address is recognized as deliverable by the USPS.
DPVDesc*StringVariesExplains DPV result.
DPVNotes*String1-14Number that correlates to DPV notes description.
DPVNotesDesc*StringVariesDetails about the DPV result.
Corrections*String1-41Number that correlates to a Corrections Description.
CorrectionsDesc*StringVariesDetails about the Correction.
LongitudeStringNumberThe closest geocoding longitude match of the given address. See “GeocodeLevel” below for different levels of matching.
TractStringNumberThe Census Tract of the given address.
BlockStringNumberThe Census Block of the given address.
AreaCodeStringVariesThe phone Area Code of the given address.
CityAbbreviationStringVariesA common alternate contraction of the city’s name.
CityTypeStringN, P, U, B, A, C, S, KThe 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.
CountyFIPSStringVariesThe county code of the address’s county.
StateFIPSStringVariesThe state code of the address’s state.
TimeZoneStringNumberThe number of hours offset from GMT. 5 = Eastern time zone, 8 = Pacific time zone, etc.
DayLightSavingsStringY or NWhether the given zip code observes DayLight 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. 
ZipLatitudeStringNumberThe Zip centroid’s latitude.
ZipLongitudeStringNumberThe Zip centroid’s longitude.
MedianIncome2000StringNumberThe median income for the zip code in 2000.
MedianIncome2005StringNumberThe median income for the zip code in 2005.
AreaHouseholdIncomeStringNumberThe average income for the immediate area in 2000.
CountyHouseholdIncomeStringNumberThe average income for the county in 2000.
StateHouseholdIncomeStringNumberThe average income for the state in 2000.
GeocodeLevelStringS, P, T, Z, CThe closest level of geocoding that matched.
S = Street
P = Zip + 4
T = Zip + 2
Z = Zip
C = City & State
GeocodeLevelDescriptionStringVariesA verbose description of GeocodeLevel.
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: Official post office branch.
UUrbanization: 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 the 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.

GetAddressPlusNoCensus

This operation is the same as GetAddressPlus without returning census data.

GetAddressPlusNoCensus Inputs

Same as GetAddressPlus

GetAddressPlusNoCensus Outputs

Same as GetAddressPlus except does not return the following:

AreaCode
CityAbbreviation
CityType
CountyFIPS
StateFIPS
TimeZone
DayLightSavings
MSA
MD
CBSA
PMSA
DMA
ZipLatitude
ZipLongitude
MedianIncome2000
MedianIncome2005
AreaHouseholdIncome
CountyHouseholdIncome
StateHouseholdIncome

Error Codes

Error codes in AV-Plus are very simple. 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 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 “https://www.serviceobjects.com” namespace on the root GetAddressPlus element as so:

<GetAddressPlus xmlns="https://www.serviceobjects.com/">

Important Note!

The namespace is not applied to the GetAddressPlus 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. Since the Address Validation Plus service is comprised of our standalone Geocoding service that provides the latitude and longitude values for an address and our stand alone Address Validation service that validates and standardizes the input address for mailing purposes, it can return multiple errors from both of those services. These two stand alone services have different data sources, and on occasion one of the services can return an error and the other service can return a valid response.  To help identify the different error responses the table below has the various errors that will be returned by the AVP service, their origin and description of what the errors mean.

NumberDescService Error OriginDescription
2Address not foundAddress ValidationMajor issue with address that doesn’t fit known USPS special case scenarios.
2Street not foundAddress ValidationStreet name not found for general area (city/state or zip)
2Please input a valid address. Address ValidationThe basic address information was not present(i.e. Address and Zip or Address and City/State
2Street number or box number out of rangeAddress ValidationStreet name found in area, but the given primary number is not valid for that street
2Zip code does not exist. Geo CoderThe entered zip code does exist in the Geocode data.
2Please input a valid US Zip Code. Geo CoderThe entered zip code was not a valid zip code format or the zip code did not exist
2Location not found. Geo CoderNo city/state or zip code location could be found for this data
2State not found Geo CoderThe entered state was not found the Geocoder data.
2Address was not found.Geo CoderThe entered address was not found in the Geocoder data
2Address and Address2 fields were too long. Together, they must be 100 characters or less. Address ValidationThe entered Address1 and Address2 fields were too long and deemed not to be valid
2Address field was too long, must be 100 characters or less.Address ValidationThe entered Address1 field was too long and deemed not to be valid.

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.

Frequently Asked Questions

Which is better: 2 calls to Address Validation and GeoCoder, or 1 call to AV-Plus?

Picking the right service is a simple matter of your needs. If you need any type of demographic data along with address validation/geocoding, then AV-Plus makes the most sense. One call to the web service will yield all the data you need. Most people don’t want to do 2 calls to do both address validation and geocoding, and they find AV-Plus to be very convenient for simplifying the process. However, other people find some of the demographic data not as important, and don’t want to sort through it. In this case, they usually make a call to address validation first, then a call to geocoder. In terms of speed, the fastest option is to do address validation and geocoder in a multi-threaded environment, as doing these simultaneously is faster than one call to AV-Plus. However, getting involved in a multithreaded program and the overhead that comes with it may be more than you want to deal with. The next fastest option is one call to AV-Plus.

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/ap/AddressPlus.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.

I’m receiving a Error about an address input as well as geocode coordinates that seem to indicate good inputs. These seem to be contradictory results, what is going on here?

Roughly speaking, our Address Validation Plus service provides data that comes from two separate sources: a source that verifies the mailing address and a source that provides the geocode coordinates for the given input.  Each of these parts of the AVP service draws data from separate sources to make its own conclusions about a given input.  The address validation part of the service tends to be more strict in how it analyzes addresses than the geocode part. This can sometimes result in an input address being recognized as invalid by the address verification part of the service, while the geocode part provides a street level match(the most specific coordinates available) for the same input.  The takeaway from this circumstance is that the USPS may not recognize the given input as a valid mailing address but the geocode coordinates provided are accurate. 

AV-Plus’s geocoding is giving coordinates that aren’t anywhere near my address!

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 GeoCoder 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.

What do all these acronyms mean?

If you don’t know what they mean, they’re probably not very useful to you. Most of the cryptic return values are federal or state area numbers that are used for statistical and demographic tracking of different areas’ populations.

I’m not a programmer. How do I use DOTS AddressPlus?

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