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


Introduction

DOTS Address Insight ("AIN") is a publicly available XML web service that provides comprehensive address validation, location identification and appends demographic metadata information about a location in the US. The service provides validated, standardized and parsed address information, geocoding information, demographics information and other useful insights about an address in the United States. A Status score is returned giving users an indication of how likely it is that the location exists especially useful for those out of the way rural addresses that may be hard to identify with a normal USPS database. Address Insight 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.


Integration

Integrating AIN 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:

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.

AIN is a public XML web service that supports SOAP, POST and GET operations, using RESTful paradigms or simple HTTP transport calls.

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

A test page for the web service can be found here:
https://trial.serviceobjects.com/AIN/ 

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/AIN/soap.svc?wsdl

Important Notes!
1. 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 ADI, you can provide this one.

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

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


Code Snippets




Address Insight - US C# Code Snippet
 public partial class AIN_Form : System.Web.UI.Page
    {
        const string TrialURL = "http://trial.serviceobjects.com/ain/soap.svc/SOAP";
        // A trial license key is not compatible with the backup datacenter.  
        // The backup url is provided with a production license key.
        const string BackupURL = "http://trial.serviceobjects.com/ain/soap.svc/SOAP";
        protected void Page_Load(object sender, EventArgs e)
        {
            ErrorLabel.Visible = false;
        }
        protected void btn_Validate_Click(object sender, EventArgs e)
        {
            try
            {
                AIN.ResponseObject response = GetAddressInsight();
                PrintResponse(response);
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = ex.Message;
            }
        }
        protected AIN.ResponseObject GetAddressInsight()
        {
            AIN.ResponseObject Response = null;

            try
            {
                using (AIN.SOAPClient Client = new AIN.SOAPClient())
                {
                    // Implement Failover logic here
                    try
                    {
                        Client.Endpoint.Address = new System.ServiceModel.EndpointAddress(TrialURL);
                        Response = Client.GetAddressInsight(BusinessName.Text,
                                                            Address1.Text,
                                                            Address2.Text,
                                                            City.Text,
                                                            State.Text,
                                                            Zip.Text,
                                                            TestType.Text,
                                                            inputLicenseKey.Text);
                    }
                    catch (WebException)
                    {
                        Client.Endpoint.Address = new System.ServiceModel.EndpointAddress(BackupURL);
                        Response = Client.GetAddressInsight(BusinessName.Text,
                                                            Address1.Text,
                                                            Address2.Text,
                                                            City.Text,
                                                            State.Text,
                                                            Zip.Text,
                                                            TestType.Text,
                                                            inputLicenseKey.Text);
                    }
                    catch (CommunicationException)
                    {
                        Client.Abort();
                    }
                    catch (TimeoutException)
                    {
                        Client.Abort();
                    }
                    catch (Exception Ex)
                    {
                        Client.Abort();
                    }
                }
            }
            catch (Exception)
            {
                // throw;
            }
            return Response;
        }
        protected void PrintResponse(AIN.ResponseObject response)
        {
            DataTable dtProvider = new DataTable();
            //Proccess result
            //We just output it here but this would be a good place to save data
            //to a database or send an email etc.
            dtProvider.Columns.Add(new DataColumn("Output", typeof(string)));
            dtProvider.Columns.Add(new DataColumn("Values", typeof(string)));
            if (response.ContainsKey("AddressInsightResponse"))
            {
                AIN.ResultObject ro = response["AddressInsightResponse"];
                //Loop through the fields
                /*
                foreach (string Key in ro[0].Keys)
                {
                    dtProvider.Rows.Add(Key, ro[0][Key]);
                }
                */
                //Or access the fields directly.
                dtProvider.Rows.Add("Status", ro[0].ContainsKey("Status") ? ro[0]["Status"] : "");
                dtProvider.Rows.Add("StatusScore", ro[0].ContainsKey("StatusScore") ? ro[0]["StatusScore"] : "");
                dtProvider.Rows.Add("AddressStatus", ro[0].ContainsKey("AddressStatus") ? ro[0]["AddressStatus"] : "");
                dtProvider.Rows.Add("DPV", ro[0].ContainsKey("DPV") ? ro[0]["DPV"] : "");
                dtProvider.Rows.Add("DPVDesc", ro[0].ContainsKey("DPVDesc") ? ro[0]["DPVDesc"] : "");
                .
				.
				.
                dtProvider.Rows.Add("ZipHouseholdIncome", ro[0].ContainsKey("ZipHouseholdIncome") ? ro[0]["ZipHouseholdIncome"] : "");
                dtProvider.Rows.Add("CountyHouseholdIncome", ro[0].ContainsKey("CountyHouseholdIncome") ? ro[0]["CountyHouseholdIncome"] : "");
                dtProvider.Rows.Add("StateHouseholdIncome", ro[0].ContainsKey("StateHouseholdIncome") ? ro[0]["StateHouseholdIncome"] : "");
                dtProvider.Rows.Add("ZipNotes", ro[0].ContainsKey("ZipNotes") ? ro[0]["ZipNotes"] : "");
                dtProvider.Rows.Add("ZipNotesCodes", ro[0].ContainsKey("ZipNotesCodes") ? ro[0]["ZipNotesCodes"] : "");
            }
            else
            {
                if (response.ContainsKey("Error"))
                {
                    AIN.ResultObject roError = response["Error"];
                    //Loop throught he fields
                    /*
                    foreach (string Key in roError[0].Keys)
                    {
                        dtProvider.Rows.Add(Key, roError[0][Key]);
                    }
                    */
                    //Or access the fields directly.
                    dtProvider.Rows.Add("Type", roError[0].ContainsKey("Type") ? roError[0]["Type"] : "");
                    dtProvider.Rows.Add("TypeCode", roError[0].ContainsKey("TypeCode") ? roError[0]["TypeCode"] : "");
                    dtProvider.Rows.Add("Desc	", roError[0].ContainsKey("Desc	") ? roError[0]["Desc	"] : "");
                    dtProvider.Rows.Add("DescCode", roError[0].ContainsKey("DescCode") ? roError[0]["DescCode"] : "");
                }
            }
            ResultGrid.DataSource = new DataView(dtProvider);
            ResultGrid.DataBind();
        }
    }


