API stands for Application Program Interface. It is a way for software to communicate with each other based on specific inputs and outputs. API’s are everywhere, nearly any application in existence can use them. One API can even utilize one or more other API’s as well. What an API is has been defined and explained in any number of Google search results. What I want to talk about is what an API really is.

It is a way to reuse existing code. Writing reusable code is often a high consideration when developers write code. If you are going to need a specific functionality over and over again, why recreate the wheel? Well, that is just what APIs help developers avoid, as well as making code more understandable and enabling them to be more productive, resulting in saved time and money.

The interchangeable nature of API’s makes switching one API out for another relatively simple. The cost of improving complex segments of code is almost as simple as unplugging a broken toaster and plugging in a new one.

The beauty of APIs is that they allow your organization’s developers to do what they do best. They don’t need to be an expert in everything. Often organizations can be sent on wild goose chases trying to figure out solutions that they are not experts in. At Service Objects, we want your business to continue being an expert at what you do and let us be your expert in the field of contact validation. Why attempt to do the heavy lifting of trying to solve a problem that is not in your wheel house? Without spending an enormous amount of time and money, there is little chance that you will be able to reproduce the code that another API can give you out of the box.

At Service Objects, we have been developing our services since 2001, so when someone is purchasing any of our 23 APIs, they are using over 16 years of cumulative knowledge and expertise. And on top of that, we are going to keep learning and improving on our services so that our customers don’t have to. What this means is that your organization can be using the best code available in your applications and leverage the best practices we have developed without being an expert in the field of data validation.

For more information, or to obtain a free trial key for any of Service Objects’ Data Validation APIs, click here.

Watch this video and hear Service Objects’ Application Engineer, Dylan, as he presents a 22 minute step-by-step tutorial on how to integrate an API using C#. In order to participate in this tutorial, you will need the following :

1. A basic knowledge of C# and object-oriented programming.
2. Visual Studio or some other IDE.

Any DOTS Validation Product Key. You can get free trial keys at www.serviceobjects.com.

In this tutorial, we have selected the DOTS Email Validation web service.  This service performs real-time checks on email addresses to determine if they are genuine, accurate and up-to-date. The service performs over 50 tests on an email address to determine whether or not it can receive email.  If you are interested in a different service, you can still follow along in this tutorial with your service of choice. The process will be the same, but the outputs, inputs, and objects that we’ll be dealing with in the integration video will be slightly modified.

Enjoy.

In this demonstration I am going to show you how to implement our DOTS Address Validation 3 web service with JavaScript and no Asp.Net markup tags using Visual Studio.  We are going to create a form for address inputs, similar to what you would see on a checkout page, which will call our API to validate the address.  Although, we could call the web service directly from JavaScript, we would then be forced to expose our license key.  So we will use an aspx.cs page to handle our call to the service API, keeping our license key safe from prying eyes.  In this demonstration, I will also show you how to add the NuGet version of DOTS Address Validation 3 to the project so that you are always using our best practices and speeding up your integration.

First, create a new empty web site, which I am going to call, cSharpJavascriptAjax.  Then I am going to add a new html page called, Addressvalidation.html.

   

Next, we are going to add the markup for the form.  Add the following code in between the body tag.

    <div>
        <table cellSpacing="4" cellPadding="4" border="0">
            <tr>
                <td>
                    <b>Enter An Address</b><br />
                    <i>(US addresses only)</i>
                    <p></p>
                </td>
            </tr>
            <tr>
                <td>Business Name:</td>
                <td><input type="text" id="inputBusinessName" /></td>
            </tr>
            <tr>
                <td>Address 1:</td>
                <td><input type="text" id="inputAddress" /></td>
            </tr>
            <tr>
                <td>Address 2:</td>
                <td><input type="text" id="inputAddress2" /></td>
            </tr>
            <tr>
                <td>City:</td>
                <td><input type="text" id="inputCity" /></td>
            </tr>
            <tr>
                <td>State:</td>
                <td><input type="text" id="inputState" /></td>
            </tr>
            <tr>
                <td>PostalCode:</td>
                <td><input type="text" id="inputZip" /></td>
            </tr>
            <tr>
                <td>
                    <input id="submitButton" type="button" onclick="submit()" value="Continue" />
                </td>
            </tr>
        </table>
    </div>

This form was designed using the table structure for the layout.  You will likely want to create the layout using divs, which is more appropriate.   Here is what the page looks like in the browser.

To speed things up a bit, I am going to include jQuery in the header so we can utilize some of the short cut functions.  Of course, all of this can be done in pure JavaScript.

<head>
    <script src="http://code.jquery.com/jquery-latest.min.js" type="text/javascript"></script>
    <title>Address Validation 3</title>
	<meta charset="utf-8" />
</head>

For the action we will take when the Complete button is clicked, we will create the submit function.  This will take in all the values from the form, call the web service and then display the response to the screen.  I added an alert and left the URL blank, this will allow for a quick test to make sure what we have is working.  Later we will update the failure and success sections as well.  For now, they will simply display an alert for testing.

<script>
        function submit() {
            var DataValue = "{BusinessName:'" + $('#inputBusinessName').val() + 
"',Address1:'" + $('#inputAddress').val() + 
"',Address2:'" + $('#inputAddress2').val() + 
"',City:'" + $('#inputCity').val() + 
"',State:'" + $('#inputState').val() + 
"',ZipCode:'" + $('#inputZip').val() + "'}";

            alert(DataValue);
            $.ajax({
                type: "POST",
                url: "",
                data: DataValue,
                contentType: 'application/json; charset=utf-8',
                dataType: 'json',
                failure: function (response) {
                    alert(response.d);
                },
                success: function (response) {
                    alert(response.d);
                }
            });
        }
    </script>

First, let’s start by making sure we are getting all the inputs into the submit function and are getting all the inputs back.  I am going to display an alert with DataValue variable so we can see what we have.

Good, now that we know that is working, we will need to make the call to the web service.  Like I mentioned before, we could call the service directly but using JavaScript would make the license key visible.  So we are going to leverage asp.net for security by creating and empty aspx page and add a method to the aspx.cs page to handle the call.  Let’s go ahead and add the aspx/aspx.cs page to the project and call it, ServiceObjectsAPIHandler.

