- Introduction
- Integration
- List of Operations
- Operation Definitions
- Error Codes
- Frequently Asked Questions
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:
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
- Code Snippets
- Full Sample Code Demonstrating Failover
- URL Formats/Request and Response
- SOAP
- REST
- C#
- Java
- PHP
- RoR
- Python
- ColdFusion
- VB
- Apex
- TSQL
- NodeJS
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; } } }); });
- C# Rest
- Java Rest
- PHP Rest
- RoR Rest
- Python Rest
- ColdFusion Rest
- VB Rest
- TSQL Rest
- NodeJS Rest
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}¶meter2={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; } } } }
- GetAddrPlusNoCensus
- GetAddrPlusWithDPV
- GetAddressPlus
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
- GetAddressPlusWithDPV (Recommended Operation) — Same as GetAddressPlus with additional DPV data.
- GetAddressPlus – Provides extensive address, geocoding, and demographic data about a given US address.
- GetAddressPlusNoCensus — Same as GetAddressPlus except it does not return the census data.
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
Name | Type | Description |
---|---|---|
Address | String | Address line of the address to validate. For example, “123 Main Street”. |
Address2 | String | Second address line of the address to validate. Usually ignored. |
City | String | The 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. |
State | String | The 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. |
Zip | String | The 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. |
LicenseKey | String | Your license key to use the service. Sign up for a free trial key at: https://www.serviceobjects.com/address-insight/ |
GetAddressPlusWithDPV Outputs
Name | Type | Values | Description |
---|---|---|---|
Address | String | Varies | The corrected Address line 1. |
City | String | Varies | The corrected city name. |
State | String | Varies | The corrected state name. |
Zip | String | Varies | The corrected zip code + 4. |
Address2 | String | Varies | The corrected Address line 2. |
BarcodeDigits | String | Varies | The post office delivery barcode digits. |
CarrierRoute | String | Empty | No longer supported. |
CongressCode | String | Varies | The congress code of the given address. |
CountyCode | String | Varies | The county code of the given address. Same as the CountyFIPS. This code is used to uniquely identify counties on a national level. |
CountyName | String | Varies | The name of the county in which the given address lies. |
Fragment | String | Varies | The parsed “Fragment” box, apartment or unit number. Same as FragmentPMBNumber. |
FragmentHouse | String | Varies | The parsed house number of the given address. |
FragmentPMBNumber | String | Varies | The parsed apartment, box, unit, etc. number of the given address. |
FragmentPMBPrefix | String | Varies | The parsed type of the apartment, box, unit, etc. For example, “APT” or “BOX”. |
FragmentPostDir | String | Varies | The parsed post-directional of the address’s street. “West” in “North Main St West”. |
FragmentPreDir | String | Varies | The parsed pre-directional of the address’s street. “North” in “North Main St West”. |
FragmentStreet | String | Varies | The parsed name of the street in the given address. “Main” in “North Main St West”. |
FragmentSuffix | String | Varies | The parsed suffix of the street in the given address. “St” in “North Main St West”. |
Latitude | String | Number | The closest geocoding latitude match of the given address. See “GeocodeLevel” below for different levels of matching. |
DPV* | String | 1-8 | Number 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* | String | Varies | Explains DPV result. |
DPVNotes* | String | 1-14 | Number that correlates to DPV notes description. |
DPVNotesDesc* | String | Varies | Details about the DPV result. |
Corrections* | String | 1-41 | Number that correlates to a Corrections Description. |
CorrectionsDesc* | String | Varies | Details about the Correction. |
Longitude | String | Number | The closest geocoding longitude match of the given address. See “GeocodeLevel” below for different levels of matching. |
Tract | String | Number | The Census Tract of the given address. |
Block | String | Number | The Census Block of the given address. |
AreaCode | String | Varies | The phone Area Code of the given address. |
CityAbbreviation | String | Varies | A common alternate contraction of the city’s name. |
CityType | String | N, 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. |
CountyFIPS | String | Varies | The county code of the address’s county. |
StateFIPS | String | Varies | The state code of the address’s state. |
TimeZone | String | Number | The number of hours offset from GMT. 5 = Eastern time zone, 8 = Pacific time zone, etc. |
DayLightSavings | String | Y or N | Whether the given zip code observes DayLight Savings time. |
MSA | String | Varies | The Metropolitan Statistical Area Code. Used to uniquely identify a geographic area with a relatively high population density at its core. |
MD | String | Varies | The Metropolitan district code. |
CBSA | String | Varies | The Core Based Statistical Area Code. A code used to identify an urban center of at least 10,000 people and adjacent areas that are socioeconomically tied to the urban center. |
PMSA | String | Varies | The Primary Metropolitan Statistical Area code. Used to uniquely identify areas that are part of a larger urban center. |
DMA | String | Varies | The Designated Market Area code. Used to uniquely identify a geographic region that receive the same(or similar) TV and radio show programs. |
ZipLatitude | String | Number | The Zip centroid’s latitude. |
ZipLongitude | String | Number | The Zip centroid’s longitude. |
MedianIncome2000 | String | Number | The median income for the zip code in 2000. |
MedianIncome2005 | String | Number | The median income for the zip code in 2005. |
AreaHouseholdIncome | String | Number | The average income for the immediate area in 2000. |
CountyHouseholdIncome | String | Number | The average income for the county in 2000. |
StateHouseholdIncome | String | Number | The average income for the state in 2000. |
GeocodeLevel | String | S, P, T, Z, C | The closest level of geocoding that matched. S = Street P = Zip + 4 T = Zip + 2 Z = Zip C = City & State |
GeocodeLevelDescription | String | Varies | A verbose description of GeocodeLevel. |
Error – Desc | String | Varies | If there was an internal web service error, the description will be displayed here. |
Error – Number | String | “1”, “2”, “4” | See “Error Codes” below. |
Error – Location | String | Always null | Deprecated, no longer used. |
*See tables below for possible values.
DPV Codes
DPV | DPV Desc |
---|---|
1 | Yes, the input record is a valid mailing address |
2 | No, the input record is not in the DPV database of valid mailing addresses |
3 | The apartment or rural route box number is not valid, although the house number or rural route is valid |
4 | The input record is a valid mailing address, but is missing the apartment or rural route box number |
5 | Internal error. Please contact customer service |
6 | Internal error. Please contact customer service |
7 | Internal error. Please contact customer service |
8 | Internal error. Please contact customer service |
DPVNotes | DPVNotesDesc: |
---|---|
1 | The input address matched the ZIP+4 record |
2 | The input address did not match the ZIP+4 record |
3 | The input address matched the DPV record |
4 | The input address primary matched DPV but the secondary did not |
5 | The input address is a military APO/FPO address |
6 | The input address is a general delivery address |
7 | The input address is a building name, and the primary is missing |
8 | The input address matched a DPV high-rise but a secondary was not input |
9 | The input address primary is invalid |
10 | The input address is missing a PO box, rural route, or highway contract box number |
11 | The input address (PO box, rural route, or highway contract) primary is invalid |
12 | The input address specified a PMB and matched a CMRA |
13 | The input address did not include a PMB and matched a CMRA |
14 | The input address matched and retained a unique ZIP code |
15 | SuiteLink did not find Suite or Unit data to append to the address |
19 | Household or residence indicated by RDI |
23 | Highrise apartment/office building address |
Corrections | CorrectionDesc |
---|---|
1 | State not found |
2 | City not found |
3 | Street not found |
4 | Address not found |
5 | Uncomputable +4 range |
6 | +4 unavailable |
7 | Multiple streets match |
8 | Multiple addresses match |
9 | Time ran out |
10 | Output too long |
11 | Unused and reserved |
12 | Company phonetic match used |
13 | First company match used |
14 | State determined from city |
15 | State determined from ZIP |
16 | City phonetic match used |
17 | City determined from ZIP |
18 | Acceptable city name used |
19 | Street phonetic match used |
20 | Predirection dropped |
21 | Predirection added |
22 | Suffix dropped |
23 | Suffix added |
24 | Postdirection dropped |
25 | Postdirection added |
26 | Predirection standardized |
27 | Street standardized |
28 | Suffix standardized |
29 | Postdirection standardized |
30 | Street missing |
31 | Alternate address used |
32 | Unit standardized |
33 | Unit missing |
34 | Unit not found |
35 | Unit unverified |
36 | Rural box not found |
37 | Leftovers found |
38 | ZIP not found |
39 | ZIP changed |
40 | +4 changed |
41 | Route changed |
42 | Suite or Unit data appended using SuiteLink |
43 | Directional 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
Name | Type | Description |
---|---|---|
Address | String | Address line of the address to validate. For example, “123 Main Street”. |
Address2 | String | Second address line of the address to validate. Usually ignored. |
City | String | The 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. |
State | String | The 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. |
Zip | String | The 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. |
LicenseKey | String | Your license key to use the service. Sign up for a free trial key at: https://www.serviceobjects.com/address-insight/ |
GetAddressPlus Outputs
Name | Type | Value | Description |
---|---|---|---|
Address | String | Varies | The corrected Address line 1. |
City | String | Varies | The corrected city name. |
State | String | Varies | The corrected state name. |
Zip | String | Varies | The corrected zip code + 4. |
Address2 | String | Varies | The corrected Address line 2. |
BarcodeDigits | String | Varies | The post office delivery barcode digits. |
CarrierRoute | String | Empty | No longer supported. |
CongressCode | String | Varies | The congress code of the given address. |
CountyCode | String | Varies | The county code of the given address. Same as the CountyFIPS. This code is used to uniquely identify counties on a national level. |
CountyName | String | Varies | The name of the county in which the given address lies. |
Fragment | String | Varies | The parsed “Fragment” box, apartment or unit number. Same as FragmentPMBNumber. |
FragmentHouse | String | Varies | The parsed house number of the given address. |
FragmentPMBNumber | String | Varies | The parsed apartment, box, unit, etc. number of the given address. |
FragmentPMBPrefix | String | Varies | The parsed type of the apartment, box, unit, etc. For example, “APT” or “BOX”. |
FragmentPostDir | String | Varies | The parsed post-directional of the address’s street. “West” in “North Main St West”. |
FragmentPreDir | String | Varies | The parsed pre-directional of the address’s street. “North” in “North Main St West”. |
FragmentStreet | String | Varies | The parsed name of the street in the given address. “Main” in “North Main St West”. |
FragmentSuffix | String | Varies | The parsed suffix of the street in the given address. “St” in “North Main St West”. |
Latitude | String | Number | The closest geocoding latitude match of the given address. See “GeocodeLevel” below for different levels of matching. |
DPV* | String | 1-8 | Number 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* | String | Varies | Explains DPV result. |
DPVNotes* | String | 1-14 | Number that correlates to DPV notes description. |
DPVNotesDesc* | String | Varies | Details about the DPV result. |
Corrections* | String | 1-41 | Number that correlates to a Corrections Description. |
CorrectionsDesc* | String | Varies | Details about the Correction. |
Longitude | String | Number | The closest geocoding longitude match of the given address. See “GeocodeLevel” below for different levels of matching. |
Tract | String | Number | The Census Tract of the given address. |
Block | String | Number | The Census Block of the given address. |
AreaCode | String | Varies | The phone Area Code of the given address. |
CityAbbreviation | String | Varies | A common alternate contraction of the city’s name. |
CityType | String | N, 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. |
CountyFIPS | String | Varies | The county code of the address’s county. |
StateFIPS | String | Varies | The state code of the address’s state. |
TimeZone | String | Number | The number of hours offset from GMT. 5 = Eastern time zone, 8 = Pacific time zone, etc. |
DayLightSavings | String | Y or N | Whether the given zip code observes DayLight Savings time. |
MSA | String | Varies | The Metropolitan Statistical Area Code. Used to uniquely identify a geographic area with a relatively high population density at its core. |
MD | String | Varies | The Metropolitan district code. |
CBSA | String | Varies | The Core Based Statistical Area Code. A code used to identify an urban center of at least 10,000 people and adjacent areas that are socioeconomically tied to the urban center. |
PMSA | String | Varies | The Primary Metropolitan Statistical Area code. Used to uniquely identify areas that are part of a larger urban center. |
DMA | String | Varies | The Designated Market Area code. Used to uniquely identify a geographic region that receive the same(or similar) TV and radio show programs. |
ZipLatitude | String | Number | The Zip centroid’s latitude. |
ZipLongitude | String | Number | The Zip centroid’s longitude. |
MedianIncome2000 | String | Number | The median income for the zip code in 2000. |
MedianIncome2005 | String | Number | The median income for the zip code in 2005. |
AreaHouseholdIncome | String | Number | The average income for the immediate area in 2000. |
CountyHouseholdIncome | String | Number | The average income for the county in 2000. |
StateHouseholdIncome | String | Number | The average income for the state in 2000. |
GeocodeLevel | String | S, P, T, Z, C | The closest level of geocoding that matched. S = Street P = Zip + 4 T = Zip + 2 Z = Zip C = City & State |
GeocodeLevelDescription | String | Varies | A verbose description of GeocodeLevel. |
Error – Desc | String | Varies | If there was an internal web service error, the description will be displayed here. |
Error – Number | String | “1”, “2”, “4” | See “Error Codes” below. |
Error – Location | String | Always null | Deprecated, no longer used. |
CityType Code Definitions
Code | Description |
---|---|
N | Non Postal Community Name: Former Postal Facility |
P | Post Office: Official post office branch. |
U | Urbanization: Specific to Puerto Rico. |
B | Branch: A postal facility that is not the main post office and is outside the corporate limits of a city. |
A | Airport Mail Facility: Facilities through which US mail is flown in and out of the city. |
C | Community Post Office: a contract postal unit providing mail services to small communities. |
S | Station: A post office that is not the main office for a city but is in corporate city limits. |
K | Bulk 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.
Number | Desc | Service Error Origin | Description |
---|---|---|---|
2 | Address not found | Address Validation | Major issue with address that doesn’t fit known USPS special case scenarios. |
2 | Street not found | Address Validation | Street name not found for general area (city/state or zip) |
2 | Please input a valid address. | Address Validation | The basic address information was not present(i.e. Address and Zip or Address and City/State |
2 | Street number or box number out of range | Address Validation | Street name found in area, but the given primary number is not valid for that street |
2 | Zip code does not exist. | Geo Coder | The entered zip code does exist in the Geocode data. |
2 | Please input a valid US Zip Code. | Geo Coder | The entered zip code was not a valid zip code format or the zip code did not exist |
2 | Location not found. | Geo Coder | No city/state or zip code location could be found for this data |
2 | State not found | Geo Coder | The entered state was not found the Geocoder data. |
2 | Address was not found. | Geo Coder | The entered address was not found in the Geocoder data |
2 | Address and Address2 fields were too long. Together, they must be 100 characters or less. | Address Validation | The entered Address1 and Address2 fields were too long and deemed not to be valid |
2 | Address field was too long, must be 100 characters or less. | Address Validation | The 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/.