Address Insight - US Java Code Snippet
		String businessName = request.getParameter("businessName");
        String address1 = request.getParameter("address1");
        String address2 = request.getParameter("address2");
        String city = request.getParameter("city");
        String state = request.getParameter("state");
        String zip = request.getParameter("zip");
        String testType = request.getParameter("testType");
        String licenseKey = request.getParameter("licensekey");
        
        //Creating the soap client
        SOAP soap = new SOAP();
        
        ISOAP client = soap.getAddressInsightSOAP();
        
        ResponseObject addressPlus;
        
        //Call the web service 
        try{
            addressPlus = client.getAddressInsight(businessName, address1, address2, city, state, zip, testType, licenseKey); 
        }catch(Exception ex){
            //Create a backup client if an exception is thrown
            ISOAP backupClient = soap.getAddressInsightSOAP();
            addressPlus = backupClient.getAddressInsight(businessName, address1, address2, city, state, zip, testType, licenseKey); 
        }
        
        List<ResponseObject.Response> responses = addressPlus.getResponse();
            %>
            <H2>Service Response</H2>
            <table>
            <%
            for(ResponseObject.Response res : responses){
                ResultObject resList = res.getValue();
                String resultKey = res.getKey();
                %>
                    <tr>
                        <td><b><%=resultKey%></b></td>
                    </tr>
                <%
                List<FieldObject> results = resList.getResult();
                for(FieldObject result : results){
                    List<FieldObject.Field> fields = result.getField();
                    for(FieldObject.Field kvp : fields){
                        String key = kvp.getKey();
                        String value = kvp.getValue();
                    %>
                    <tr>
                        <td><%=key%></td>
                        <td><%=value%></td>
                    </tr>
                    <%
                        
                    }
                }
            }