Here is our empty aspx.cs page, where we will be adding our function. It will go below the Page_Load method.

Let’s call the method, CallDOTSAddressValidation3_GBM.  There are two things to notice with the signature for this method.  We decorate the method with the WebMethod attribute so that our new method can be exposed as a web service method. And, we declare it as static because of the stateless nature of the static methods.  An instance of a class does not need to be declared.

        [WebMethod]
        public static string CallDOTSAddressValidation3_GBM(string InputText)
        {
            return InputText;
        }

To test things out, for now we will just take one string input and return it to the Ajax call where we will display it.  In order to do this, we will need to adjust our DataValue call in the script on the html page.

var DataValue = "{InputText:'Hello World!'}";

We will also need to add the URL and method to the Ajax call.

url: "ServiceObjectsAPIHandler.aspx/CallDOTSAddressValidation3_GBM",

I also adjusted the alerts so we can see the success or fail.

failure: function (response) {
                    alert(response.d + " :(");
                },
                success: function (response) {
                    alert(response.d + " :)");
                }

Great! That worked! Now, let’s write up the code in the aspx.cs page to make the call to the service.  We could grab some sample code from the web site and walk through it, but we have documentation and tutorials already on how to do that.  Instead, I am going to take a short cut and grab what I need from NuGet.  We offer NuGet packages for most of our services, which include best practices such as failover configurations and speeding up the integration time.

To do this, we will need to open up the NuGet Package Manager in Visual Studio under the Tools menu option.  When browsing  for our services, you can type “Serviceobjects”.  You should see a list of available Service Objects NuGet packages to choose from.

Select DOTSAddressValidation3US, you will be prompted to select the project you want to install it under.  Select the project and then click install.

Once the installation is complete, a ReadMe file will automatically open that will contain a lot of information about the service.  You will also notice a few things were added to your project.  First, a DLL for DOTSAddressValidation3US was added to the bin folder and was referenced in your project.

Next, an AV3LicenseKey app setting was added to your web.config file with the value “WSXX-XXXX-XXXX”.  You will need to substitute this value for the key you received from Service Objects.

    <appSettings>
      <add key="AV3LicenseKey" value="WSXX-XXXX-XXXX" />
    </appSettings>

Also in the web.config you will see several endpoints were added.  These will be used in the pre-packaged code to determine how to call the service based on your key.

<system.serviceModel>
        <bindings>
            <basicHttpBinding>
                <binding name="DOTSAddressValidation3" />
                <binding name="DOTSAddressValidation31" />
            </basicHttpBinding>
        </bindings>
        <client>
            <endpoint address="http://wsbackup.serviceobjects.com/AV3/api.svc/soap"
                      binding="basicHttpBinding" 
                      bindingConfiguration="DOTSAddressValidation3" 
                      contract="AV3Service.IAddressValidation3" 
                      name="DOTSAddressValidation3Backup" />
            <endpoint address="http://trial.serviceobjects.com/AV3/api.svc/soap" 
                      binding="basicHttpBinding" 
                      bindingConfiguration="DOTSAddressValidation3" 
                      contract="AV3Service.IAddressValidation3" 
                      name="DOTSAddressValidation3Trial" />
            <endpoint address="http://ws.serviceobjects.com/AV3/api.svc/soap" 
                      binding="basicHttpBinding" 
                      bindingConfiguration="DOTSAddressValidation31" 
                      contract="AV3Service.IAddressValidation3" 
                      name="DOTSAddressValidation3" />
        </client>
    </system.serviceModel>

Now that we have the NuGet package added to the project, we can use it.  Next is the code that will use the DOTSAddressValidation3US DLL by loading it up with the input parameters, making the call to the service, then working with the response and finally sending the data back out to our JavaScript.

First we get the license key from the web configs file.

string LicenseKey = System.Configuration.ConfigurationManager.AppSettings["AV3LicenseKey"];

Then we make the call to the service.  You will notice that we throw in a Boolean parameter at the end of the call to GetBestMatches for live or trial.  This is an indicator that will tell the underlying process which endpoints to use.  A mismatch between your license key and this Boolean flag will cause the call to the service to fail.

DOTSAddressValidation3US.AV3Service.BestMatchesResponse DOTSAddressResponse = DOTSAddressValidation3US.DOTSAV3.GetBestMatches(BusinessName, Address, Address2, City, State, ZipCode, LicenseKey, false);

After we make the call to the service, we will process the response and send the data back to the JavaScript. If there is an error,  we will return the error details. Otherwise, we will return a serialized version of the response object.  Note that you can also just deal with the response completely here or completely in JavaScript.  I mixed it up so you can see a bit of both.

if(DOTSAddressResponse.Error != null)
{
string ErrorDesc = DOTSAddressResponse.Error.Desc;
string ErrorType = DOTSAddressResponse.Error.Type;
      return "Address Error: " + ErrorType + ". " + ErrorDesc;
}
else
{
      return new JavaScriptSerializer().Serialize(DOTSAddressResponse);
     } 

Here is the whole method all together.

[WebMethod]
public static string CallDOTSAddressValidation3_GBM(string BusinessName, string Address, string Address2, string City, string State, string ZipCode)
{
string LicenseKey = System.Configuration.ConfigurationManager.AppSettings["AV3LicenseKey"];
DOTSAddressValidation3US.AV3Service.BestMatchesResponse DOTSAddressResponse = DOTSAddressValidation3US.DOTSAV3.GetBestMatches(BusinessName, Address, Address2, City, State, ZipCode, LicenseKey, false);
            if(DOTSAddressResponse.Error != null)
            {
                string ErrorDesc = DOTSAddressResponse.Error.Desc;
                string ErrorType = DOTSAddressResponse.Error.Type;
                return "Address Error: " + ErrorType + ". " + ErrorDesc;
            }
            else
            {
                return new JavaScriptSerializer().Serialize(DOTSAddressResponse);
            }
}

Now we will turn our attention back to the JavaScript and update our submit function.  All we really have to deal with now is the response from the aspx method call.  Here is the portion of the Ajax call implementing that.

