- C#
- Python
- NodeJS
Address Insight C# Code Snippet
using AIUSReference;
namespace address_insight_us_dot_net.SOAP
{
/// <summary>
/// Provides functionality to call the ServiceObjects AddressInsight (AIN) SOAP service's GetAddressInsight operation,
/// retrieving address validation, geocoding, and demographic information for a given US address
/// with fallback to a backup endpoint for reliability in live mode.
/// </summary>
public class GetAddressInsightValidation
{
private const string LiveBaseUrl = "https://sws.serviceobjects.com/AIN/SOAP.svc/SOAP";
private const string BackupBaseUrl = "https://swsbackup.serviceobjects.com/AIN/SOAP.svc/SOAP";
private const string TrialBaseUrl = "https://trial.serviceobjects.com/AIN/SOAP.svc/SOAP";
private readonly string _primaryUrl;
private readonly string _backupUrl;
private readonly int _timeoutMs;
private readonly bool _isLive;
/// <summary>
/// Initializes URLs, timeout, and IsLive.
/// </summary>
public GetAddressInsightValidation(bool isLive)
{
_timeoutMs = 10000;
_isLive = isLive;
_primaryUrl = isLive ? LiveBaseUrl : TrialBaseUrl;
_backupUrl = isLive ? BackupBaseUrl : TrialBaseUrl;
if (string.IsNullOrWhiteSpace(_primaryUrl))
throw new InvalidOperationException("Primary URL not set.");
if (string.IsNullOrWhiteSpace(_backupUrl))
throw new InvalidOperationException("Backup URL not set.");
}
/// <summary>
/// This operation returns the best available address insight data for a given US address, including
/// address validation, geocoding, and demographic information.
/// </summary>
/// <param name="BusinessName">A company name for a business, can provide additional insight or append a SuiteLink value. Optional.</param>
/// <param name="Address1">Address line 1 of the contact or business address (e.g., "123 Main Street").</param>
/// <param name="Address2">Address line 2 of the contact or business address (e.g., "Apt 4B"). Optional.</param>
/// <param name="City">The city of the address (e.g., "New York"). Optional if zip is provided.</param>
/// <param name="State">The state of the address (e.g., "NY"). Optional if zip is provided.</param>
/// <param name="Zip">The ZIP code of the address. Optional if city and state are provided.</param>
/// <param name="TestType">The test type, either empty or "census_loose" for best possible match based on census data. Optional.</param>
/// <param name="LicenseKey">The license key to authenticate the API request.</param>
public async Task<ResponseObject> GetAddressInsight(string BusinessName, string Address1, string Address2, string City, string State, string Zip, string TestType, string LicenseKey)
{
SOAPClient clientPrimary = null;
SOAPClient clientBackup = null;
try
{
// Attempt Primary
clientPrimary = new SOAPClient();
clientPrimary.Endpoint.Address = new System.ServiceModel.EndpointAddress(_primaryUrl);
clientPrimary.InnerChannel.OperationTimeout = TimeSpan.FromMilliseconds(_timeoutMs);
ResponseObject response = await clientPrimary.GetAddressInsightAsync(
BusinessName, Address1, Address2, City, State, Zip, TestType, LicenseKey).ConfigureAwait(false);
if (_isLive && !IsValid(response))
{
throw new InvalidOperationException("Primary endpoint returned null or a fatal TypeCode=3 error for GetAddressInsight");
}
return response;
}
catch (Exception primaryEx)
{
try
{
clientBackup = new SOAPClient();
clientBackup.Endpoint.Address = new System.ServiceModel.EndpointAddress(_backupUrl);
clientBackup.InnerChannel.OperationTimeout = TimeSpan.FromMilliseconds(_timeoutMs);
return await clientBackup.GetAddressInsightAsync(
BusinessName, Address1, Address2, City, State, Zip, TestType, LicenseKey).ConfigureAwait(false);
}
catch (Exception backupEx)
{
throw new InvalidOperationException(
$"Both primary and backup endpoints failed.\n" +
$"Primary error: {primaryEx.Message}\n" +
$"Backup error: {backupEx.Message}");
}
finally
{
clientBackup.Close();
}
}
finally
{
clientPrimary.Close();
}
}
private static bool IsValid(ResponseObject response)
{
if (response.TryGetValue("Error", out var resultObject) && resultObject != null)
{
var errorField = resultObject.FirstOrDefault()?.FirstOrDefault(f => f.Key == "TypeCode");
if (errorField != null && errorField.Value.Value == "3")
return false;
}
return true;
}
}
}
Address Insight Python Code Snippet
from suds.client import Client
from suds import WebFault
from suds.sudsobject import Object
class GetAddressInsightSoap:
def __init__(self, license_key: str, is_live: bool = True, timeout_ms: int = 15000):
"""
license_key: Service Objects AIN license key.
is_live: Whether to use live or trial endpoints
timeout_ms: SOAP call timeout in milliseconds
"""
self.is_live = is_live
self.timeout = timeout_ms / 1000.0
self.license_key = license_key
# WSDL URLs
self._primary_wsdl = (
"https://sws.serviceobjects.com/AIN/SOAP.svc?wsdl"
if is_live
else "https://trial.serviceobjects.com/AIN/SOAP.svc?wsdl"
)
self._backup_wsdl = (
"https://swsbackup.serviceobjects.com/AIN/SOAP.svc?wsdl"
if is_live
else "https://trial.serviceobjects.com/AIN/SOAP.svc?wsdl"
)
def get_address_insight(
self,
business_name: str,
address1: str,
address2: str,
city: str,
state: str,
zip_code: str,
test_type: str,
) -> Object:
"""
Calls the GetAddressInsight SOAP API to retrieve the information.
Parameters:
business_name: A company name for a business, can provide additional insight or append a SuiteLink value. Optional.
address1: Address line 1 of the contact or business address (e.g., "123 Main Street").
address2: Address line 2 of the contact or business address (e.g., "Apt 4B"). Optional.
city: The city of the address (e.g., "New York"). Optional if zip is provided.
state: The state of the address (e.g., "NY"). Optional if zip is provided.
zip_code: The ZIP code of the address. Optional if city and state are provided.
test_type: The test type, either empty or "census_loose" for best possible match based on census data. Optional.
license_key: Your ServiceObjects license key.
is_live: Determines whether to use the live or trial servers.
timeout_ms: Timeout, in milliseconds, for the call to the service.
Returns:
suds.sudsobject.Object: SOAP response containing address insight details or error.
"""
# Common kwargs for both calls
call_kwargs = dict(
BusinessName=business_name,
Address1=address1,
Address2=address2,
City=city,
State=state,
Zip=zip_code,
TestType=test_type,
LicenseKey=self.license_key,
)
# Attempt primary
try:
client = Client(self._primary_wsdl)
# Override endpoint URL if needed:
# client.set_options(location=self._primary_wsdl.replace('?wsdl','/soap'))
response = client.service.GetAddressInsight(**call_kwargs)
# If response invalid or Error.TypeCode == "3", trigger fallback
if response is None or (
hasattr(response, "Error")
and response.Error
and hasattr(response.Error, "TypeCode")
and response.Error.TypeCode == "3"
):
raise ValueError("Primary returned no result or Error.TypeCode=3")
return response
except (WebFault, ValueError, Exception) as primary_ex:
# Attempt backup
try:
client = Client(self._backup_wsdl)
response = client.service.GetAddressInsight(**call_kwargs)
if response is None:
raise ValueError("Backup returned no result")
return response
except (WebFault, Exception) as backup_ex:
msg = (
"Both primary and backup endpoints failed.\n"
f"Primary error: {str(primary_ex)}\n"
f"Backup error: {str(backup_ex)}"
)
raise RuntimeError(msg)
Address Insight NodeJS Code Snippet
import { soap } from 'strong-soap';
/**
* <summary>
* A class that provides functionality to call the ServiceObjects AddressInsight (AIN) SOAP service's GetAddressInsight endpoint,
* retrieving address validation, geocoding, and demographic information for a given US address with fallback to a backup endpoint for reliability in live mode.
* </summary>
*/
class GetAddressInsightSoap {
/**
* <summary>
* Initializes a new instance of the GetAddressInsightSoap class with the provided input parameters,
* setting up primary and backup WSDL URLs based on the live/trial mode.
* </summary>
* @param {string} BusinessName - A company name for a business, can provide additional insight or append a SuiteLink value. Optional.
* @param {string} Address1 - Address line 1 of the contact or business address (e.g., "123 Main Street").
* @param {string} Address2 - Address line 2 of the contact or business address (e.g., "Apt 4B"). Optional.
* @param {string} City - The city of the address (e.g., "New York"). Optional if zip is provided.
* @param {string} State - The state of the address (e.g., "NY"). Optional if zip is provided.
* @param {string} Zip - The ZIP code of the address. Optional if city and state are provided.
* @param {string} TestType - The test type, either empty or "census_loose" for best possible match based on census data. Optional.
* @param {string} LicenseKey - Your license key to use the service.
* @param {boolean} isLive - Value to determine whether to use the live or trial servers.
* @param {number} timeoutSeconds - Timeout, in seconds, for the call to the service.
* @throws {Error} Thrown if LicenseKey is empty or null.
*/
constructor(BusinessName, Address1, Address2, City, State, Zip, TestType, LicenseKey, isLive = true, timeoutSeconds = 15) {
this.args = {
BusinessName,
Address1,
Address2,
City,
State,
Zip,
TestType,
LicenseKey
};
this.isLive = isLive;
this.timeoutSeconds = timeoutSeconds;
this.LiveBaseUrl = 'https://sws.serviceobjects.com/AIN/SOAP.svc?wsdl';
this.BackupBaseUrl = 'https://swsbackup.serviceobjects.com/AIN/SOAP.svc?wsdl';
this.TrialBaseUrl = 'https://trial.serviceobjects.com/AIN/SOAP.svc?wsdl';
this._primaryWsdl = this.isLive ? this.LiveBaseUrl : this.TrialBaseUrl;
this._backupWsdl = this.isLive ? this.BackupBaseUrl : this.TrialBaseUrl;
}
/**
* <summary>
* Asynchronously calls the GetAddressInsight SOAP endpoint, attempting the primary endpoint
* first and falling back to the backup if the response is invalid (Error.TypeCode == '3') in live mode
* or if the primary call fails.
* </summary>
* @returns {Promise<Object>} A promise that resolves to an object containing address insight details or an error.
* @throws {Error} Thrown if both primary and backup calls fail, with detailed error messages.
*/
async invokeAsync() {
try {
const primaryResult = await this._callSoap(this._primaryWsdl, this.args);
if (this.isLive && !this._isValid(primaryResult)) {
console.warn("Primary returned Error.TypeCode == '3', falling back to backup...");
const backupResult = await this._callSoap(this._backupWsdl, this.args);
return backupResult;
}
return primaryResult;
} catch (primaryErr) {
try {
const backupResult = await this._callSoap(this._backupWsdl, this.args);
return backupResult;
} catch (backupErr) {
throw new Error(`Both primary and backup calls failed:\nPrimary: ${primaryErr.message}\nBackup: ${backupErr.message}`);
}
}
}
/**
* <summary>
* Performs a SOAP service call to the specified WSDL URL with the given arguments,
* creating a client and processing the response into an object.
* </summary>
* @param {string} wsdlUrl - The WSDL URL of the SOAP service endpoint (primary or backup).
* @param {Object} args - The arguments to pass to the GetAddressInsight method.
* @returns {Promise<Object>} A promise that resolves to an object containing the SOAP response data.
* @throws {Error} Thrown if the SOAP client creation fails, the service call fails, or the response cannot be parsed.
*/
_callSoap(wsdlUrl, args) {
return new Promise((resolve, reject) => {
soap.createClient(wsdlUrl, { timeout: this.timeoutSeconds * 1000 }, (err, client) => {
if (err) return reject(err);
client.GetAddressInsight(args, (err, result) => {
const response = result?.GetAddressInsightResult;
try {
if (!response) {
return reject(new Error("SOAP response is empty or undefined."));
}
resolve(response);
} catch (parseErr) {
reject(new Error(`Failed to parse SOAP response: ${parseErr.message}`));
}
});
});
});
}
/**
* <summary>
* Checks if a SOAP response is valid by verifying that it exists and either has no Error object
* or the Error.TypeCode is not equal to '3'.
* </summary>
* @param {Object} response - The response object to validate.
* @returns {boolean} True if the response is valid, false otherwise.
*/
_isValid(response) {
if (!response) return false;
if (response.Error) {
const errorFields = response.Error.Result?.[0]?.Field || [];
const typeCode = errorFields.find(field => field.Key === 'TypeCode')?.Value;
return typeCode !== '3';
}
return true;
}
}
export { GetAddressInsightSoap };