Address Insight - US C# Code Snippet
            protected void btn_Validate_Click(object sender, EventArgs e)
        {
            string businessName, address1, address2, city, state, zip, testType, licenseKey;
            businessName = BusinessName.Text; address1 = Address1.Text; address2 = Address2.Text;
            city = City.Text; state = State.Text; zip = Zip.Text;
            testType = TestType.Text; licenseKey = inputLicenseKey.Text;
            try
            {
                if (String.IsNullOrWhiteSpace(licenseKey))
                    licenseKey = "yourDevKey";
                AINResponse response = MakeRequest(businessName, address1, address2, city, state, zip, testType, licenseKey);
                ProcessResponse(response);
            }
            catch (Exception ex)
            {
                ErrorLabel.Text = ex.Message;
                ErrorLabel.Visible = true;
            }
        }
        public static AINResponse MakeRequest(string businessName, string address1, string address2, string city, string state, string zip, string testType, string licenseKey)
        {
            string mainURL = WEB_SERVICE_PRIMARY_URL + "?BusinessName=" + businessName + "&Address1=" + address1 + "&Address2=" + address2 + "&City=" + city + "&State=" + state + "&Zip=" + zip + "&TestType="+ testType + "&LicenseKey=" + licenseKey;
            string backupURL = WEB_SERVICE_BACKUP_URL + "?BusinessName=" + businessName + "&Address1=" + address1 + "&Address2=" + address2 + "&City=" + city + "&State=" + state + "&Zip=" + zip + "&TestType=" + testType + "&LicenseKey=" + licenseKey;
            AINResponse result = null;

            try
            {
                result = HttpGet(mainURL);
                //NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP 
                if (result == null || (result.error != null && result.error.TypeCode == "3"))
                {
                    return HttpGet(backupURL);
                }
                else
                {
                    return result;
                }
            }
            catch (Exception)
            {   //ERROR IN MAIN URL - USING BACKUP
                return HttpGet(backupURL);
            }
        }
        public static AINResponse 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(AINResponse));
                    object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
                    AINResponse jsonResponse = objResponse as AINResponse;
                    return jsonResponse;
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        private void ProcessResponse(AINResponse response)
        {
            try
            {
                //processing result
                if (response.error == null)
                {
                    ProcessResult(response);
                }
                //processing error
                else
                {
                    ProcessError(response.error);
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        private void ProcessResult(AINResponse response)
        {
            DataTable dtProvider = new DataTable();
            dtProvider.Columns.Add(new DataColumn("Output", typeof(string)));
            dtProvider.Columns.Add(new DataColumn("Values", typeof(string)));
            try
            {
                dtProvider.Rows.Add("Status", response.Status);
                dtProvider.Rows.Add("StatusScore", response.StatusScore);
                dtProvider.Rows.Add("AddressStatus", response.AddressStatus);
                dtProvider.Rows.Add("DPV", response.DPV);
                dtProvider.Rows.Add("DPVDesc", response.DPVDesc);
                ...
                dtProvider.Rows.Add("GeocodeStatus", response.GeocodeStatus);
                dtProvider.Rows.Add("LocationLatitude", response.LocationLatitude);
                dtProvider.Rows.Add("LocationLongitude", response.LocationLongitude);
                ...
                dtProvider.Rows.Add("CityType", response.CityType);
                dtProvider.Rows.Add("CityAliasName", response.CityAliasName);
                dtProvider.Rows.Add("AreaCode", response.AreaCode);
                dtProvider.Rows.Add("TimeZone", response.TimeZone);
                dtProvider.Rows.Add("DaylightSaving", response.DaylightSaving);
                ...
                dtProvider.Rows.Add("StateHouseholdIncome", response.StateHouseholdIncome);
                dtProvider.Rows.Add("ZipNotes", response.ZipNotes);
                dtProvider.Rows.Add("ZipNotesCodes", response.ZipNotesCodes);
                ResultGrid.Visible = true;
                ErrorGrid.Visible = false;
                ResultGrid.DataSource = new DataView(dtProvider);
                ResultGrid.DataBind();
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        private void ProcessError(Error error)
        {
            try
            {
                DataTable dtError = new DataTable();
                
                dtError.Columns.Add(new DataColumn("Output", typeof(string)));
                dtError.Columns.Add(new DataColumn("Values", typeof(string)));
                dtError.Rows.Add("Type", string.IsNullOrEmpty(error.Type) ? "" : error.Type);
                dtError.Rows.Add("TypeCode", string.IsNullOrEmpty(error.TypeCode) ? "" : error.TypeCode);
                dtError.Rows.Add("Desc", string.IsNullOrEmpty(error.Desc) ? "" : error.Desc);
                dtError.Rows.Add("DescCode", string.IsNullOrEmpty(error.DescCode) ? "" : error.DescCode);

                ErrorGrid.Visible = true;
                ResultGrid.Visible = false;
                ErrorGrid.DataSource = new DataView(dtError);
                ErrorGrid.DataBind();
            }
            catch (Exception e)
            {
                throw e;
            }
        }


String businessName = request.getParameter("businessName");
String address1 = request.getParameter("address1");
String address2 = request.getParameter("address2");
String city = request.getParameter("city");
String state = request.getParameter("state");
String zip = request.getParameter("zip");
String testType = request.getParameter("testType");
String licenseKey = request.getParameter("licensekey");

businessName = URLEncoder.encode(businessName,"UTF-8").replaceAll("\\+", "%20");
address1 = URLEncoder.encode(address1,"UTF-8").replaceAll("\\+", "%20");
address2 = URLEncoder.encode(address2,"UTF-8").replaceAll("\\+", "%20");
city = URLEncoder.encode(city,"UTF-8").replaceAll("\\+", "%20");
state = URLEncoder.encode(state,"UTF-8").replaceAll("\\+", "%20");
zip = URLEncoder.encode(zip,"UTF-8").replaceAll("\\+", "%20");
testType = URLEncoder.encode(testType,"UTF-8").replaceAll("\\+", "%20");
licenseKey = URLEncoder.encode(licenseKey,"UTF-8").replaceAll("\\+", "%20");

String mainURL = "https://trial.serviceobjects.com/AIN/api.svc/json/GetAddressInsight?BusinessName=" + businessName + "&Address1=" + address1 + "&Address2=" + address2 + "&City=" + city + "&State=" + state + "&Zip=" + zip + "&TestType=" + testType + "&LicenseKey=" + licenseKey;
String backupURL = "https://trial.serviceobjects.com/AIN/api.svc/json/GetAddressInsight?BusinessName=" + businessName + "&Address1=" + address1 + "&Address2=" + address2 + "&City=" + city + "&State=" + state + "&Zip=" + zip + "&TestType=" + testType + "&LicenseKey=" + licenseKey;
URL url = null;
HttpsURLConnection conn = null;
Gson gson = new GsonBuilder().setPrettyPrinting().disableHtmlEscaping().create();
String responseString = "";
String prettyjson = "";
try{
url = new URL(mainURL);
conn = (HttpsURLConnection) url.openConnection();
conn.setConnectTimeout(10000);
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");

if (conn.getResponseCode() != 200) {
throw new RuntimeException("Failed : HTTP error code : " + conn.getResponseCode());
}

BufferedReader br = new BufferedReader(new InputStreamReader(
(conn.getInputStream())));
String output;
while ((output = br.readLine()) != null) {
responseString += output;
}

JsonParser parser = new JsonParser();
JsonObject json = parser.parse(responseString).getAsJsonObject();

prettyjson = gson.toJson(json);

} catch (Exception ex) {
//call the backup client
url = new URL(backupURL);
conn = (HttpsURLConnection) url.openConnection();
conn.setConnectTimeout(10000);
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");

if (conn.getResponseCode() != 200) {
throw new RuntimeException("Failed : HTTP error code : " + conn.getResponseCode());
}

BufferedReader br = new BufferedReader(new InputStreamReader(
(conn.getInputStream())));
String output;
while ((output = br.readLine()) != null) {
responseString += output;
}

JsonParser parser = new JsonParser();
JsonObject json = parser.parse(responseString).getAsJsonObject();

prettyjson = gson.toJson(json);
}



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

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

C#
using System;
using System.Collections.Generic;
using System.Data;
using System.Linq;
using System.Net;
using System.ServiceModel;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
namespace AIN_C_Sharp_SOAP
{
    public partial class AIN_Form : System.Web.UI.Page
    {
        const string TrialURL = "http://trial.serviceobjects.com/ain/soap.svc/SOAP";
        // A trial license key is not compatible with the backup datacenter.  
        // The backup url is provided with a production license key.
        const string BackupURL = "http://trial.serviceobjects.com/ain/soap.svc/SOAP";
        protected void Page_Load(object sender, EventArgs e)
        {
            ErrorLabel.Visible = false;
        }
        protected void btn_Validate_Click(object sender, EventArgs e)
        {
            try
            {
                AIN.ResponseObject response = GetAddressInsight();
                PrintResponse(response);
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = ex.Message;
            }
        }
        protected AIN.ResponseObject GetAddressInsight()
        {
            AIN.ResponseObject Response = null;

            try
            {
                using (AIN.SOAPClient Client = new AIN.SOAPClient())
                {
                    // Implement Failover logic here
                    try
                    {
                        Client.Endpoint.Address = new System.ServiceModel.EndpointAddress(TrialURL);
                        Response = Client.GetAddressInsight(BusinessName.Text,
                                                            Address1.Text,
                                                            Address2.Text,
                                                            City.Text,
                                                            State.Text,
                                                            Zip.Text,
                                                            TestType.Text,
                                                            inputLicenseKey.Text);
                    }
                    catch (WebException)
                    {
                        Client.Endpoint.Address = new System.ServiceModel.EndpointAddress(BackupURL);
                        Response = Client.GetAddressInsight(BusinessName.Text,
                                                            Address1.Text,
                                                            Address2.Text,
                                                            City.Text,
                                                            State.Text,
                                                            Zip.Text,
                                                            TestType.Text,
                                                            inputLicenseKey.Text);
                    }
                    catch (CommunicationException)
                    {
                        Client.Abort();
                    }
                    catch (TimeoutException)
                    {
                        Client.Abort();
                    }
                    catch (Exception Ex)
                    {
                        Client.Abort();
                    }
                }
            }
            catch (Exception)
            {
                // throw;
            }
            return Response;
        }
        protected void PrintResponse(AIN.ResponseObject response)
        {
            DataTable dtProvider = new DataTable();
            //Proccess result
            //We just output it here but this would be a good place to save data
            //to a database or send an email etc.
            dtProvider.Columns.Add(new DataColumn("Output", typeof(string)));
            dtProvider.Columns.Add(new DataColumn("Values", typeof(string)));
            if (response.ContainsKey("AddressInsightResponse"))
            {
                AIN.ResultObject ro = response["AddressInsightResponse"];
                //Loop through the fields
                /*
                foreach (string Key in ro[0].Keys)
                {
                    dtProvider.Rows.Add(Key, ro[0][Key]);
                }
                */
                //Or access the fields directly.
                dtProvider.Rows.Add("Status", ro[0].ContainsKey("Status") ? ro[0]["Status"] : "");
                dtProvider.Rows.Add("StatusScore", ro[0].ContainsKey("StatusScore") ? ro[0]["StatusScore"] : "");
                dtProvider.Rows.Add("AddressStatus", ro[0].ContainsKey("AddressStatus") ? ro[0]["AddressStatus"] : "");
                dtProvider.Rows.Add("DPV", ro[0].ContainsKey("DPV") ? ro[0]["DPV"] : "");
                dtProvider.Rows.Add("DPVDesc", ro[0].ContainsKey("DPVDesc") ? ro[0]["DPVDesc"] : "");
                dtProvider.Rows.Add("Address", ro[0].ContainsKey("Address") ? ro[0]["Address"] : "");
                dtProvider.Rows.Add("AddressExtra", ro[0].ContainsKey("AddressExtra") ? ro[0]["AddressExtra"] : "");
                dtProvider.Rows.Add("City", ro[0].ContainsKey("City") ? ro[0]["City"] : "");
                dtProvider.Rows.Add("State", ro[0].ContainsKey("State") ? ro[0]["State"] : "");
                dtProvider.Rows.Add("Zip", ro[0].ContainsKey("Zip") ? ro[0]["Zip"] : "");
                dtProvider.Rows.Add("BarcodeDigits", ro[0].ContainsKey("BarcodeDigits") ? ro[0]["BarcodeDigits"] : "");
                dtProvider.Rows.Add("CarrierRoute", ro[0].ContainsKey("CarrierRoute") ? ro[0]["CarrierRoute"] : "");
                dtProvider.Rows.Add("CongressCode", ro[0].ContainsKey("CongressCode") ? ro[0]["CongressCode"] : "");
                dtProvider.Rows.Add("CountyName", ro[0].ContainsKey("CountyName") ? ro[0]["CountyName"] : "");
                dtProvider.Rows.Add("FragmentHouse", ro[0].ContainsKey("FragmentHouse") ? ro[0]["FragmentHouse"] : "");
                dtProvider.Rows.Add("FragmentPreDir", ro[0].ContainsKey("FragmentPreDir") ? ro[0]["FragmentPreDir"] : "");
                dtProvider.Rows.Add("FragmentStreet", ro[0].ContainsKey("FragmentStreet") ? ro[0]["FragmentStreet"] : "");
                dtProvider.Rows.Add("FragmentSuffix", ro[0].ContainsKey("FragmentSuffix") ? ro[0]["FragmentSuffix"] : "");
                dtProvider.Rows.Add("FragmentPostDir", ro[0].ContainsKey("FragmentPostDir") ? ro[0]["FragmentPostDir"] : "");
                dtProvider.Rows.Add("FragmentUnit", ro[0].ContainsKey("FragmentUnit") ? ro[0]["FragmentUnit"] : "");
                dtProvider.Rows.Add("FragmentUnitNumber", ro[0].ContainsKey("FragmentUnitNumber") ? ro[0]["FragmentUnitNumber"] : "");
                dtProvider.Rows.Add("FragmentPMBPrefix", ro[0].ContainsKey("FragmentPMBPrefix") ? ro[0]["FragmentPMBPrefix"] : "");
                dtProvider.Rows.Add("FragmentPMBNumber", ro[0].ContainsKey("FragmentPMBNumber") ? ro[0]["FragmentPMBNumber"] : "");
                dtProvider.Rows.Add("Corrections", ro[0].ContainsKey("Corrections") ? ro[0]["Corrections"] : "");
                dtProvider.Rows.Add("CorrectionsDesc", ro[0].ContainsKey("CorrectionsDesc") ? ro[0]["CorrectionsDesc"] : "");
                dtProvider.Rows.Add("AddressNotes", ro[0].ContainsKey("AddressNotes") ? ro[0]["AddressNotes"] : "");
                dtProvider.Rows.Add("AddressNotesCodes", ro[0].ContainsKey("AddressNotesCodes") ? ro[0]["AddressNotesCodes"] : "");
                dtProvider.Rows.Add("GeocodeStatus", ro[0].ContainsKey("GeocodeStatus") ? ro[0]["GeocodeStatus"] : "");
                dtProvider.Rows.Add("LocationLatitude", ro[0].ContainsKey("LocationLatitude") ? ro[0]["LocationLatitude"] : "");
                dtProvider.Rows.Add("LocationLongitude", ro[0].ContainsKey("LocationLongitude") ? ro[0]["LocationLongitude"] : "");
                dtProvider.Rows.Add("CensusTract", ro[0].ContainsKey("CensusTract") ? ro[0]["CensusTract"] : "");
                dtProvider.Rows.Add("CensusBlock", ro[0].ContainsKey("CensusBlock") ? ro[0]["CensusBlock"] : "");
                dtProvider.Rows.Add("PlaceName", ro[0].ContainsKey("PlaceName") ? ro[0]["PlaceName"] : "");
                dtProvider.Rows.Add("ClassFP", ro[0].ContainsKey("ClassFP") ? ro[0]["ClassFP"] : "");
                dtProvider.Rows.Add("SLDUST", ro[0].ContainsKey("SLDUST") ? ro[0]["SLDUST"] : "");
                dtProvider.Rows.Add("SLDLST", ro[0].ContainsKey("SLDLST") ? ro[0]["SLDLST"] : "");
                dtProvider.Rows.Add("CountyFIPS", ro[0].ContainsKey("CountyFIPS") ? ro[0]["CountyFIPS"] : "");
                dtProvider.Rows.Add("StateFIPS", ro[0].ContainsKey("StateFIPS") ? ro[0]["StateFIPS"] : "");
                dtProvider.Rows.Add("GeocodeNotes", ro[0].ContainsKey("GeocodeNotes") ? ro[0]["GeocodeNotes"] : "");
                dtProvider.Rows.Add("GeocodeNotesCodes", ro[0].ContainsKey("GeocodeNotesCodes") ? ro[0]["GeocodeNotesCodes"] : "");
                dtProvider.Rows.Add("ZipStatus", ro[0].ContainsKey("ZipStatus") ? ro[0]["ZipStatus"] : "");
                dtProvider.Rows.Add("ZipLatitude", ro[0].ContainsKey("ZipLatitude") ? ro[0]["ZipLatitude"] : "");
                dtProvider.Rows.Add("ZipLongitude", ro[0].ContainsKey("ZipLongitude") ? ro[0]["ZipLongitude"] : "");
                dtProvider.Rows.Add("CityType", ro[0].ContainsKey("CityType") ? ro[0]["CityType"] : "");
                dtProvider.Rows.Add("CityAliasName", ro[0].ContainsKey("CityAliasName") ? ro[0]["CityAliasName"] : "");
                dtProvider.Rows.Add("AreaCode", ro[0].ContainsKey("AreaCode") ? ro[0]["AreaCode"] : "");
                dtProvider.Rows.Add("TimeZone", ro[0].ContainsKey("TimeZone") ? ro[0]["TimeZone"] : "");
                dtProvider.Rows.Add("DaylightSaving", ro[0].ContainsKey("DaylightSaving") ? ro[0]["DaylightSaving"] : "");
                dtProvider.Rows.Add("MSA", ro[0].ContainsKey("MSA") ? ro[0]["MSA"] : "");
                dtProvider.Rows.Add("CBSA", ro[0].ContainsKey("CBSA") ? ro[0]["CBSA"] : "");
                dtProvider.Rows.Add("CBSA_Div", ro[0].ContainsKey("CBSA_Div") ? ro[0]["CBSA_Div"] : "");
                dtProvider.Rows.Add("PMSA", ro[0].ContainsKey("PMSA") ? ro[0]["PMSA"] : "");
                dtProvider.Rows.Add("DMA", ro[0].ContainsKey("DMA") ? ro[0]["DMA"] : "");
                dtProvider.Rows.Add("ZipHouseholdValue", ro[0].ContainsKey("ZipHouseholdValue") ? ro[0]["ZipHouseholdValue"] : "");
                dtProvider.Rows.Add("ZipPersonsPerHousehold", ro[0].ContainsKey("ZipPersonsPerHousehold") ? ro[0]["ZipPersonsPerHousehold"] : "");
                dtProvider.Rows.Add("ZipHouseholdIncome", ro[0].ContainsKey("ZipHouseholdIncome") ? ro[0]["ZipHouseholdIncome"] : "");
                dtProvider.Rows.Add("CountyHouseholdIncome", ro[0].ContainsKey("CountyHouseholdIncome") ? ro[0]["CountyHouseholdIncome"] : "");
                dtProvider.Rows.Add("StateHouseholdIncome", ro[0].ContainsKey("StateHouseholdIncome") ? ro[0]["StateHouseholdIncome"] : "");
                dtProvider.Rows.Add("ZipNotes", ro[0].ContainsKey("ZipNotes") ? ro[0]["ZipNotes"] : "");
                dtProvider.Rows.Add("ZipNotesCodes", ro[0].ContainsKey("ZipNotesCodes") ? ro[0]["ZipNotesCodes"] : "");
            }
            else
            {
                if (response.ContainsKey("Error"))
                {
                    AIN.ResultObject roError = response["Error"];
                    //Loop throught he fields
                    /*
                    foreach (string Key in roError[0].Keys)
                    {
                        dtProvider.Rows.Add(Key, roError[0][Key]);
                    }
                    */
                    //Or access the fields directly.
                    dtProvider.Rows.Add("Type", roError[0].ContainsKey("Type") ? roError[0]["Type"] : "");
                    dtProvider.Rows.Add("TypeCode", roError[0].ContainsKey("TypeCode") ? roError[0]["TypeCode"] : "");
                    dtProvider.Rows.Add("Desc	", roError[0].ContainsKey("Desc	") ? roError[0]["Desc	"] : "");
                    dtProvider.Rows.Add("DescCode", roError[0].ContainsKey("DescCode") ? roError[0]["DescCode"] : "");
                }
            }
            ResultGrid.DataSource = new DataView(dtProvider);
            ResultGrid.DataBind();
        }
    }
}



             


FindBestCountry Example Request and Response


URL Request:
https://trial.serviceobjects.com/ain/api.svc/JSON/GetAddressInsight?BusinessName=&Address1=514%20Brinkerhoff&Address2=&City=Santa%20Barbara&State=CA&Zip=93101&TestType=&LicenseKey=[YOURKEY]


Json Response
{"Status":"Valid USPS deliverable address. Street level geo data found. Additional zip area info found. ","StatusScore":"100","AddressStatus":"Success","DPV":"1","DPVDesc":"Yes, the input record is a valid mailing address","Address":"514 Brinkerhoff Ave","AddressExtra":"","City":"Santa Barbara","State":"CA","Zip":"93101-3441","BarcodeDigits":"931013441149","CarrierRoute":"C008","CongressCode":"24","CountyName":"Santa Barbara","FragmentHouse":"514","FragmentPreDir":"","FragmentStreet":"Brinkerhoff","FragmentSuffix":"Ave","FragmentPostDir":"","FragmentUnit":"","FragmentUnitNumber":"","FragmentPMBPrefix":"","FragmentPMBNumber":"","Corrections":"9","CorrectionsDesc":"Directional or Suffix change","AddressNotes":"AddressFoundByUSPS,IsResidence,IsStreetAddress","AddressNotesCodes":"100,121,124","GeocodeStatus":"Success","LocationLatitude":"34.415395","LocationLongitude":"-119.697827","CensusTract":"0010.00","CensusBlock":"3003","PlaceName":"Santa Barbara","ClassFP":"C1","SLDUST":"37","SLDLST":"37","CountyFIPS":"083","StateFIPS":"06","GeocodeNotes":"IsLocationMatch","GeocodeNotesCodes":"110","ZipStatus":"Success","ZipLatitude":"34.41912","ZipLongitude":"-119.703421","CityType":"P","CityAliasName":"SANTA BARBARA","AreaCode":"805","TimeZone":"8","DaylightSaving":"Y","MSA":"7480","CBSA":"42200","CBSA_Div":"","PMSA":"","DMA":"Santa Barbara - Santa Maria - San Luis Obispo","ZipHouseholdValue":"734800","ZipPersonsPerHousehold":"2.49","ZipHouseholdIncome":"53730","CountyHouseholdIncome":"72355","StateHouseholdIncome":"65536","ZipNotes":"CensusDataFoundForZip","ZipNotesCodes":"150"}


XML Request: 
https://trial.serviceobjects.com/ain/api.svc/XML/GetAddressInsight?BusinessName=&Address1=514%20Brinkerhoff&Address2=&City=Santa%20Barbara&State=CA&Zip=93101&TestType=&LicenseKey=[YOURKEY]


XML Response
<AddressInsightResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Status>
Valid USPS deliverable address. Street level geo data found. Additional zip area info found.
</Status>
<StatusScore>100</StatusScore>
<AddressStatus>Success</AddressStatus>
<DPV>1</DPV>
<DPVDesc>Yes, the input record is a valid mailing address</DPVDesc>
<Address>514 Brinkerhoff Ave</Address>
<AddressExtra/>
<City>Santa Barbara</City>
<State>CA</State>
<Zip>93101-3441</Zip>
<BarcodeDigits>931013441149</BarcodeDigits>
<CarrierRoute>C008</CarrierRoute>
<CongressCode>24</CongressCode>
<CountyName>Santa Barbara</CountyName>
<FragmentHouse>514</FragmentHouse>
<FragmentPreDir/>
<FragmentStreet>Brinkerhoff</FragmentStreet>
<FragmentSuffix>Ave</FragmentSuffix>
<FragmentPostDir/>
<FragmentUnit/>
<FragmentUnitNumber/>
<FragmentPMBPrefix/>
<FragmentPMBNumber/>
<Corrections>9</Corrections>
<CorrectionsDesc>Directional or Suffix change</CorrectionsDesc>
<AddressNotes>AddressFoundByUSPS,IsResidence,IsStreetAddress</AddressNotes>
<AddressNotesCodes>100,121,124</AddressNotesCodes>
<GeocodeStatus>Success</GeocodeStatus>
<LocationLatitude>34.415395</LocationLatitude>
<LocationLongitude>-119.697827</LocationLongitude>
<CensusTract>0010.00</CensusTract>
<CensusBlock>3003</CensusBlock>
<PlaceName>Santa Barbara</PlaceName>
<ClassFP>C1</ClassFP>
<SLDUST>37</SLDUST>
<SLDLST>37</SLDLST>
<CountyFIPS>083</CountyFIPS>
<StateFIPS>06</StateFIPS>
<GeocodeNotes>IsLocationMatch</GeocodeNotes>
<GeocodeNotesCodes>110</GeocodeNotesCodes>
<ZipStatus>Success</ZipStatus>
<ZipLatitude>34.41912</ZipLatitude>
<ZipLongitude>-119.703421</ZipLongitude>
<CityType>P</CityType>
<CityAliasName>SANTA BARBARA</CityAliasName>
<AreaCode>805</AreaCode>
<TimeZone>8</TimeZone>
<DaylightSaving>Y</DaylightSaving>
<MSA>7480</MSA>
<CBSA>42200</CBSA>
<CBSA_Div/>
<PMSA/>
<DMA>Santa Barbara - Santa Maria - San Luis Obispo</DMA>
<ZipHouseholdValue>734800</ZipHouseholdValue>
<ZipPersonsPerHousehold>2.49</ZipPersonsPerHousehold>
<ZipHouseholdIncome>53730</ZipHouseholdIncome>
<CountyHouseholdIncome>72355</CountyHouseholdIncome>
<StateHouseholdIncome>65536</StateHouseholdIncome>
<ZipNotes>CensusDataFoundForZip</ZipNotes>
<ZipNotesCodes>150</ZipNotesCodes>

</AddressInsightResponse>

List of Operations

GetAddressInsight - Provides comprehensive address validation, location identification and appends demographic metadata information about a location in the US.

Operation Definitions

This document defines the input, output and behavior of the web service operation(s) in Address Insight.

GetAddressInsight

 Provides comprehensive address validation, location identification and appends demographic metadata information about a location in the US.

URL Formats

JSON:  https://trial.serviceobjects.com/ain/api.svc/JSON/GetAddressInsight?BusinessName={BUSINESSNAME}&Address1={ADDRESS1}&Address2={ADDRESS2}&City={CITY}&State={STATE}&Zip={ZIP}&TestType={TESTTYPE}&LicenseKey={LICENSEKEY}

XML: https://trial.serviceobjects.com/ain/api.svc/XML/GetAddressInsight?BusinessName={BUSINESSNAME}&Address1={ADDRESS1}&Address2={ADDRESS2}&City={CITY}&State={STATE}&Zip={ZIP}&TestType={TESTTYPE}&LicenseKey={LICENSEKEY}

Click Here for examples and code snippets!


GetAddressInsight Inputs

Name

Type

Description

BusinessName

String

A company name for a business, can provide additional insight to the location or append a SuiteLink value

Address1

String

The address line 1 of the contact or business address.

Address2

String

The address line 2 of the contact or business address.

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.

TestType

String

Not currently used - May allow future customizations

LicenseKey

String

Your license key to use the service. This is a required value.
Sign up for a free trial key at 
www.serviceobjects.com.


GetAddressInsight Outputs

Name

Type

Values

Description

Status
VariesAn overall human readable description of the result of the set of validations. This result may change over time and is designed to provide a quick overview of the results, not meant for programming against.
StatusScore
0-100A 0-100 score representing the percent likelihood that the location is a good one.
AddressStatus
Success/FailAn indicator of how the location fared as it pertains to address validation.
DPV
1-4Number 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
VariesHuman readable description of the DPV result.
Address
VariesThe corrected and standardized first line of the given address.
AddressExtra
VariesExtraneous input address information that is NOT part of the standardized address but may provide extra insight.
City
VariesThe corrected and standardized city of the given address.
State
2 character code (XX)The corrected and standardized state of the given address.
Zip
9 digit number(XXXXX-XXXX)The corrected and standardized nine digit zip code of the given address.
BarcodeDigits
12 digit numberThe twelve digit post office delivery barcode digits.
CarrierRoute
4 character code (XXXX)4 chars: 1 for the route type, 3 for the route code. Identifies a group of addresses when prepended by 5-digit Zip.
CongressCode
XXThe congress code of the given address.
CountyName
VariesThe country name of the given address.
FragmentHouse
VariesThe parsed house number of the given address.
FragmentPreDir
N,S,E,W, NW,NE,SW,SEThe parsed pre-directional of the address's street. "North" in "North Main St West".
FragmentStreet
VariesThe parsed name of the street in the given address. "Main" in "North Main St West".
FragmentSuffix
VariesThe parsed suffix of the street in the given address. "St" in "North Main St West".
FragmentPostDir
N,S,E,W, NW,NE,SW,SEThe parsed post-directional of the address's street. "West" in "North Main St West".
FragmentUnit
Varies

The parsed type of the apartment, box, unit, etc. "Apt" in "Main St, Apt B"

FragmentUnitNumber
VariesThe parsed apartment, box, unit, etc. number of the given address. "B" in "Main St, Apt B"
FragmentPMBPrefix
VariesThe parsed type of personal mail box. "PMB" in "Main St, Apt B PMB 150"
FragmentPMBNumber
VariesThe parsed number of the personal mailbox. "150" in "Main St, Apt B PMB 150"
Corrections
VariesNumber that correlates to a Corrections Description. Service Objects may add or change Correction descriptions, but will never modify existing codes.
CorrectionsDesc
VariesDescription of what was corrected in an address. Service Objects may add or change Correction descriptions, but will never modify existing codes.
AddressNotes
VariesA comma separated string of numbers representing informative findings about the address as it pertains to Address Validation. See AddressNotes table below for more detailed description.
AddressNotesCodes
VariesA comma separated string of human readable descriptions for the AddressNotes. See AddressNotes table below for more detailed description.
GeocodeStatus
Success/FailAn indicator of how the location fared as it pertains to the geolocation of said location.
LocationLatitude
Decimal Number

The closest geocoding latitude match of the given address. A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point. See GeocodeNotes for levels.

LocationLongitude
Decimal Number

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

CensusTract
6 digit decimal (XXXX.XX)The Census Tract of the given address.
CensusBlock
4 digit number (XXXX)

The Census Block of the given address.

PlaceName
VariesThe PlaceName of the location as it pertains to geolocation. May be more exact than USPS returned City information as those designations exist to ease postal deliveries and not to return precise results.
ClassFP
Alpha-Numeric (XX)A code that defines the current class of the geographic location.
SLDUST
VariesCurrent state legislative district upper (senate) chamber code.
SLDLST
VariesCurrent state legislative district lower (house) chamber code
CountyFIPS
3 digit number (XXX)County FIPS(Federal Information Processing Standard) code; used to uniquely identify counties across the US.
StateFIPS
2 digit number (XX)State FIPS(Federal Information Processing Standard) code; used to uniquely identity states 
GeocodeNotes
VariesA comma separated string of numbers representing informative findings about the address as it pertains to Location Geocoding. See GeocodeNotes table below for more detailed description.
GeocodeNotesCodes
VariesA comma separated string of human readable descriptions for the GeocodeNotes. See GeocodeNotes table below for more detailed description.
ZipStatus
Success/FailAn indidcator of success in returning demographics/census data for the given zip code.
ZipLatitude
NumberA zip centroid Latitude.
ZipLongitude
NumberA zip centroid Longitude.
CityType
N, P, U, B, A, C, S, KThe city type of the given zip code. The code refers to the type of postal station in a given zip code. See table below for descriptions for each of the codes.
CityAliasName
VariesA common alternative city name for the given location.
AreaCode
VariesContains one or more area codes associated with the zip code. e.g. zip code: 74570 has 4 and will return: "918/405/539/580"
TimeZone
1 digit number (X)The number of hours offset from GMT. 5 = Eastern time zone, 8 = Pacific time zone, etc.
DaylightSaving
Y or N

Whether the given zip code observes DayLight Savings time.

MSA
VariesThe Metropolitan Statistical Area Code. Used to uniquely identify a geographic area with a relatively high population density at its core.
CBSA
VariesThe 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. 
CBSA_Div
Varies
PMSA
VariesThe Primary Metropolitan Statistical Area code. Used to uniquely identify areas that are part of a larger urban center. 
DMA
VariesThe Designated Market Area code. Used to uniquely identify a geographic region that receive the same(or similar) TV and radio show programs. 
ZipHouseholdValue
NumberAverage value of houses in the zip code
ZipPersonsPerHousehold
NumberAverage number of persons per household in the zip code
ZipHouseholdIncome
NumberAverage Income per household in the zip code
CountyHouseholdIncome
NumberAverage Income per household in the country of the zip code
StateHouseholdIncome
NumberAverage Income per household in the state of the zip code
ZipNotes

A comma separated string of numbers representing informative findings about the zip code. See ZipNotes table below for more detailed description.
ZipNotesCodes

A comma separated string of human readable descriptions for the ZipNotes. See ZipNotes table below for more detailed description.

* Indicates that the output value is coming soon.

Data Tables and Notes

The following tables contain codes and descriptions for various enumerated lists of data found in DOTS Address Insight.


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

Corrections

*New corrections may be added over time, and some descriptions may change, but the codes will never change

Corrections

CorrectionsDesc

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

Address Note Codes & Descriptions

*New notes may be added over time, and some descriptions may change, but the codes will never change

Notes

NotesDesc

Description
1BadAddressAll indications suggest this is a bad address
2AddressNotFound.The address was not found by USPS.
5HouseNumberOutOfRangeThe given house number does not seem to be a valid one.
100AddressFoundByUSPSThe Address was found in the normal USPS dataset.
101AddressFoundInSupplementalData*Coming soon*
102AddressIsGeneralDeliveryAddress may not have been found in USPS or other datasets but has a high likelihood of being good and is likely in a General Delivery area.
120IsBusinessAddress appears to be a business.
121IsResidenceAddress appears to be a residence
122IsPOBoxAddress appears to be a PO Box.
123IsCMRAAddress appears to be associated with a commercial mail handling facility.
124IsStreetAddressAddress appears to be a standalone dwelling residence or business
125IsHighRiseAddress appears to be a multilevel apartment or business building.
126IsMilitaryAddress appears to be in a known military area.
130IsUniqueZipZip code belongs to a known area such as a university where mail and packages are delivered to a central location and distributed from there. The actual street address is irrelevant as long as it contains a house number and street name.
131IsVacantAddress appears to be vacant.
132IsReturningMailAddress appears to be returning mail at the moment.


Geocode Note Codes & Descriptions

*New notes may be added over time, and some descriptions may change, but the codes will never change

Notes

NotesDesc

Description
10LocationNotFoundNo Latitude and Longitude was found for the given location.
110IsLocationMatchLatitude and Longitude found should represent the property in question.
111IsZip4MatchLatitude and Longitude found should represent the centroid of all locations matching the first 9 digits of the zip code.
112IsZip3MatchLatitude and Longitude found should represent the centroid of all locations matching the first 8 digits of the zip code.
113IsZip2MatchLatitude and Longitude found should represent the centroid of all locations matching the first 7 digits of the zip code.
114IsZip1MatchLatitude and Longitude found should represent the centroid of all locations matching the first 6 digits of the zip code.
115IsZipMatchLatitude and Longitude found should represent the centroid of all locations matching the first 5 digits of the zip code.
116IsCityMatchLatitude and Longitude found should represent the centroid of the given city and state.
140IsUnincorporatedThe location was not found in a known city boundary. It may be a census designated place or not assigned to any known "place".


Zip Note Codes & Descriptions

*New notes may be added over time, and some descriptions may change, but the codes will never change

Notes

NotesDesc

Description
20CensusDataNotFoundForZipNo demographic or census data was found for this zip code.
25NoZipInputNo zip code was given.
150CensusDataFoundForZipDemographic and census data was found for this zip code.


Current List of ClassFP Codes

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


CityType Code Definitions

CodeDescription
NNon Postal Community Name: Former Postal Facility 
PPost Office: Official post office branch.
UUrbanization: Specific to Puerto Rico.
BBranch: A postal facility that is not the main post office and is outside the corporate limits of a city.
CCommunity Post Office: a contract postal unit providing mail services to small communities.
SStation: A post office that is not the main office for a city but is in corporate city limits.
ZPO Box: Linked to a set of PO Boxes.
XMilitary: Linked to an APO/FPO Military base.

Errors

Anything that happens during a run of DOTS Address Insight that causes it to be unable to finish its normal processing is an error. If an error occurs, one of the following error types will be returned.

Error Types

Type

TypeCode

Billable

Standard Across All Gen2 Web Services

Authorization

1

No

Yes

User Input

2

No

No

Service Objects Fatal

3

No

Yes


Error type 1: Authorization

Theses are standard to all Generation 2 DOTS Web Services.

DescCode

Desc

0

Unknown authorization error.

1

Please provide a valid license key for this web service.

2

The daily allowable number of transactions for this license key has been exceeded.

3

The monthly allowable number of transactions for this license key has been exceeded.

4

The total allowable number of transactions for this license key has been exceeded.

5

There are not enough transactions available. Check your daily/monthly transaction limits.

6

This license key has not yet been activated.

7

This license key has expired.

8

Your license key does not work on this service


Error type 2: User Input

User Input errors are caused when a user inputs an invalid value or fails to provide a certain input field altogether. If a developer creates a request and mistypes a parameter name, it will probably cause a User Input Error.

DescCode

Desc

1You must input a license key in the LicenseKey field.
2You must submit at least one input value in addition to your license key.


Error type 3: Service Objects Fatal

The Desc will always be the same and the DescCode has no meaning. This is standard to all Generation 2 DOTS Web Services. This is a rare error that signals either a bug in the DOTS Address Detective service, or a Network/Connectivity issue.

DescCode

Desc

1

Unhandled error. Please contact Service Objects.

Frequently Asked Questions

The Sample Code is Giving Strange Errors or is Crashing!

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

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


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 need to know exactly how long each of the output fields could be.  What is your standard field length?

Please email us at support@serviceobjects.com, and we'll send you the exact field length specifications.  As a general rule, you won't get a field longer than 80 characters.

I am not a programmer.  How do I use DOTS Address Insight?

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

Conclusion

Service Objects is proud to offer you a free trial of DOTS Address Insight



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

If you are interested in purchasing any other DOTS Address Validation products, please contact sales@serviceobjects.com 


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

  • No labels