failure: function (response) {
    alert('Something went wrong!');},
success: function (response) {
    if ((response.d + "").startsWith("Address Error")) {
         alert(response.d);
    }else {
         var AddressResponse = JSON.parse(response.d);
         if (AddressResponse.Addresses[0].DPV === "1") {
              alert("Good Address!");
         }else {
              alert("Not Good Address: " + AddressResponse.Addresses[0].DPVNotes);
         }
    }}

Success or failure here does not mean that the address is good or not.  It is really just a success or failure of the call to the aspx web method.  On failure, we simply make an alert stating something went wrong.  On success, we examine the response value, determine if the address was good or not and display the appropriate response.  Here is the whole submit function.

function submit() {
var DataValue = "{BusinessName:'" + $('#inputBusinessName').val() + 
"',Address1:'" + $('#inputAddress').val() + 
"',Address2:'" + $('#inputAddress2').val() + 
"',City:'" + $('#inputCity').val() + 
"',State:'" + $('#inputState').val() + 
"',ZipCode:'" + $('#inputZip').val() + "'}";
            $.ajax({
                type: "POST",
                url: "ServiceObjectsAPIHandler.aspx/CallDOTSAddressValidation3_GBM",
                data: DataValue,
                contentType: 'application/json; charset=utf-8',
                dataType: 'json',
                failure: function (response) {
                    alert('Something went wrong!');
                },
                success: function (response) {
                    if ((response.d + "").startsWith("Address Error")) {
                        alert(response.d);
                    }
                    else {
                        var AddressResponse = JSON.parse(response.d);
                        if (AddressResponse.Addresses[0].DPV === "1") {
                            alert("Good Address!");
                        }else {
                            alert("Not Good Address: " + AddressResponse.Addresses[0].DPVNotes);
                        }
                    }
                }
            });
        }

 

Here is a good address.

 

And here is a bad address.

 

In the submit function, we did the most basic check to see if an address was good or not.

if (AddressResponse.Addresses[0].DPV === "1")

But many more data points from the response can be used to make any number of conclusions about an address.  One thing you will notice is that AddressResponse.Addresses is an array.  A check to see if multiple addresses are returned can be valuable because in certain situations more than one address may be returned.  One example is when an East and a West street address are equally valid responses to an input address.  In this case you may want to display both addresses and let the user determine which to use.  You may want to evaluate the individual address fragments or the corrections that were made to the address.

The data points associated to the DOTS Address Validation US 3 service can be found on our development guide page for the service.

The following is commented out code that I added to the submit method for easy access to the various output data points.

//AddressResponse.Addresses[0].Address1
//AddressResponse.Addresses[0].Address2
//AddressResponse.Addresses[0].City
//AddressResponse.Addresses[0].State
//AddressResponse.Addresses[0].Zip
//AddressResponse.Addresses[0].IsResidential
//AddressResponse.Addresses[0].DPV
//AddressResponse.Addresses[0].DPVDesc
//AddressResponse.Addresses[0].DPVNotes
//AddressResponse.Addresses[0].DPVNotesDesc
//AddressResponse.Addresses[0].Corrections
//AddressResponse.Addresses[0].CorrectionsDesc
//AddressResponse.Addresses[0].BarcodeDigits
//AddressResponse.Addresses[0].CarrierRoute
//AddressResponse.Addresses[0].CongressCode
//AddressResponse.Addresses[0].CountyCode
//AddressResponse.Addresses[0].CountyName
//AddressResponse.Addresses[0].FragmentHouse
//AddressResponse.Addresses[0].FragmentPreDir
//AddressResponse.Addresses[0].FragmentStreet
//AddressResponse.Addresses[0].FragmentSuffix
//AddressResponse.Addresses[0].FragmentPostDir
//AddressResponse.Addresses[0].FragmentUnit
//AddressResponse.Addresses[0].Fragment
//AddressResponse.Addresses[0].FragmentPMBPrefix
//AddressResponse.Addresses[0].FragmentPMBNumber

And here is the same thing but for the Error object in the aspx page.

//string ErrorDesc = DOTSAddressResponse.Error.Desc;
//string ErrorDescCode = DOTSAddressResponse.Error.DescCode;
//string ErrorType = DOTSAddressResponse.Error.Type;
//string ErrorTypeCode = DOTSAddressResponse.Error.TypeCode;

I hope this walk-thru was helpful in demonstrating how to implement our DOTS Address Validation 3 web service with JavaScript and no Asp.Net markup tags using Visual Studio.  If you have any question, please feel free to contact Service Objects for support.

The reality about any set of residential customer data is that given enough time, addresses and the people living there are bound to change. Occasionally, businesses and organizations can rely on the customer to notify them of changing addresses but when people move, this often times falls to the wayside on the list of priorities.

For cases like these, accessing the USPS National Change of Address database can provide a helpful solution to ensure that mail gets delivered to the correct person. The USPS maintains a large data set of address forwarding notifications, and with the DOTS NCOA Live service, this information is right at your finger tips.

Our DOTS NCOA Live service is a bit different than the rest of our products. Most of our other products process validation requests in a one at a time manner. NCOA is a little different in that in order to start a request, a minimum list of 100 addresses must be sent to the service, and from there anywhere from 1 to 500 records can be processed at a time. To show you how it works, we’ve put together a quick step by step tutorial.

What You Will Need

• C# experience
• Visual Studio ( VS 2015 is used for this example)
• A DOTS NCOA Live license Key. A free Trial Key can be obtained here.

Project Creation and Setup

To get started, go ahead and launch Visual Studio and select File->New->Project.  From here you can choose whatever project will meet your needs. For this example, we’ll be creating a very basic console application.  So if you want to follow along step by step, you can choose the same project details as shown below.

Select OK and wait for Visual Studio to finish creating the project. Once that is done, right click the project, select Add and then select Service Reference. Here, we’ll enter the URL to the WSDL so that Visual Studio will create all the necessary classes, objects and methods that we’ll use when interacting with the DOTS NCOA Live service. To successfully do this, add the necessary information into the pop up screen as shown in the screenshot below.

Select OK. Now that the service reference is successfully set, open up the App.Config. Below is a screenshot of the App.Config that has been modified.

