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


Introduction

DOTS Address Detective International ("ADI") is a utility service that provides tools to provide greater insight to existing data points, go outside of the box on complex location based problems and help clean up extremely messy data points.

Currently, it contains one operation called FindBestCountry, designed to analyze a given set of data points and correct or append the Country. Users with incorrect or missing country data can use the operation to fill in the blanks. It can also be used to enhance other services such as DOTS Address Validation - International or DOTS Lead Validation - International that require a country to properly process.

ADI's FindBestCountry can help clean up messy CRMs, localize sales and marketing more effectively by providing the proper geographic location, or help companies identify a customer's location to remain compliant when dealing with data protection laws like GDPR.


Integration

Integrating ADI 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.

ADI 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/ADI/api.svc

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

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/ADI/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 Detective International C# Code Snippet
 public partial class ADI_Form : System.Web.UI.Page
    {
        const string TrialURL = "http://trial.serviceobjects.com/adi/soap.svc";
        // 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/adi/soap.svc";
        protected void Page_Load(object sender, EventArgs e)
        {
            ErrorLabel.Visible = false;
        }
        protected void btn_Validate_Click(object sender, EventArgs e)
        {
            try
            {
                ADI.ResponseObject response = FindBestCountry();
                PrintResponse(response);
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = ex.Message;
            }
        }
        protected ADI.ResponseObject FindBestCountry()
        {
            ADI.ResponseObject Response = null;

            try
            {
                using (ADI.SOAPClient Client = new ADI.SOAPClient())
                {
                    // Implement Failover logic here
                    try
                    {
                        Response = Client.FindBestCountry("", "", "", "",
                                                          inputAddress1.Text,
                                                          inputAddress2.Text,
                                                          inputAddress3.Text,
                                                          inputAddress4.Text,
                                                          inputAddress5.Text,
                                                          inputAddress6.Text,
                                                          inputAddress7.Text,
                                                          inputAddress8.Text,
                                                          inputLocality.Text,
                                                          inputAdminArea.Text,
                                                          inputPostalCode.Text,
                                                          inputPhoneNumber.Text,
                                                          inputPhoneNumber2.Text,
                                                          inputPhoneNumber3.Text,
                                                          inputEmail.Text,
                                                          inputIPAddress.Text,
                                                          inputDomain.Text,
                                                          inputLicenseKey.Text);
                    }
                    catch (WebException)
                    {
                        Client.Endpoint.Address = new System.ServiceModel.EndpointAddress(BackupURL);
                        Response = Client.FindBestCountry("", "", "", "",
                                                          inputAddress1.Text,
                                                          inputAddress2.Text,
                                                          inputAddress3.Text,
                                                          inputAddress4.Text,
                                                          inputAddress5.Text,
                                                          inputAddress6.Text,
                                                          inputAddress7.Text,
                                                          inputAddress8.Text,
                                                          inputLocality.Text,
                                                          inputAdminArea.Text,
                                                          inputPostalCode.Text,
                                                          inputPhoneNumber.Text,
                                                          inputPhoneNumber2.Text,
                                                          inputPhoneNumber3.Text,
                                                          inputEmail.Text,
                                                          inputIPAddress.Text,
                                                          inputDomain.Text,
                                                          inputLicenseKey.Text);
                    }
                    catch (CommunicationException)
                    {
                        Client.Abort();
                    }
                    catch (TimeoutException)
                    {
                        Client.Abort();
                    }
                    catch (Exception)
                    {
                        Client.Abort();
                    }
                }
            }
            catch (Exception)
            {
                // throw;
            }
            return Response;
        }
        protected void PrintResponse(ADI.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("CountryDetectionResponse"))
            {
                ADI.ResultObject ro = response["CountryDetectionResponse"];
                //Loop throught he 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("TotalScore", ro[0].ContainsKey("TotalScore") ? ro[0]["TotalScore"] : "");
                dtProvider.Rows.Add("NotesDesc", ro[0].ContainsKey("NotesDesc") ? ro[0]["NotesDesc"] : "");
                dtProvider.Rows.Add("Best_CountryName", ro[0].ContainsKey("Best_CountryName") ? ro[0]["Best_CountryName"] : "");
                dtProvider.Rows.Add("Best_CountryISO2", ro[0].ContainsKey("Best_CountryISO2") ? ro[0]["Best_CountryISO2"] : "");
                dtProvider.Rows.Add("Best_CountryISO3", ro[0].ContainsKey("Best_CountryISO3") ? ro[0]["Best_CountryISO3"] : "");
                dtProvider.Rows.Add("Address_Score", ro[0].ContainsKey("Address_Score") ? ro[0]["Address_Score"] : "");
                dtProvider.Rows.Add("Address_CountryName", ro[0].ContainsKey("Address_CountryName") ? ro[0]["Address_CountryName"] : "");
                dtProvider.Rows.Add("Address_CountryISO2", ro[0].ContainsKey("Address_CountryISO2") ? ro[0]["Address_CountryISO2"] : "");
                dtProvider.Rows.Add("Address_CountryISO3", ro[0].ContainsKey("Address_CountryISO3") ? ro[0]["Address_CountryISO3"] : "");
                dtProvider.Rows.Add("Address_AllCountriesFoundISO2", ro[0].ContainsKey("Address_AllCountriesFoundISO2") ? ro[0]["Address_AllCountriesFoundISO2"] : "");
                dtProvider.Rows.Add("Phone1_Score", ro[0].ContainsKey("Phone1_Score") ? ro[0]["Phone1_Score"] : "");
                dtProvider.Rows.Add("Phone1_CountryName", ro[0].ContainsKey("Phone1_CountryName") ? ro[0]["Phone1_CountryName"] : "");
                dtProvider.Rows.Add("Phone1_CountryISO2", ro[0].ContainsKey("Phone1_CountryISO2") ? ro[0]["Phone1_CountryISO2"] : "");
                dtProvider.Rows.Add("Phone1_CountryISO3", ro[0].ContainsKey("Phone1_CountryISO3") ? ro[0]["Phone1_CountryISO3"] : "");
                dtProvider.Rows.Add("Phone1_AllCountriesFoundISO2", ro[0].ContainsKey("Phone1_AllCountriesFoundISO2") ? ro[0]["Phone1_AllCountriesFoundISO2"] : "");
                dtProvider.Rows.Add("Email_Score", ro[0].ContainsKey("Email_Score") ? ro[0]["Email_Score"] : "");
                dtProvider.Rows.Add("Email_CountryISO2", ro[0].ContainsKey("Email_CountryISO2") ? ro[0]["Email_CountryISO2"] : "");
                dtProvider.Rows.Add("Email_CountryISO3", ro[0].ContainsKey("Email_CountryISO3") ? ro[0]["Email_CountryISO3"] : "");
                dtProvider.Rows.Add("Email_AllCountriesFoundISO2", ro[0].ContainsKey("Status") ? ro[0]["Email_AllCountriesFoundISO2"] : "");
            }
            else
            {
                if (response.ContainsKey("Error"))
                {
                    ADI.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 Detective International Java Code Snippet
			String CompanyName = request.getParameter("CompanyName");
            String FullName = request.getParameter("FullName");
            String FirstName = request.getParameter("FirstName");
            String LastName = request.getParameter("LastName");
            String Address1 = request.getParameter("Address1");
            String Address2 = request.getParameter("Address2");
            String Address3 = request.getParameter("Address3");
            String Address4 = request.getParameter("Address4");
            String Address5 = request.getParameter("Address5");
            String Address6 = request.getParameter("Address6");
            String Address7 = request.getParameter("Address7");
            String Address8 = request.getParameter("Address8");
            String Locality = request.getParameter("Locality");
            String AdminArea = request.getParameter("AdminArea");
            String PostalCode = request.getParameter("PostalCode");
            String Phone1 = request.getParameter("Phone1");
            String Phone2 = request.getParameter("Phone2");
            String Phone3 = request.getParameter("Phone3");
            String Email = request.getParameter("Email");
            String IPAddress = request.getParameter("IPAddress");
            String Domain = request.getParameter("Domain");
            String LicenseKey = request.getParameter("LicenseKey");
            CompanyName = URLEncoder.encode(CompanyName, "UTF-8").replaceAll("\\+", "%20");
            FullName = URLEncoder.encode(FullName, "UTF-8").replaceAll("\\+", "%20");
            FirstName = URLEncoder.encode(FirstName, "UTF-8").replaceAll("\\+", "%20");
            LastName = URLEncoder.encode(LastName, "UTF-8").replaceAll("\\+", "%20");
            Address1 = URLEncoder.encode(Address1, "UTF-8").replaceAll("\\+", "%20");
            Address2 = URLEncoder.encode(Address2, "UTF-8").replaceAll("\\+", "%20");
            Address3 = URLEncoder.encode(Address3, "UTF-8").replaceAll("\\+", "%20");
            Address4 = URLEncoder.encode(Address4, "UTF-8").replaceAll("\\+", "%20");
            Address5 = URLEncoder.encode(Address5, "UTF-8").replaceAll("\\+", "%20");
            Address6 = URLEncoder.encode(Address6, "UTF-8").replaceAll("\\+", "%20");
            Address7 = URLEncoder.encode(Address7, "UTF-8").replaceAll("\\+", "%20");
            Address8 = URLEncoder.encode(Address8, "UTF-8").replaceAll("\\+", "%20");
            Locality = URLEncoder.encode(Locality, "UTF-8").replaceAll("\\+", "%20");
            AdminArea = URLEncoder.encode(AdminArea, "UTF-8").replaceAll("\\+", "%20");
            PostalCode = URLEncoder.encode(PostalCode, "UTF-8").replaceAll("\\+", "%20");
            Phone1 = URLEncoder.encode(Phone1, "UTF-8").replaceAll("\\+", "%20");
            Phone2 = URLEncoder.encode(Phone2, "UTF-8").replaceAll("\\+", "%20");
            Phone3 = URLEncoder.encode(Phone3, "UTF-8").replaceAll("\\+", "%20");
            Email = URLEncoder.encode(Email, "UTF-8").replaceAll("\\+", "%20");
            IPAddress = URLEncoder.encode(IPAddress, "UTF-8").replaceAll("\\+", "%20");
            Domain = URLEncoder.encode(Domain, "UTF-8").replaceAll("\\+", "%20");
            LicenseKey = URLEncoder.encode(LicenseKey, "UTF-8").replaceAll("\\+", "%20");
            
            SOAP soap = new SOAP();
            ISOAP client = soap.getDOTSAddressDetectiveInternational();
            ResponseObject addressDetectiveInternational = client.findBestCountry(CompanyName, FullName, FirstName, LastName, Address1, Address2, Address3, Address4, Address5, Address6, Address7, Address8, Locality, AdminArea, PostalCode, Phone1, Phone2, Phone3, Email, IPAddress, Domain, LicenseKey);
            List<Response> responses = addressDetectiveInternational.getResponse();
 
			//Loop through response and fields to find the specific you are targeting.
			//A helper method couldb ecreated and used to make this part look nicer but
			//essentially it would be doing the same thing so we leave it to you to
			//make that decision.
			for(Response res : responses){
                ResultObject resList = res.getValue();
                String resultKey = res.getKey();
				List<FieldObject> results = resList.getResult();
                for(FieldObject result : results){
                    List<Field> fields = result.getField();
                    for(FieldObject.Field kvp : fields){
                        String key = kvp.getKey();
                        String value = kvp.getValue();
					}
				}
			}



Address Detective International C# Code Snippet
            string primaryurl = "http://trial.serviceobjects.com/adi/api.svc/" + format + "/FindBestCountry?CompanyName=" + companyName + "&FullName=" + fullName + "&FirstName=" + firstName + "&LastName=" + lastName + "&Address1=" + address1 + "&Address2=" + address2 + "&Address3=" + address3 + "&Address4=" + address4 + "&Address5=" + address5 + "&Address6=" + address6 + "&Address7=" + address7 + "&Address8=" + address8 + "&Locality=" + locality + "&AdminArea=" + adminArea + "&PostalCode=" + postalCode + "&Phone1=" + phone1 + "&Phone2=" + phone2 + "&Phone3=" + phone3 + "&Email=" + email + "&IPAddress=" + ipAddress + "&LicenseKey=" + licensekey;
            
			string backupurl = "http://trial.serviceobjects.com/adi/api.svc/" + format + "/FindBestCountry?CompanyName=" + companyName + "&FullName=" + fullName + "&FirstName=" + firstName + "&LastName=" + lastName + "&Address1=" + address1 + "&Address2=" + address2 + "&Address3=" + address3 + "&Address4=" + address4 + "&Address5=" + address5 + "&Address6=" + address6 + "&Address7=" + address7 + "&Address8=" + address8 + "&Locality=" + locality + "&AdminArea=" + adminArea + "&PostalCode=" + postalCode + "&Phone1=" + phone1 + "&Phone2=" + phone2 + "&Phone3=" + phone3 + "&Email=" + email + "&IPAddress=" + ipAddress + "&LicenseKey=" + licensekey;
            try
            {
               
                wsresponse = httpGet(primaryurl);
                //checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
                if (wsresponse == null || (wsresponse.Error != null && wsresponse.Error.TypeCode == "3"))
                {
                    throw new Exception("Primary Call Received an Unhandled erros");
                }
            }
            catch (Exception ex)
            {
                try
                {
                    wsresponse = httpGet(backupurl);
                }
                catch (Exception err)
                {
                    //Displays the relevant error mesasge if both backup and primary urls failed. You will likely want to log this somewhere
                    StatusLabel.Text = err.Message;
                    StatusLabel.Visible = true;
                } 
                //Displays the relevant error mesasge if both backup and primary urls failed.
                StatusLabel.Text = ex.Message;
                StatusLabel.Visible = true;
            }
            if (wsresponse.Error != null)
            {
                ProcessErrorResponse(wsresponse.Error);
            }
            else
            {
                ProcessSuccessfulResponse(wsresponse);
            }
 
        private CountryDetectionResponse httpGet(string url)
        {
            try
            {
                //NOTE: URL encoding occurs automatically when creating the web request
                HttpWebRequest request = WebRequest.Create(url) as HttpWebRequest;
                request.Timeout = 15000;//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));
                    //parses XML response into the AVIResponse object
                    XmlSerializer serializer = new XmlSerializer(typeof(CountryDetectionResponse));
                    StreamReader reader = new StreamReader(response.GetResponseStream());
                    CountryDetectionResponse output = new CountryDetectionResponse();
                    output = (CountryDetectionResponse)serializer.Deserialize(reader);
                    return output;
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }

        private void ProcessSuccessfulResponse(CountryDetectionResponse outputs)
        {
            DataTable dtoutput = new DataTable();
            dtoutput.Columns.Add("Outputs", typeof(string));
            dtoutput.Columns.Add("Values", typeof(string));
            dtoutput.Rows.Add("Status", outputs.CountryDetection.Status);
            dtoutput.Rows.Add("TotalScore", outputs.CountryDetection.TotalScore);
            dtoutput.Rows.Add("Notes", outputs.CountryDetection.Notes);
            dtoutput.Rows.Add("NotesDesc", outputs.CountryDetection.NotesDesc);
            dtoutput.Rows.Add("Warnings", outputs.CountryDetection.Warnings);
            dtoutput.Rows.Add("WarningsDesc", outputs.CountryDetection.WarningsDesc);
            .
			.
			.
            dtoutput.Rows.Add("Email_CountryISO2", outputs.CountryDetection.Email_CountryISO2);
            dtoutput.Rows.Add("Email_CountryISO3", outputs.CountryDetection.Email_CountryISO3);
            dtoutput.Rows.Add("Email_AllCountriesFoundISO2", outputs.CountryDetection.Email_AllCountriesFoundISO2);

            //Checks for the existence of the Information Compoents object and then prints the resulting values if they arise.
            ResultGrid.Visible = true;
            StatusLabel.Visible = true;
            ResultGrid.DataSource = new DataView(dtoutput);
            ResultGrid.DataBind();
        }
        private void ProcessErrorResponse(Error errorResponse)
        {
            DataTable dtError = new DataTable();
            dtError.Columns.Add("Outputs", typeof(string));
            dtError.Columns.Add("Values", typeof(string));
            dtError.Rows.Add("Type", errorResponse.Type);
            dtError.Rows.Add("TypeCode", errorResponse.TypeCode);
            dtError.Rows.Add("Desc", errorResponse.Desc);
            dtError.Rows.Add("DescCode", errorResponse.DescCode);
            ResultGrid.Visible = true;
            StatusLabel.Visible = true;
            ResultGrid.DataSource = new DataView(dtError);
            ResultGrid.DataBind();
        }


//We'll pull these values from the input form
String Address1 = request.getParameter("address1");
String Address2 = request.getParameter("address2");
String Address3 = request.getParameter("address3");
String Address4 = request.getParameter("address4");
String Address5 = request.getParameter("address5");
String Address6 = request.getParameter("address6");
String Address7 = request.getParameter("address7");
String Address8 = request.getParameter("address8");
String Locality = request.getParameter("locality");
String AdminArea = request.getParameter("adminarea");
String PostalCode = request.getParameter("postalcode");
String Phone1 = request.getParameter("phone1");
String Phone2 = request.getParameter("phone2");
String Phone3 = request.getParameter("phone3");
String Email = request.getParameter("email");
String IPAddress = request.getParameter("ipaddress");
String Domain = request.getParameter("domain");
String LicenseKey = request.getParameter("licensekey");

Address1 = URLEncoder.encode(Address1,"UTF-8").replaceAll("\\+", "%20");
Address2 = URLEncoder.encode(Address2,"UTF-8").replaceAll("\\+", "%20");
Address3 = URLEncoder.encode(Address3,"UTF-8").replaceAll("\\+", "%20");
Address4 = URLEncoder.encode(Address4,"UTF-8").replaceAll("\\+", "%20");
Address5 = URLEncoder.encode(Address5,"UTF-8").replaceAll("\\+", "%20");
Address6 = URLEncoder.encode(Address6,"UTF-8").replaceAll("\\+", "%20");
Address7 = URLEncoder.encode(Address7,"UTF-8").replaceAll("\\+", "%20");
Address8 = URLEncoder.encode(Address8,"UTF-8").replaceAll("\\+", "%20");
Locality = URLEncoder.encode(Locality,"UTF-8").replaceAll("\\+", "%20");
AdminArea = URLEncoder.encode(AdminArea,"UTF-8").replaceAll("\\+", "%20");
PostalCode = URLEncoder.encode(PostalCode,"UTF-8").replaceAll("\\+", "%20");
Phone1 = URLEncoder.encode(Phone1,"UTF-8").replaceAll("\\+", "%20");
Phone2 = URLEncoder.encode(Phone2,"UTF-8").replaceAll("\\+", "%20");
Phone3 = URLEncoder.encode(Phone3,"UTF-8").replaceAll("\\+", "%20");
Email = URLEncoder.encode(Email,"UTF-8").replaceAll("\\+", "%20");
IPAddress = URLEncoder.encode(IPAddress,"UTF-8").replaceAll("\\+", "%20");
Domain = URLEncoder.encode(Domain,"UTF-8").replaceAll("\\+", "%20");
LicenseKey = URLEncoder.encode(LicenseKey,"UTF-8").replaceAll("\\+", "%20");

//Set the primary and backup URLs as necessary. In production, the primary endpoint should be pointed to ws.serviceobjects.com and the backup should be pointed to wsbackup.serviceobjects.com
String mainUrl = "http://trial.serviceobjects.com/adi/api.svc/XML/FindBestCountry?CompanyName=" + CompanyName + "&FullName=" + FullName+ "&FirstName=" + FirstName + "&LastName=" + LastName + "&Address1=" + Address1 + "&Address2=" + Address2 + "&Address3=" + Address3 + "&Address4=" + Address4 + "&Address5=" + Address5 + "&Address6=" + Address6 + "&Address7=" + Address7 + "&Address8=" + Address8 + "&Locality=" + Locality + "&AdminArea=" + AdminArea + "&PostalCode=" +PostalCode + "&Phone1=" + Phone1 + "&Phone2=" + Phone2 + "&Phone3=" + Phone3 +"&Email=" + Email + "&IPAddress=" + IPAddress + "&Domain=" + Domain + "&LicenseKey=" + LicenseKey;
String backupUrl = "http://trial.serviceobjects.com//adi/api.svc/XML/FindBestCountry?CompanyName=" + CompanyName + "&FullName=" + FullName+ "&FirstName=" + FirstName + "&LastName=" + LastName + "&Address1=" + Address1 + "&Address2=" + Address2 + "&Address3=" + Address3 + "&Address4=" + Address4 + "&Address5=" + Address5 + "&Address6=" + Address6 + "&Address7=" + Address7 + "&Address8=" + Address8 + "&Locality=" + Locality + "&AdminArea=" + AdminArea + "&PostalCode=" +PostalCode + "&Phone1=" + Phone1 + "&Phone2=" + Phone2 + "&Phone3=" + Phone3 +"&Email=" + Email + "&IPAddress=" + IPAddress + "&Domain=" + Domain + "&LicenseKey=" + LicenseKey;

ADIRest adirestClient = new ADIRest();
JSONObject results = new JSONObject();

results = adirestClient.AddressResponse(mainUrl, backupUrl);
if (results.getJSONObject("CountryDetectionResponse").has("Error") )
{
JSONObject errorResponse = results.getJSONObject("CountryDetectionResponse").getJSONObject("Error") ;
string Type = errorResponse.get("Type");

.

.

.

}else{

JSONObject validresponse = results.getJSONObject("CountryDetectionResponse").getJSONObject("CountryDetection");

string status = validresponse.get("Status");

.

.

.

string totalScore = validresponse.get("TotalScore");

}



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 adi_soap
{
    public partial class ADI_Form : System.Web.UI.Page
    {
        const string TrialURL = "http://trial.serviceobjects.com/adi/soap.svc";
        // 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/adi/soap.svc";
        protected void Page_Load(object sender, EventArgs e)
        {
            ErrorLabel.Visible = false;
        }
        protected void btn_Validate_Click(object sender, EventArgs e)
        {
            try
            {
                ADI.ResponseObject response = FindBestCountry();
                PrintResponse(response);
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = ex.Message;
            }
        }
        protected ADI.ResponseObject FindBestCountry()
        {
            ADI.ResponseObject Response = null;

            try
            {
                using (ADI.SOAPClient Client = new ADI.SOAPClient())
                {
                    // Implement Failover logic here
                    try
                    {
                        Response = Client.FindBestCountry("",
                                                          "",
                                                          "",
                                                          "",
                                                          inputAddress1.Text,
                                                          inputAddress2.Text,
                                                          inputAddress3.Text,
                                                          inputAddress4.Text,
                                                          inputAddress5.Text,
                                                          inputAddress6.Text,
                                                          inputAddress7.Text,
                                                          inputAddress8.Text,
                                                          inputLocality.Text,
                                                          inputAdminArea.Text,
                                                          inputPostalCode.Text,
                                                          inputPhoneNumber.Text,
                                                          inputPhoneNumber2.Text,
                                                          inputPhoneNumber3.Text,
                                                          inputEmail.Text,
                                                          inputIPAddress.Text,
                                                          inputDomain.Text,
                                                          inputLicenseKey.Text);
                    }
                    catch (WebException)
                    {
                        Client.Endpoint.Address = new System.ServiceModel.EndpointAddress(BackupURL);
                        Response = Client.FindBestCountry("",
                                                          "",
                                                          "",
                                                          "",
                                                          inputAddress1.Text,
                                                          inputAddress2.Text,
                                                          inputAddress3.Text,
                                                          inputAddress4.Text,
                                                          inputAddress5.Text,
                                                          inputAddress6.Text,
                                                          inputAddress7.Text,
                                                          inputAddress8.Text,
                                                          inputLocality.Text,
                                                          inputAdminArea.Text,
                                                          inputPostalCode.Text,
                                                          inputPhoneNumber.Text,
                                                          inputPhoneNumber2.Text,
                                                          inputPhoneNumber3.Text,
                                                          inputEmail.Text,
                                                          inputIPAddress.Text,
                                                          inputDomain.Text,
                                                          inputLicenseKey.Text);
                    }
                    catch (CommunicationException)
                    {
                        Client.Abort();
                    }
                    catch (TimeoutException)
                    {
                        Client.Abort();
                    }
                    catch (Exception)
                    {
                        Client.Abort();
                    }
                }
            }
            catch (Exception)
            {
                // throw;
            }
            return Response;
        }
        protected void PrintResponse(ADI.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("CountryDetectionResponse"))
            {
                ADI.ResultObject ro = response["CountryDetectionResponse"];
                //Loop throught he 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("TotalScore", ro[0].ContainsKey("TotalScore") ? ro[0]["TotalScore"] : "");
                dtProvider.Rows.Add("NotesDesc", ro[0].ContainsKey("NotesDesc") ? ro[0]["NotesDesc"] : "");
                dtProvider.Rows.Add("Best_CountryName", ro[0].ContainsKey("Best_CountryName") ? ro[0]["Best_CountryName"] : "");
                dtProvider.Rows.Add("Best_CountryISO2", ro[0].ContainsKey("Best_CountryISO2") ? ro[0]["Best_CountryISO2"] : "");
                dtProvider.Rows.Add("Best_CountryISO3", ro[0].ContainsKey("Best_CountryISO3") ? ro[0]["Best_CountryISO3"] : "");
                dtProvider.Rows.Add("Address_Score", ro[0].ContainsKey("Address_Score") ? ro[0]["Address_Score"] : "");
                dtProvider.Rows.Add("Address_CountryName", ro[0].ContainsKey("Address_CountryName") ? ro[0]["Address_CountryName"] : "");
                dtProvider.Rows.Add("Address_CountryISO2", ro[0].ContainsKey("Address_CountryISO2") ? ro[0]["Address_CountryISO2"] : "");
                dtProvider.Rows.Add("Address_CountryISO3", ro[0].ContainsKey("Address_CountryISO3") ? ro[0]["Address_CountryISO3"] : "");
                dtProvider.Rows.Add("Address_AllCountriesFoundISO2", ro[0].ContainsKey("Address_AllCountriesFoundISO2") ? ro[0]["Address_AllCountriesFoundISO2"] : "");
                dtProvider.Rows.Add("Phone1_Score", ro[0].ContainsKey("Phone1_Score") ? ro[0]["Phone1_Score"] : "");
                dtProvider.Rows.Add("Phone1_CountryName", ro[0].ContainsKey("Phone1_CountryName") ? ro[0]["Phone1_CountryName"] : "");
                dtProvider.Rows.Add("Phone1_CountryISO2", ro[0].ContainsKey("Phone1_CountryISO2") ? ro[0]["Phone1_CountryISO2"] : "");
                dtProvider.Rows.Add("Phone1_CountryISO3", ro[0].ContainsKey("Phone1_CountryISO3") ? ro[0]["Phone1_CountryISO3"] : "");
                dtProvider.Rows.Add("Phone1_AllCountriesFoundISO2", ro[0].ContainsKey("Phone1_AllCountriesFoundISO2") ? ro[0]["Phone1_AllCountriesFoundISO2"] : "");
                dtProvider.Rows.Add("Email_Score", ro[0].ContainsKey("Email_Score") ? ro[0]["Email_Score"] : "");
                dtProvider.Rows.Add("Email_CountryISO2", ro[0].ContainsKey("Email_CountryISO2") ? ro[0]["Email_CountryISO2"] : "");
                dtProvider.Rows.Add("Email_CountryISO3", ro[0].ContainsKey("Email_CountryISO3") ? ro[0]["Email_CountryISO3"] : "");
                dtProvider.Rows.Add("Email_AllCountriesFoundISO2", ro[0].ContainsKey("Status") ? ro[0]["Email_AllCountriesFoundISO2"] : "");
            }
            else
            {
                if (response.ContainsKey("Error"))
                {
                    ADI.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:
http://trial.serviceobjects.com/adi/api.svc/JSON/FindBestCountry?CompanyName=franz Fink&FullName=franz fink&FirstName=&LastName=&Address1=Muellerstr 178&Locality=berlin&AdminArea=%20&PostalCode=%20&Phone1=49 30 46 81 77 96&Email=franz.fink@hotmail.com&IPAddress=79.194.91.107&LicenseKey=[YOURKEY]


Json Response
{"CountryDetection":{"Status":"OK","TotalScore":"70","Notes":"2,3,10,11,14","NotesDesc":"Phone2Missing,Phone3Missing,CountryMatch_Address,CountryMatch_Phone1,CountryMatch_IP","Warnings":"14","WarningsDesc":"CountryMismatch_Email","Best_CountryName":"Germany","Best_CountryISO2":"DE","Best_CountryISO3":"DEU","Address_Score":"30","Address_CountryName":"Germany","Address_CountryISO2":"DE","Address_CountryISO3":"DEU","Address_AllCountriesFoundISO2":"DE,CO,US,MX,VE,PE,BO,HN,NI,SV,ZA,CR,GT,JM,HT,GY,EC,RU,UA","Phone1_Score":"25","Phone1_CountryName":"Germany","Phone1_CountryISO2":"DE","Phone1_CountryISO3":"DEU","Phone1_AllCountriesFoundISO2":"DE","IPAddress_Score":"15","IPAddress_CountryName":"Germany","IPAddress_CountryISO2":"DE","IPAddress_CountryISO3":"DEU","IPAddress_AllCountriesFoundISO2":"DE","Email_Score":"0","Email_CountryName":"United States","Email_CountryISO2":"US","Email_CountryISO3":"USA","Email_AllCountriesFoundISO2":"US"}}


XML Request: 
http://trial.serviceobjects.com/adi/api.svc/XML/FindBestCountry?CompanyName=franz Fink&FullName=franz fink&FirstName=&LastName=&Address1=Muellerstr 178&Locality=berlin&AdminArea=%20&PostalCode=%20&Phone1=49 30 46 81 77 96&Email=franz.fink@hotmail.com&IPAddress=79.194.91.107&LicenseKey=[YOURKEY]


XML Response
<CountryDetectionResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CountryDetection>
<Status>OK</Status>
<TotalScore>70</TotalScore>
<Notes>2,3,10,11,14</Notes>
<NotesDesc>
Phone2Missing,Phone3Missing,CountryMatch_Address,CountryMatch_Phone1,CountryMatch_IP
</NotesDesc>
<Warnings>14</Warnings>
<WarningsDesc>CountryMismatch_Email</WarningsDesc>
<Best_CountryName>Germany</Best_CountryName>
<Best_CountryISO2>DE</Best_CountryISO2>
<Best_CountryISO3>DEU</Best_CountryISO3>
<Address_Score>30</Address_Score>
<Address_CountryName>Germany</Address_CountryName>
<Address_CountryISO2>DE</Address_CountryISO2>
<Address_CountryISO3>DEU</Address_CountryISO3>
<Address_AllCountriesFoundISO2>
DE,CO,US,MX,VE,PE,BO,HN,NI,SV,ZA,CR,GT,JM,HT,GY,EC,RU,UA
</Address_AllCountriesFoundISO2>
<Phone1_Score>25</Phone1_Score>
<Phone1_CountryName>Germany</Phone1_CountryName>
<Phone1_CountryISO2>DE</Phone1_CountryISO2>
<Phone1_CountryISO3>DEU</Phone1_CountryISO3>
<Phone1_AllCountriesFoundISO2>DE</Phone1_AllCountriesFoundISO2>
<IPAddress_Score>15</IPAddress_Score>
<IPAddress_CountryName>Germany</IPAddress_CountryName>
<IPAddress_CountryISO2>DE</IPAddress_CountryISO2>
<IPAddress_CountryISO3>DEU</IPAddress_CountryISO3>
<IPAddress_AllCountriesFoundISO2>DE</IPAddress_AllCountriesFoundISO2>
<Email_Score>0</Email_Score>
<Email_CountryName>Ireland</Email_CountryName>
<Email_CountryISO2>IE</Email_CountryISO2>
<Email_CountryISO3>IRL</Email_CountryISO3>
<Email_AllCountriesFoundISO2>IE,AT</Email_AllCountriesFoundISO2>
</CountryDetection>
</CountryDetectionResponse>

List of Operations

FindBestCountry - This operation was desinged to identify the country that best suits the input data.  Countries matching the individual components are returned too.  The more inputs added the better the results are going to be in most situations.  After analizing the inputs a total score will be generated based on the number of contact points submitted and each contact point has its own weight.

Operation Definitions

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

FindBestCountry

This operation was desinged to identify the country that best suits the input data.  Countries matching the individual components are returned too.  The more inputs added the better the results are going to be in most situations.  After analizing the inputs a total score will be generated based on the number of contact points submitted and each contact point has its own weight.


URL Formats

JSON:  https://trial.serviceobjects.com/ADI/api.svc/json/FindBestCountry?CompanyName={COMPANYNAME}&FullName={FULLNAME}&FirstName={FIRSTNAME}&LastName={LASTNAME}&Address1={ADDRESS1}&Address2={ADDRESS2}&Address3={ADDRESS3}&Address4={ADDRESS4}&Address5={ADDRESS5}&Address6={ADDRESS6}&Address7={ADDRESS7}&Address8={ADDRESS8}&Locality={LOCALITY}&AdminArea={ADMINAREA}&PostalCode={POSTALCODE}&Phone1={PHONE1}&Phone2={PHONE2}&Phone3={PHONE3}&Email={EMAIL}&IPAddress={IPADDRESS}&Domain={DOMAIN}&LicenseKey={LICENSEKEY} 

XML:  https://trial.serviceobjects.com/ADI/api.svc/xml/FindBestCountry?CompanyName={COMPANYNAME}&FullName={FULLNAME}&FirstName={FIRSTNAME}&LastName={LASTNAME}&Address1={ADDRESS1}&Address2={ADDRESS2}&Address3={ADDRESS3}&Address4={ADDRESS4}&Address5={ADDRESS5}&Address6={ADDRESS6}&Address7={ADDRESS7}&Address8={ADDRESS8}&Locality={LOCALITY}&AdminArea={ADMINAREA}&PostalCode={POSTALCODE}&Phone1={PHONE1}&Phone2={PHONE2}&Phone3={PHONE3}&Email={EMAIL}&IPAddress={IPADDRESS}&Domain={DOMAIN}&LicenseKey={LICENSEKEY}

Click Here for examples and code snippets!


FindBestCountry Inputs

Name

Type

Description

CompanyName

String

The contacts company name. e.g. Service Objects *** This value is not currently used by the service.

FullNameStringThe contact's full name. e.g. Jane Doe *** This value is not currently used by the service.
FirstNameStringFirst name of the contact. e.g. Jane *** This value is not currently used by the service.
LastNameStringLast name of the contact. e.g. Doe *** This value is not currently used by the service.

Address1

String

The address line 1 of the contact or business address.

Address2

String

The address line 2 of the contact or business address.

Address3StringThe address line 3 of the contact or business address.
Address4StringThe address line 4 of the contact or business address.
Address5StringThe address line 5 of the contact or business address.
Address6StringThe address line 6 of the contact or business address.
Address7StringThe address line 7 of the contact or business address.
Address8StringThe address line 8 of the contact or business address.

Locality

String

The locality of the contact's postal address, such as a city, town, village or other type of municipality.

AdminArea

String

The name of the administrative division of the contact's postal address. Commonly the primary division of a country, such as a State, Region, Province, County, Territory or Prefecture.

PostalCode

String

The contact's postal address postal code or its equivalent, such as a ZIP code (US), PLZ (DE, AU, and CH), PIN code (IN) and CAP (IT).

Phone1

String

The contact's primary phone number. e.g. office number

Phone2

String

The contact's secondary phone number. e.g. fax number

Phone3StringThe contact's tertiary phone number. e.g. direct number

Email

String

The contact's email address.

IPAddress

String

The contact's IP address in IPv4. (IPv6 coming in a future release).

Domain

String

Website domain associated with the business. e.g. serviceobjects.com *** This value is not currently used by the service.

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.


FindAddress Outputs

Name

Type

Values

Description

Status

String

OK
WARNING

See "Result Status" for descriptions

Indicates if the request was successfully able to find a best matching country for the contact or not.

TotalScore

String

0-100

Returns a score between 0 and 100.
The score is based on the number of contact components submitted. Some components are worth more than others. For example, the address component will have a higher score than the email component. The more contact component input values that are given, the greater the likelihood for the service to return a high score.

NotesString or NULLSee "Note Codes & Descriptions" for possible values and details.Comma-separated list of descriptive note codes.
NotesDescString or NULLSee "Note Codes & Descriptions" for possible values and details.

Comma-separated list of descriptions that correspond to the Notes output.

WarningsString or NULLSee "Warning Codes & Descriptions" for possible values and details.Comma-separated list of warning codes.
WarningsDescString or NULLSee "Warning Codes & Descriptions" for possible values and details.Comma-separated list of descriptions that correspond to the Warnings output.
Best_CountryNameString or NULLVariesThe name of the country that best matches the contact.
Best_CountryLocalNameString or NULLVaries* The endonym or autonym of the best matching country for the contact. This is the internal name used by the locals of the country. e.g. Germany is Deutschland
Best_CountryISO2String or NULLVariesThe ISO 3166-1 Alpha-2 Country Code of the country that best macthes the contact as a whole.
Best_CountryISO3String or NULLVariesThe ISO 3166-1 Alpha-3 Country Code of the country that best macthes the contact as a whole.
Address_ScoreString or NULLVariesRepresents the score of the contact's address component and how much it contributes to the total score.
Address_CountryNameString or NULLVariesThe name of the country that best matches the contact's address component.
Address_CountryLocalName

String or NULL

Varies

The endonym or autonym of the country that best matches the contact's address component.
Address_CountryISO2

String or NULL

Varies

The ISO 3166-1 Alpha-2 Country Code of the country that best matches the contact's address component.
Address_CountryISO3String or NULLVariesThe ISO 3166-1 Alpha-3 Country Code of the country that best matches the contact's address component.
Address_AllCountriesFoundISO2String or NULLVariesA comma-seperated list of ISO 3166-1 Alpha-2 Country Codes for all the countries that matched the contact's address component.
Phone1_ScoreString or NULLVariesRepresents the score of the contact's phone1 component and how much it contributes to the total score.

Phone1_CountryName

String or NULLVaries

The name of the country that best matches the contact's phone1 component.

Phone1_CountryLocalName

String or NULL

Varies

The endonym or autonym of the country that best matches the contact's phone1 component.

Phone1_CountryISO2

String or NULL

Varies

The ISO 3166-1 Alpha-2 Country Code of the country that best matches the contact's phone1 component.

Phone1_CountryISO3

String or NULL

Varies

The ISO 3166-1 Alpha-3 Country Code of the country that best matches the contact's phone1 component.

Phone1_AllCountriesFoundISO2

String or NULL

Varies

A comma-seperated list of ISO 3166-1 Alpha-2 Country Codes for all the countries that matched the contact's phone1 component.
Phone2_ScoreString or NULLVariesRepresents the score of the contact's phone2 component and how much it contributes to the total score.

Phone2_CountryName

String or NULLVaries

The name of the country that best matches the contact's phone2 component.

Phone2_CountryLocalNameString or NULLVariesThe endonym or autonym of the country that best matches the contact's phone2 component.
Phone2_CountryISO2String or NULLVariesThe ISO 3166-1 Alpha-2 Country Code of the country that best matches the contact's phone2 component.
Phone2_CountryISO3String or NULLVariesThe ISO 3166-1 Alpha-3 Country Code of the country that best matches the contact's phone2 component.
Phone2_AllCountriesFoundISO2String or NULLVariesA comma-seperated list of ISO 3166-1 Alpha-2 Country Codes for all the countries that matched the contact's phone2 component.
Phone3_ScoreString or NULLVariesRepresents the score of the contact's phone3 component and how much it contributes to the total score.
Phone3_CountryNameString or NULLVaries

The name of the country that best matches the contact's phone3 component.

Phone3_CountryLocalNameString or NULLVariesThe endonym or autonym of the country that best matches the contact's phone3 component.
Phone3_CountryISO2String or NULLVariesThe ISO 3166-1 Alpha-2 Country Code of the country that best matches the contact's phone3 component.
Phone3_CountryISO3String or NULLVariesThe ISO 3166-1 Alpha-3 Country Code of the country that best matches the contact's phone3 component.
Phone3_AllCountriesFoundISO2String or NULLVariesA comma-seperated list of ISO 3166-1 Alpha-2 Country Codes for all the countries that matched the contact's phone3 component.
IPAddress_ScoreString or NULLVariesRepresents the score of the contact's IP address component and how much it contributes to the total score.
IPAddress_CountryNameString or NULLVaries

The name of the country that best matches the contact's IP address component.

IPAddress_CountryLocalNameString or NULLVariesThe endonym or autonym of the country that best matches the contact's IP address component.
IPAddress_CountryISO2String or NULLVariesThe ISO 3166-1 Alpha-2 Country Code of the country that best matches the contact's IP address component.
IPAddress_CountryISO3String or NULLVariesThe ISO 3166-1 Alpha-3 Country Code of the country that best matches the contact's IP address component.
IPAddress_AllCountriesFoundISO2String or NULLVariesA comma-seperated list of ISO 3166-1 Alpha-2 Country Codes for all the countries that matched the contact's IP address component.

Email_Score

String or NULLVariesRepresents the score of the contact's email address component and how much it contributes to the total score.
Email_CountryNameString or NULLVaries

The name of the country that best matches the contact's email address component.

Email_CountryLocalNameString or NULLVariesThe endonym or autonym of the country that best matches the contact's email address component.
Email_CountryISO2String or NULLVariesThe ISO 3166-1 Alpha-2 Country Code of the country that best matches the contact's email address component.
Email_CountryISO3String or NULLVariesA comma-seperated list of ISO 3166-1 Alpha-2 Country Codes for all the countries that matched the contact's email address component.
Email_AllCountriesFoundISO2String or NULLVariesA comma-seperated list of ISO 3166-1 Alpha-2 Country Codes for all the countries that matched the contact's email address component.

* Indicates that the output value is coming soon.

Result Status

Name

Description

OK

Indicates that a country was found that best matches the contact.


WARNING

Indicates that a country was not found that best matches the contact.


Note Codes & Descriptions

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

Notes

NotesDesc

Description
0AddressMissingIndicates that no address component values were submitted.
1Phone1MissingIndicates that no value for Phone1 was submitted.
2Phone2MissingIndicates that no value for Phone2 was submitted.
3Phone3MissingIndicates that no value for Phone3 was submitted.
4EmailMissingIndicates that no value for Email was submitted.
5IPMissingIndicates that no value for IPAddress was submitted.
6NameMissingIndicates that no name component values were submitted.
7CompanyNameMissingIndicates that no value for CompanyName was submitted.
8CountryMatch_AddressIndicates that the country that best matches the address also matches the best country for the contact.
9CountryMatch_Phone1Indicates that the country that best matches Phone1 also matches the best country for the contact.
10CountryMatch_Phone2Indicates that the country that best matches Phone2 also matches the best country for the contact.
11CountryMatch_Phone3Indicates that the country that best matches Phone2 also matches the best country for the contact.
12CountryMatch_IPIndicates that the country that best matches IPAddress also matches the best country for the contact.
13CountryMatch_EmailIndicates that the country that best matches Email also matches the best country for the contact.
14CountryMatch_NameIndicates that the country that best matches the name also matches the best country for the contact.
15CountryMatch_CompanyNameIndicates that the country that best matches CompanyName also matches the best country for the contact.
16ContactIsInGDPRIndicates that the best country for the contact is subject to the General Data Protection Regulation (GDPR).
17AddressIsInGDPRIndicates that the address country is subject to the General Data Protection Regulation (GDPR).
18Phone1IsInGDPRIndicates that the Phone1 country is subject to the General Data Protection Regulation (GDPR).
19Phone2IsInGDPRIndicates that the Phone2 country is subject to the General Data Protection Regulation (GDPR).
20Phone3IsInGDPRIndicates that the Phone3 country is subject to the General Data Protection Regulation (GDPR).
21IPAddressIsInGDPRIndicates that the IP address country is subject to the General Data Protection Regulation (GDPR).
22EmailIsInGDPRIndicates that the Email country is subject to the General Data Protection Regulation (GDPR).
23Phone1DerivedFromLengthIndicates that the Phone1 country was derived from examining the length of the phone number and comparing it against known lengths and formats of other countries.
24Phone2DerivedFromLengthIndicates that the Phone2 country was derived from examining the length of the phone number and comparing it against known lengths and formats of other countries.
25Phone3DerivedFromLengthIndicates that the Phone3 country was derived from examining the length of the phone number and comparing it against known lengths and formats of other countries.

Warning Codes & Descriptions

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

Warnings

WarningsDesc

Description
0NoCountryFoundIndicates that no countries were found for any of the input values and therefore a best country could not be found.
1NoBestMatchFoundIndicates that countries were found for the input values; however, a best country could not be found among them.
2NoCountryFound_AddressIndicates that no countries were found for the address component.
3NoCountryFound_Phone1Indicates that no countries were found for the Phone1 component.
4NoCountryFound_Phone2Indicates that no countries were found for the Phone2 component.
5NoCountryFound_Phone3Indicates that no countries were found for the Phone2 component.
6NoCountryFound_IPIndicates that no countries were found for the IP Address component.
7NoCountryFound_EmailIndicates that no countries were found for the Email component.
8CountryMismatch_AddressIndicates that the Best Country does not match the Address component country.
9CountryMismatch_Phone1Indicates that the Best Country does not match the Phone1 component country.
10CountryMismatch_Phone2Indicates that the Best Country does not match the Phone2 component country.
11CountryMismatch_Phone3Indicates that the Best Country does not match the Phone3 component country.
12CountryMismatch_IPIndicates that the Best Country does not match the IP Address component country.
13CountryMismatch_EmailIndicates that the Best Country does not match the Email component country.


Errors

Anything that happens during a run of DOTS Address Detective International 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/adi/

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 Detective International?

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 Detective




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