We’ve added the appSettings section and within that we’ve added two key value pairs. The first is the license key field where you will enter your key. Storing the license key in the app or web config files can be helpful and easy when transitioning from a trial to a live environment in your application. When you are ready to use a production key, changing it in the app config is an easier option than having to change a hard coded license key.

We’ve also put the path to a csv that will contain the address and name information that we will be sending to the NCOA service. You may not want to read in a CSV for your application but the process of building the input elements for the service will be relatively similar. For this example, we’re just going to put the file in the BIN folder of our project, but you can add any path you want to the file.

We’ve also increased the maximum buffer size in the http Binding. Since we’ll be sending a list of 100 addresses to the DOTS NCOA Live service, we’ll indeed need to increase the buffer size.

Lastly, we’ve changed the name of the original endpoint to “PrimaryClient,” made a copy of the endpoint and changed that name to “BackupPoint.” Currently, both of these endpoints point to the trial Service Objects environment, but when a production key is purchased, the PrimaryClient url should point to http://ws.serviceobjects.com/nl/ncoalive.asmx and the BackupClient should point to http://wsbackup.serviceobjects.com/nl/ncoalive.asmx.

Calling the DOTS NCOA Live web service

The first thing we’ll do is instantiate two static strings outside of the Main method. One will be for the input file, and the other will be for the license key that we’ve placed in the app.config. Inside the scope of the Main method, we’ll instantiate a NCOAAddressResponse object called response and set it equal to null. We’ll also create a string called jobID and set that equal to null as well.  This jobID will be passed as a parameter to our NCOA service call. A JobID can be seen as a unique identifier for all the records that are run against the service.

Now we’ll create the following method that will read our input file.

This method will return a List of the NCOAAddress object that will have all the inputs we need to send to the service. In my particular file the fields are as follows: Name, Address, Address2, City, State, Zip.  Your code will need to be modified to read the specific structure of your input file. This code reads in the file and then loops through each of the lines and adds the appropriate values to the fields of the NCOA address object. After the line is successfully read, we add the individual NCOAAddress objet to the list called inputAddresses and then return that object once the code has finished looping through the file.

Now we’ll insert a try catch block into the main method. Within this try catch block we’ll create a List of the NCOAAddress object and call the readInputFile method to fill it. We’ll also make a JobID with today’s date appended to the end of it. You will likely want to customize your job id to fit into your business application. Jobs close on Sunday at 11:55 PM so that is also something to take into consideration when designing your code.

Failover Configuration

Now that we have all our inputs successfully set up, we are able to call the NCOA web service. The first step we’ll take is create another try catch block to make the web service calls in. We will also create an instance of the DOTSNCOALibraryClient and pass in the trip “PrimaryClient” as a parameter. This will ensure that our first call to the NCOA service will point to our primary URL that we have defined in the web config. Next we’ll make the call to the webservice using the library client and set it equal to our response object.

After we get a response back from the service we’ll perform our failover check. We check if the response is null or if an error TypeCode of 3 was returned from the service. An error type code of 3 would indicate that a fatal error occurred with the service. If either of these criteria are met, then we’ll throw an exception that will be caught by the catch block we have created. Within this catch block we’ll set the library client object to a new instance with the “BackupClient” string passed to it to ensure that we call the backup client. The code should look like the following.

This failover logic will ensure that your application stays up and running in the event that a Service Objects web service is unresponsive or in the event that it is not behaving as expected.

Processing the Response

Now that we have successfully called the service, we’ll need to do something with the response. In this tutorial, we’ll take the results from the service and download them as a CSV into our bin folder.

To do this, we will call and create a method called processResponse that will take a NCOAAddressResponse as an input. This method will take the outputs from the service and build a DataTable that we will use to eventually turn into a CSV. This can be done as shown in the following screen shot.

 

 

Now that our output data table has been created, we’ll call and create two methods will loop through our DataTable and convert it to a CSV string, and then write that CSV to the bin folder.  The code to perform this is shown below.

More information on all the elements in the response object can be found on our developer guide for the NCOA service.

Now that our output data table has been created, we’ll call and create two methods will loop through our Data Table and convert it to a CSV string, and then write that CSV to the bin folder. The code to perform this is shown below.

Now our code is ready to run and the service is ready to test.

We’re always available for assistance, so be sure to contact us with any questions about integration for NCOA or any of our other services.

“In the era of big data and software as a service, we are witnessing a major industry transformation. In order to stay competitive, businesses have reduced the time it takes to deploy a new application from months to minutes.” – Geoff Grow, Founder and CEO, Service Objects

The big data revolution has ushered in a major change in the way we develop software, with applications webified and big data tools woven in. Until recently data quality tools that ensure data is genuine have not kept pace. As a result, developers have had little choice but to leave out data validation in their applications.

In this video, Geoff will show you why data validation is critical to reducing waste, identifying fraud, and maximizing operation efficiency – and how on-demand tools are the best way to ensure that this data is genuine, accurate, and up-to-date. If you develop applications with IP connectivity, watch this video and discover what 2,400 other organizations have learned about building data quality right into their software.

You’ve found Service Objects, you’ve read about our services so now you want to test drive. Well, there are several ways to do just that and as I go through the options you will also get a pretty good picture about how you can integrate our services into your applications or processes. Testing can be a tedious task, delving into the unknown of a third party process, but we make it easy for you to jump right in by giving you several ways to test such as our Quick Lookup Tool, DataTumbler, Batch Processing and our real-time API services.

Quick Lookup Tool
The Quick Lookup tool is used to test one off examples on our website.  It is as simple as navigating to the Quick Lookup page, selecting the particular service you are interested in, filling out the fields and clicking submit. You’ll receive a real time response from the service containing the results of your test.

Since our services often offer multiple operations the Quick Lookup pages will inform you which operation is being used for the particular service in the form. If there are other operations you are interested in testing then we have you covered there as well with links to the other operations.

DataTumbler
The DataTumbler is a PC-based desktop application you can download from our site to run tests on multiple records. If you have ever used Excel then this application will be easy for you to drive. It works like a spreadsheet where you can paste multiple records for processing, in real-time.

Here are the basic steps: Choose your service, choose your operation, drop your data in and click validate. Choosing the service and desired operation is important because often it will change the input columns needed for the records to process properly. In the screenshot above you can see that there are 5 input columns designated by the yellowish cell background. Here we have inputs for Address, Address2, City, State and Zip. If your particular purposes do not require Address2, for instance, then that column can be removed by simply clicking on the “Customize Input Columns” button and removing it from the input.  You can do the same thing for the output columns as well but in that case you would need to access the “Customize Output Columns” popup.  The output columns are designated by the cells with the greenish background.

You can also add additional columns that are not predefined by the application by right clicking a column and selecting “Insert Column”.  This is handy for situations where you want additional data to stay together with your test like a unique identifier or other data unrelated to testing the service.

Once one of the validation buttons at the bottom is pressed, the DataTumbler will make requests to our services in real-time and populate the output columns as the data is being processed.

To get the application please call Customer Support at 1.800.694.6269 or access Live Chat and we will get you started.

Batch Processing
Batch processing is another way you can test drive our services.  When you have a file ready to go for testing you can simply hand it over to us.  We will process it and send back the results to you along with a summary.

This is one of the more preferred ways to test drive our services for several reasons:

• We can see the data you send us first hand and give you feedback about what the file looks like with respect to items like formatting.
• By seeing all the fields of data we can quickly recommend the most beneficial service.
• It gives us an opportunity to see the results with you and go over any interesting data points from a data validation/cleansing expert point of view.

All that is needed for this is a test file containing the records you want to try out. The file can come in several formats including txt, csv and xls to name a few. You can send us the file directly to an email or for a more secure means we can provide you a secure ftp for the file transfer. We can also handle working with encrypted data when an extra security layer is needed. An additional way to get us your test file is through our web site itself. You can drag and drop a file and be on your way. Once we have the file we will process it against the service you are testing and return the results along with a summary breakdown of the processing.

If your test run is a success and you’re ready to move forward with a larger file, we can also run one-time paid batch. Clients often use a this as an initial data scrub before a switching to our real time API or automated batch system which will run batches virtually on demand.

Integrating the API
The last way you can test our services is by implementing our API in your code. Most clients use the API when they integrate with us so testing this way gives you the closest representation of how your production process will work with our services.

When it comes to doing a direct software integration test we have you covered. We make it easy to integrate and get testing quickly by means of sample code, code snippets, step-by-step integration walk-through blogs, developer guides and NuGet for Visual Studio.

We have sample code for C#, Java, PHP, Rails, Python, NodeJS, VB.Net, Classic ASP, Microsoft SQL Server, APEX and Cold Fusion.  This list does not mean that we stop there.  Additional sample code can be requested and our team will review to find the best solution for you.  When applicable, our sample code will be available in both REST and SOAP.  All of our examples will implement best practices and demonstrate failover.

If you are a C# developer and use Visual Studio you will have us at the hands of your finger tips.  Using the NuGet Manager in Visual Studio you can have our API injected into your code and ready to go.

All of our walk-through tutorial blogs and documentation are presented in a straight forward and easy to understand format and as always the Service Objects team is here to assist with any questions or help you may need.

When it comes to test driving our services we give you options to make it easy. A trial key will give you access to all the options I mentioned. Going through these options also gave me a chance to show you how you can integrate with our services.  The beauty behind the way we set this system up is that you can become fully integrated and tested before you even purchase a live production key.  In all of these cases, usually only two things need to be updated when switching from trial testing to live production use.  In the Quick Lookup Tool you will need to switch the “Select Key Type” to “Customer Production Key” and then use your live production key instead of your trial key.  In the DataTumbler you will be similarly swapping those fields out as well.  When it comes to doing a code integration you just need to update your endpoints from trial.serviceobjects.com to ws.serviceobjects.com and the trial key for a live production key.

Whenever you want to test one or two records or a whole file, simply put, our team has you covered.

Java is easily one of the most popular programming languages in the world. It is a general purpose language that users have managed to implement in a variety of applications. It is popular with web applications; which is why it is one of our most requested sample code languages for our DOTS validation products. This is no surprise either, since Java is able to run on a wide range of architecture, applications and environments.  Since it is so popular, we’re here to show you the ropes and get a Service Objects web service up and running.

For this example we’ll be using a fairly new operation in our DOTS Address Detective service. Our Address Detective service is a power house address validation service that can leverage multiple different data sources to validate an address.  The DOTS Address Detective service has input fields for a person’s name, a business name, and a phone number along with the traditional address fields. These additional data points help the service leverage other data sources to get your address validated.  This service even has an operation that will take your data in any order it’s given and return a standardized address. It’s called FindAddressLines and has 10 inputs ranging from “Line1” to “Line10” and can work wonders on standardizing messy data sources.  We’ll be integrating with this operation in our tutorial today, so let’s get started!

What You’ll Need

• A Java IDE (We’re using Eclipse for this example)
• Basic Java Knowledge
• A Service Objects DOTS Validation product License Key (We’re using DOTS Address Detective for this case)

Setting Up the Project

Launch Eclipse and select a workspace if it asks you do so. Once everything has finished loading,  select File->New->Other. In the search field type “Dynamic Web Project” and click next.

On the next screen, type in an appropriate project name and configure the settings to our specific needs. Congratulations, you’ve built a project! We’ll need to add several files to take in our inputs, send them to the DOTS Address Detective service, serialize the XML response and display the results back to the user. To start, add two jsp files by right clicking the project and selectingNew->JSP File as shown below:

In this tutorial we’ll name them “inputForm.jsp” and “webServiceCall.jsp.”  These will function as the input form and the display page for the results from the service.

These new JSP files will obviously need something more than they currently have. We’ll place all the necessary HTML elements in the inputForm.jsp file. Make your page look like it does below:

These 10 input lines will send all the necessary information to the FindAddressLines operation.  Now that we have the necessary fields to take our input parameters, we’ll need to put the code in place to actually call the DOTS Address Validation web service. We’ll create a package with the necessary class files for the response from the Address Detective service and within that package we’ll create a method that will actually perform the call to the web service.

To add a package, right click the project and select New->Package.  For this project we’ll name the package “serviceObjects” as shown below.

Be sure to select the “Create package-info.java” checkbox as we’ll need to add some necessary import statements into the package.info file.  After the package as been added, right click it and select New->Class and add all the following classes to the project.

We’ll talk briefly about the necessary code to add to each of the different objects and classes so that the XML response from the web service will be successfully deserialized into the objects that we are defining here. One thing that needs to be added to the package-info.java file is as follows.

This will let the code know that it should expect the http://www.serviceobjects.com namespace in the XML response from the service.

Like most classes, all the values in each of the code files will need the “getters and setters” for each of the objects that the service returns in order to properly work with the returned object. The highest level object that is returned from the service (meaning all the other objects and values will be contained within that one) will be the FixedAddressResponse. This object will contain a possible array of FixedAddress objects that is called “Addresses” and it will contain an Error object that the Address Detective service can potentially return. See below for an example of how to format the declarations and, XML annotations and the “getters and setters.”

As mentioned this is a general example of how to do this and we’ll include all the class files with this tutorial so that they can be easily added to your own project.

Now we’ll point out some things to be aware of in our “ADClient” file.

Inside the class declaration, we’ll define a few things that we’ll need to make the actual call to the service.

In the above code, we’ve defined both the trial and the backup URLs. Currently, they both point to the trial environment Service Objects servers. In the event that a license key is purchased the primary call should be to ws.serviceobjects.com and the backup URL should be to wsbackup.serviceobjects.com. We’ve also defined our LicenseKey in the class which will allow us to keep it hidden from outside view and we’ve defined a method called “FindAddressLines” that will eventually call the same operation. Notice that it returns the FixedAddressResponse object.

Within the actual method we have some cleanup logic that is performed on the input strings, and then the URLs are assembled for the HTTP call. See below:

In the above snippet of code URL strings are assembled and sent to the DoHTTPRequest method. After the web service is called, it is necessary to do a check to ensure that the call was completed correctly. The code will check for a null response from the service or a ‘TypeCode” of 3 is returned which would indicate a fatal error from the Service Objects web service.  If either of those conditions is true, then the code will throw an exception and use the backup URL.  The above functionality and logic will ensure that your application will be uninterrupted in the unlikely event that the Service Object servers are non responsive or returning a TypeCode of 3.

Displaying The Results from the Web Service

Since our failover logic and call to the DOTS Address Detective web service are set up, we can now create the objects that will call the web service with the inputs from the input form, and display the results to the user.

Navigate to the webServiceCall.jsp file and implement the following code:

In this bit of code we’ll grab the inputs from the inputForm.jsp page and place them in strings of the same name.  We’ve also instantiated an instance of the “FixedAddressResponse” object which will hold the results from the service and the “ADClient” object which will make the actual call to the web service.  Since our FindAddressLines method in the ADClient object returns a FixedAddressResponse object we can set it equal to it.

Our call to the web service is all set up and now we can implement some logic that will either display the results from the service.  Implement the following logic in your JSP page.

adResponse = adCall.FindAddressLines(line1, line2, line3, line4, line5, line6, line7, line8, line9, line10);
        
if (adResponse.getError() != null){
    %> 
    <br/><h3>Address Detective - FindOutlyingAddress Error!</h3>
    <table border='1' width="450" cellspacing="4" cellpadding="4" >
    <tr><td>Desc:</td><td><%out.println(adResponse.getError().getDesc());%></td></tr>
    <tr><td>DescCode:</td><td><%out.println(adResponse.getError().getDescCode());%></td></tr>
    <tr><td>Type:</td><td><%out.println(adResponse.getError().getType());%></td></tr>
    <tr><td>TypeCode:</td><td><%out.println(adResponse.getError().getTypeCode());%></td></tr>
    <tr><td colspan="2" ><input type ="button" value="Start Over" onClick="document.location='inputForm.jsp';"></td></tr>
    </table>
    <%
}
else{
    %>
    <br/><h3>FindAddressLines Results</h3>
    <table border='1' width="450" cellspacing="4" cellpadding="4" >
    <tr><td>Address:</td><td><%out.println(adResponse.getAddresses()[0].getAddress());%></td></tr>
    <tr><td>City:</td><td><%out.println(adResponse.getAddresses()[0].getCity());%></td></tr>
    <tr><td>State:</td><td><%out.println(adResponse.getAddresses()[0].getState());%></td></tr>
    <tr><td>Zip:</td><td><%out.println(adResponse.getAddresses()[0].getZip());%></td></tr>
    <tr><td>DPV:</td><td><%out.println(adResponse.getAddresses()[0].getDPV());%></td></tr>
    <tr><td>DPVDesc:</td><td><%out.println(adResponse.getAddresses()[0].getDPVDesc());%></td></tr>
    <tr><td>DPVNotes:</td><td><%out.println(adResponse.getAddresses()[0].getDPVNotes());%></td></tr>
    <tr><td>DPVNotesDesc:</td><td><%out.println(adResponse.getAddresses()[0].getDPVNotesDesc());%></td></tr>
    <tr><td>Corrections:</td><td><%out.println(adResponse.getAddresses()[0].getCorrections());%></td></tr>
    <tr><td>CorrectionsDesc:</td><td><%out.println(adResponse.getAddresses()[0].getCorrectionsDesc());%></td></tr>
    <tr><td>BarcodeDigits:</td><td><%out.println(adResponse.getAddresses()[0].getBarcodeDigits());%></td></tr>
    <tr><td>CarrierRoute:</td><td><%out.println(adResponse.getAddresses()[0].getCarrierRoute());%></td></tr>
    <tr><td>CongressCode:</td><td><%out.println(adResponse.getAddresses()[0].getCongressCode());%></td></tr>
    <tr><td>CountyCode:</td><td><%out.println(adResponse.getAddresses()[0].getCountyCode());%></td></tr>
    <tr><td>CountyName:</td><td><%out.println(adResponse.getAddresses()[0].getCountyName());%></td></tr>
    <tr><td>FragmentHouse:</td><td><%out.println(adResponse.getAddresses()[0].getFragmentHouse());%></td></tr>
    <tr><td>FragmentPreDir:</td><td><%out.println(adResponse.getAddresses()[0].getFragmentPreDir());%></td></tr>
    <tr><td>FragmentStreet:</td><td><%out.println(adResponse.getAddresses()[0].getFragmentStreet());%></td></tr>
    <tr><td>FragmentSuffix:</td><td><%out.println(adResponse.getAddresses()[0].getFragmentSuffix());%></td></tr>
    <tr><td>FragmentPostDir:</td><td><%out.println(adResponse.getAddresses()[0].getFragmentPostDir());%></td></tr>
    <tr><td>FragmentUnit:</td><td><%out.println(adResponse.getAddresses()[0].getFragmentUnit());%></td></tr>
    <tr><td>Fragment:</td><td><%out.println(adResponse.getAddresses()[0].getFragment());%></td></tr>
    <tr><td>FragmentPMBPrefix:</td><td><%out.println(adResponse.getAddresses()[0].getFragmentPMBPrefix());%></td></tr>
    <tr><td>FragmentPMBNumber:</td><td><%out.println(adResponse.getAddresses()[0].getFragmentPMBNumber());%></td></tr>
    <tr><td colspan="2" ><input type ="button" value="Start Over" onClick="document.location='inputForm.jsp';"></td></tr>
    </table>
    <%
}

}
catch (Exception ex){
    System.out.println(ex);        
}

%>

This code will first check if an error is present in the response; if it is present it will display that error to the screen. If the error response is null, it will display the validated response from the service.  Notice that we call the “getters” that we have previously defined in our response class to display the results to the user.

We now have everything we need to use the service, let’s see it in action!

As mentioned previously, the FindAddressLines operation can take the inputs for an address in any order and return the validated output address.  See below for an example.

After we send that input to the service, we will receive this response:

You are now all set to test the FindAddressLines operation in the DOTS Address Detective web service. Sample code downloads are also available for all of our other services. As always if you have any questions about integrations, service behavior or best practices, feel free to contact us and we will gladly assist in any way that we can!

One of our primary goals as Application Engineers at Service Objects, is to do whatever we can to ensure that clients and prospective clients get up and running with their DOTS validation service and programming language of choice. That’s why we have over 250 different pieces of sample code available to those who want to test our services!

But what if you are interested in integrating multiple services in your application?

Lucky for you, this commitment to getting the data hungry masses up and running with testing our services goes even further. We are dedicated to ensuring that you get the most out of the service(s) that you are testing and assisting with any integration related questions. One of the ways we do this is by writing custom sample code to help our clients and prospective clients integrate our services into their business logic.

What are some examples of custom sample code?

Well I am glad you asked! Need some sample code that will run our NCOA service against 500,000 addresses in a couple hours? No problem.  Do you want to get geocode

coordinates from the contact address that comes back from our DOTS Geophone Plus 2? We’ll write you some sample code that will get that done. Does a portion of your address data include a PO Box number reflected as the unit or suite? We can help you leverage the results from our DOTS Address Validation 3 service to programmatically identify those records.  Need to use any of our DOTS validation products with asynchronous calls? We can certainly help with that as well.

There are a multitude of other combinations that our services can be used to get you your desired result! If you’re interested in any DOTS validation products and need some assistance in how to get the intended result, please reach out to us here! We will gladly provide a consultation on how to best integrate your service (or services) of choice into your application or we’ll go ahead and write a piece of sample code for you to illustrate best practices when calling a DOTS validation web service.

Python is a versatile, robust scripting language that can be used for a variety of projects and implementations. One thing that separates Python from other programming languages is its use of white space and indentations to separate different blocks of code rather than curly braces that languages like Java or C# use. This can often be a polarizing issue for many developers but it is simple enough to start using once you have some experience in it. For this tutorial we’re going to look into making a RESTful web service call to our DOTS Phone Exchange 2 service to validate an international phone number. You will need the following to participate in this tutorial.

What you’ll need

• Python Installed on your Test Machine(2.7.11 is used in this version)
• IDE or Text editor of choice. We’re using the community edition of PyCharm.
• A DOTS product License key of choice. We’re DOTS Phone Exchange 2 for this example.

Once you have all the necessary prerequisites installed, Launch PyCharm and create a new project in your directory of choice. Once you have a project created right click on the project location in the solution and select “New” and then “Python File.”

For this project we will use the following modules that we are importing at the top of the .py file. The “Tkinter” module will allow us to have a simple GUI to allow the user to enter phone number Information to be validated. The “Tix” module allows us to use some handy labels, scrollbars and buttons to properly display the outputs from the service, and the “requests” and “xmltodict” modules will allow us to make a HTTP Get call and parse the results in the a Python dictionary respectively.

To add these modules in PyCharm you will need to go into settings from the File menu. Select Project:, and then select Project Interpreter.  Click the small green plus symbol in the upper right-hand corner and from there you can search for and install the necessary modules to run this project.

Now that we have all the necessary modules in place, let’s create a method that will eventually make the HTTP Get call. For now we will leave it empty as shown below.

There is nothing very exciting happening in that method at the moment, but we’re certainly going to change that.  We’ll now create the elements necessary to take in the values that will create a successful call to the GetInternationalExchangeInfo operation for the DOTS Phone Exchange 2 web service.  The service takes in 3 values as an input: PhoneNumber, Country and Licensekey.  To create the necessary input elements, add the following bits of code to your python file below the method definition.

This will give our GUI a title, and 3 text boxes so that we can enter the necessary information to validate an international phone number. Notice at the bottom that once the button gets pressed, it will call the PE2Int method which we have defined right above this code. Since we have the user interface all set up, we can go ahead and enter the code that will make the actual call to the web service and then display the results to the user.

Web Service Call and Fail Over Configuration

For starters, we’ll take inputs that a user will enter in the text boxes in the GUI and also instantiate the beginning part of the URL that we’ll be using to make a web service call. Additionally, we’ll utilize a feature of the “requests” module that allows the user to format the query string items in the URL in a more readable way. See below for the example.  Our new code will also have a “primaryURL” and “backupURL” string which we’ll talk about more when we get to implementing proper failover into the project.  Add the following code to the program under the primary method.

The project will now implement a few try/catch blocks that will call the DOTS Phone Exchange 2 web service and handle any potential errors that come up during the call to the web service. In this basic bit of code, we show how to call the service using the “requests” module and how to properly failover to another datacenter in the event that the primary Service Objects data center is not responding as intended.

As shown above, the code will call the primaryURL and then process the response depending on the results returned from the service. If an error code is returned and a TypeCode of “3” is returned the code will throw an exception, and then call the backupURL to receive a valid response from the service. A TypeCode of “3” indicates that something has gone wrong with the service and that it is throwing an “Unhandled Error.”

Proper error checking and failover implementation should be used to ensure that your business logic goes uninterrupted and can continue to be used in the event that the primary Service Objects data center is offline or not behaving as expected.

Displaying the Results to the User

Now that our fail over configuration is properly set up, we can work on displaying the results to the user. To do this we’ll create Label’s using the Tix module that will simply allow us to show the values that are returned from the service. To do this, make statements in the primary call and back up call section of the code resembling the following.

Now it’s time for testing!  For this example we’re using a the phone number to a Hotel in Germany, but feel free to test any phone number you would like! This operation will also validate phone numbers from the US and Canada as well. Here is an example of the sample output from the service.

This concludes our python tutorial. Please contact support with any questions or tutorial requests!

C# may very well be our most requested sample code.  There is good reason for that too; C# and the .NET framework are many developer’s first choice for creating a web page or any other type of application because of the versatility of the language and framework as well as the robust features that Visual Studio offers.  One of those features is the ability to consume a WSDL (Web Services Description Language) and create all the necessary classes and methods to successfully call a web service.  This makes using SOAP squeaky clean! Ok, that was the first and last SOAP pun, I promise.  Here’s what you will need for this tutorial.

Requirements

• Visual Studio (2015 is used in this tutorial but the process should be relatively similar with any other version)
• DOTS Web Service License Key (We are using DOTS Address Validation International for this example)
• Some familiarity with C# and the .NET Framework. This tutorial will be pretty basic so it should be accessible even if you are a beginner.

Setting Up the Visual Studio Project

For starters, launch Visual Studio and create a new ASP.NET Web Application and choose an appropriate project name. Your screen should look similar to the following:

Click ok and then select “Empty” to create an empty web form. We will add the necessary aspx page momentarily.

But, our first step for our new project will be to add the service reference to the DOTS Address Validation International web service. To do this, right-click on “References” in the Solution Explorer and select “Add Service Reference” a pop up should appear to add the Service Reference.  Here we will add the URL to WSDL that contains the information on how the project should interact with the DOTS Address Validation International web service and we will name the Service Reference.

For reference here is the WSDL URL and here is what the pop up page should look like

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

Now that we have successfully added the service reference, we can add an aspx page that will have our input form and display our results. Right click the project name and select “Add” and then select “Web Form” to add a blank web form to the project.  For our example we’ll name the form “AVIForm”.

Creating the Input Form and Code Behind

Now that our form is present, we’ll add some simple HTML and ASP elements to take in our inputs and display them to the screen after we get a response from the service. Make your ASPX page look like the following.

The above code will allow us to take the inputs send them to the code behind and the display the results in the outputGrid and InformationComponentsGrid.  We have to separate grids; one to account for the standard outputs from the service, and the other to account for the InformationComponents field to account for some variable information and data to be returned by the service.  This field can change based on the country or data available for a specific international address. Now that our input form is all set up, we’ll add the proper code behind that will display the results to the user.

We won’t look at every part of the code here, to download a .txt version of the code, click here.

One thing we like to stress to clients who are integrating our services is proper Failover Configuration.  In the unlikely event that our primary datacenters are offline or producing strange errors, we want to ensure that our clients are pointing their code to our backup datacenters so that their applications and business processes go uninterrupted.  Here is a full picture of the proper way to integrate failover into an application.

We’ve found that to ensure uninterrupted service the best practice is to have the calls to the web service nested in a try-catch block of code.  In our current setup, the backup call will hit the same data center as the primary call; but if a License Key is purchased the primary call should point to ws.serviceobjects.com and the backup call should point wsbackup.serviceobjects.com.   The screen shot below, highlights some of the primary failover logic that will allow the code to run uninterrupted.

This code occurs right after the primary call to the web service if it detects that the response from the service is null or if an Error TypeCode of “3” is returned, then the code will throw a new exception and the catch statement will call the backup web service call.

If a successful response is received from the service, the code will call a method named “ProcessValidResponse” which takes in the response from the web service and display the results into a DataGrid and then send that data grid to the ASPX page for the user to see. This method is pretty straight forward for the most part, as it simply assigns the outputs and their respective values into separate columns for the user to see.

The only part that may be mildy tricky would be the InformationComponents field that is returned from the service.  This field is an array of InformationComponent which contains two strings; one for the “Name” of the variable returned and one that indicates the “Value” of the variable returned.  For example is you pass a US address into the AVI service, one InformationComponent that can be returned will have a Name of “DPV” and a Value of “1” indicating that it is considered delivered by the USPS.  Below is an example of the XML output.

 

This array of fields allows us to add new outputs to the service over time without potentially breaking any existing client’s code.  To account for this array of information we have a brief For loop below that will loop through all the elements of InformationComponents and add their names and values to the InfoCompTable so that they can be seen by the user.

Making a Successful Call to the Service

If we go ahead and run our project, our webpage will look like the following.

Not very exciting, but it will get the job done. As an example address, we’ll use the following in France:

3 Place de la Victoire, 33000 Bordeaux, France

If this address is sent to the service you should see the following response.

As you can see, this address is considered Valid by the service and the service has a premise level resolution for this address.  The Address1-Address8 fields will also display how the address should look for mailing purposes. For this particular example we only need Address1 and Address2 but for other countries all 8 address lines may be used.  The InformationComponents field was also parsed out and the two Name and Value pairs were shown below the standard outputs from the service.

That wraps up our tutorial for DOTS AVI integration in C#.  Congratulations! You are now on your way to being a DOTS Address Validation International expert! Feel free to go and test more International addresses, and as always if you have any questions feel free to reach out to us at support@serviceobjects.com!