- C#
- Python
- NodeJS
Address Validation 3 C# Rest Code Snippet
static void Main(string[] args)
{
//Usage example
GetBestMatchesInput In = new("", "26 S Chestnut", "", "Ventura", "CA", "93033", "XXXXXXXXXXXXXX", true);
GBMResponse Response = GetBestMatchesClient.InvokeAsync(In).Result;
}
public static class GetBestMatchesClient
{
// Base URL constants: production, backup, and trial
private const string LiveBaseUrl = "https://sws.serviceobjects.com/AV3/api.svc/";
private const string BackupBaseUrl = "https://swsbackup.serviceobjects.com/AV3/api.svc/";
private const string TrialBaseUrl = "https://trial.serviceobjects.com/AV3/api.svc/";
/// <summary>
/// Synchronously invoke the GetBestMatchesJson endpoint.
/// </summary>
/// <param name="input">Data for the request (address components, license key, isLive).</param>
/// <returns>Deserialized <see cref="GBMResponse"/>.</returns>
public static GBMResponse Invoke(GetBestMatchesInput input)
{
var url = BuildUrl(input, input.IsLive ? LiveBaseUrl : TrialBaseUrl);
var response = Helper.HttpGet<GBMResponse>(url, input.TimeoutSeconds);
// Fallback on error payload in live mode
if (input.IsLive && !IsValid(response))
{
var fallbackUrl = BuildUrl(input, BackupBaseUrl);
var fallbackResponse = Helper.HttpGet<GBMResponse>(fallbackUrl, input.TimeoutSeconds);
return IsValid(fallbackResponse) ? fallbackResponse : response;
}
return response;
}
/// <summary>
/// Asynchronously invoke the GetBestMatchesJson endpoint.
/// </summary>
/// <param name="input">Data for the request (address components, license key, isLive).</param>
/// <returns>Deserialized <see cref="GBMResponse"/>.</returns>
public static async Task<GBMResponse> InvokeAsync(GetBestMatchesInput input)
{
var url = BuildUrl(input, input.IsLive ? LiveBaseUrl : TrialBaseUrl);
var response = await Helper.HttpGetAsync<GBMResponse>(url, input.TimeoutSeconds).ConfigureAwait(false);
if (input.IsLive && !IsValid(response))
{
var fallbackUrl = BuildUrl(input, BackupBaseUrl);
var fallbackResponse = await Helper.HttpGetAsync<GBMResponse>(fallbackUrl, input.TimeoutSeconds).ConfigureAwait(false);
return IsValid(fallbackResponse) ? fallbackResponse : response;
}
return response;
}
/// <summary>
/// Input container for the AV3 GetBestMatches operation.
/// Encapsulates all required address fields, license key, and execution options.
/// </summary>
/// <param name="BusinessName">Company name to assist suite parsing (e.g., "Acme Corp").</param>
/// <param name="Address">Primary street address (e.g., "123 Main St").</param>
/// <param name="Address2">Secondary address information (e.g., "C/O John Smith").</param>
/// <param name="City">City name; required if PostalCode is omitted.</param>
/// <param name="State">State code or full name; required if PostalCode is omitted.</param>
/// <param name="PostalCode">5- or 9-digit ZIP; required if City/State are omitted.</param>
/// <param name="LicenseKey">Service Objects AV3 license key.</param>
/// <param name="IsLive">True to use production endpoints (with fallback); false for trial endpoint only.</param>
/// <param name="TimeoutSeconds">Timeout for HTTP requests in seconds (default: 15).</param>
public record GetBestMatchesInput(
string BusinessName,
string Address,
string Address2,
string City,
string State,
string PostalCode,
string LicenseKey,
bool IsLive,
int TimeoutSeconds = 15
);
// Build the full request URL, including URL-encoded query string
private static string BuildUrl(GetBestMatchesInput input, string baseUrl)
{
var qs = $"GetBestMatchesJson?BusinessName={Helper.UrlEncode(input.BusinessName)}" +
$"&Address={Helper.UrlEncode(input.Address)}" +
$"&Address2={Helper.UrlEncode(input.Address2)}" +
$"&City={Helper.UrlEncode(input.City)}" +
$"&State={Helper.UrlEncode(input.State)}" +
$"&PostalCode={Helper.UrlEncode(input.PostalCode)}" +
$"&LicenseKey={Helper.UrlEncode(input.LicenseKey)}";
return baseUrl + qs;
}
private static bool IsValid(GBMResponse response) => response?.Error == null || response.Error.TypeCode != "3";
}
/// <summary>
/// Represents the response from the GetBestMatches operation,
/// including a list of validated addresses, CASS status, and any error information.
/// </summary>
public class GBMResponse
{
[DataMember(Name = "Addresses")]
public Address[] Addresses { get; set; }
[DataMember(Name = "IsCASS")]
public bool IsCASS { get; set; }
[DataMember(Name = "Error")]
public Error Error { get; set; }
public override string ToString()
{
string Output = "";
Output += $"GBM Response:\n";
Output += $"List of all Addresses: [";
if (Addresses != null && Addresses.Length > 0)
{
foreach (Address A in Addresses)
{
Output += A.ToString() + "\n";
}
}
Output += "]\n";
Output += $"IsCASS: {IsCASS}\n";
Output += $"Error: {{{Error}}}\n";
return Output;
}
}
/// <summary>
/// Represents a single address candidate returned by the AV3 service,
/// including parsed components, delivery indicators, and postal fragments.
/// </summary>
public class Address
{
[DataMember(Name = "Address1")]
public string Address1 { get; set; }
[DataMember(Name = "Address2")]
public string Address2 { get; set; }
[DataMember(Name = "City")]
public string City { get; set; }
[DataMember(Name = "State")]
public string State { get; set; }
[DataMember(Name = "Zip")]
public string Zip { get; set; }
[DataMember(Name = "IsResidential")]
public string IsResidential { get; set; }
[DataMember(Name = "DPV")]
public string DPV { get; set; }
[DataMember(Name = "DPVDesc")]
public string DPVDesc { get; set; }
[DataMember(Name = "DPVNotes")]
public string DPVNotes { get; set; }
[DataMember(Name = "DPVNotesDesc")]
public string DPVNotesDesc { get; set; }
[DataMember(Name = "Corrections")]
public string Corrections { get; set; }
[DataMember(Name = "CorrectionsDesc")]
public string CorrectionsDesc { get; set; }
[DataMember(Name = "BarcodeDigits")]
public string BarcodeDigits { get; set; }
[DataMember(Name = "CarrierRoute")]
public string CarrierRoute { get; set; }
[DataMember(Name = "CongressCode")]
public string CongressCode { get; set; }
[DataMember(Name = "CountyCode")]
public string CountyCode { get; set; }
[DataMember(Name = "CountyName")]
public string CountyName { get; set; }
[DataMember(Name = "FragmentHouse")]
public string FragmentHouse { get; set; }
[DataMember(Name = "FragmentPreDir")]
public string FragmentPreDir { get; set; }
[DataMember(Name = "FragmentStreet")]
public string FragmentStreet { get; set; }
[DataMember(Name = "FragmentSuffix")]
public string FragmentSuffix { get; set; }
[DataMember(Name = "FragmentPostDir")]
public string FragmentPostDir { get; set; }
[DataMember(Name = "FragmentUnit")]
public string FragmentUnit { get; set; }
[DataMember(Name = "Fragment")]
public string Fragment { get; set; }
[DataMember(Name = "FragmentPMBPrefix")]
public string FragmentPMBPrefix { get; set; }
[DataMember(Name = "FragmentPMBNumber")]
public string FragmentPMBNumber { get; set; }
public override string ToString()
{
return $"\n{{Address1: {Address1}\n" +
$"\tAddress2: {Address2}\n" +
$"\tCity: {City}\n" +
$"\tState: {State}\n" +
$"\tZip: {Zip}\n" +
$"\tIsResidential: {IsResidential}\n" +
$"\tDPV: {DPV}\n" +
$"\tDPVDesc: {DPVDesc}\n" +
$"\tDPVNotes: {DPVNotes}\n" +
$"\tDPVNotesDesc: {DPVNotesDesc}\n" +
$"\tCorrections: {Corrections}\n" +
$"\tCorrectionsDesc: {CorrectionsDesc}\n" +
$"\tBarcodeDigits: {BarcodeDigits}\n" +
$"\tCarrierRoute: {CarrierRoute}\n" +
$"\tCongressCode: {CongressCode}\n" +
$"\tCountyCode: {CountyCode}\n" +
$"\tCountyName: {CountyName}\n" +
$"\tFragmentHouse: {FragmentHouse}\n" +
$"\tFragmentPreDir: {FragmentPreDir}\n" +
$"\tFragmentStreet: {FragmentStreet}\n" +
$"\tFragmentSuffix: {FragmentSuffix}\n" +
$"\tFragmentPostDir: {FragmentPostDir}\n" +
$"\tFragmentUnit: {FragmentUnit}\n" +
$"\tFragment: {Fragment}\n" +
$"\tFragmentPMBPrefix: {FragmentPMBPrefix}\n" +
$"\tFragmentPMBNumber: {FragmentPMBNumber}}}\n";
}
}
/// <summary>
/// Represents error information returned by the AV3 service,
/// including error type codes and descriptive messages.
/// </summary>
public class Error
{
[DataMember(Name = "Type")]
public string Type { get; set; }
[DataMember(Name = "TypeCode")]
public string TypeCode { get; set; }
[DataMember(Name = "Desc")]
public string Desc { get; set; }
[DataMember(Name = "DescCode")]
public string DescCode { get; set; }
public override string ToString()
{
return $"Type: {Type} " +
$"TypeCode: {TypeCode} " +
$"Desc: {Desc} " +
$"DescCode: {DescCode} ";
}
}
/// <summary>
/// Utility class providing synchronous and asynchronous HTTP GET methods
/// and URL encoding for ServiceObjects API clients.
/// </summary>
public static class Helper
{
// Reuse a single HttpClient instance for performance and resource management
private static readonly HttpClient HttpClient = new HttpClient();
/// <summary>
/// Performs a synchronous HTTP GET request and deserializes the JSON response into the specified type.
/// </summary>
/// <typeparam name="T">The target type to deserialize the JSON response into.</typeparam>
/// <param name="url">Full URL including query string.</param>
/// <param name="timeoutSeconds">Request timeout in seconds.</param>
/// <returns>Deserialized object of type T.</returns>
public static T HttpGet<T>(string url, int timeoutSeconds)
{
HttpClient.Timeout = TimeSpan.FromSeconds(timeoutSeconds);
using var httpResponse = HttpClient.GetAsync(url).GetAwaiter().GetResult();
httpResponse.EnsureSuccessStatusCode();
var stream = httpResponse.Content.ReadAsStream();
return JsonSerializer.Deserialize<T>(stream)!;
}
/// <summary>
/// Performs an asynchronous HTTP GET request and deserializes the JSON response into the specified type.
/// </summary>
/// <typeparam name="T">The target type to deserialize the JSON response into.</typeparam>
/// <param name="url">Full URL including query string.</param>
/// <param name="timeoutSeconds">Request timeout in seconds.</param>
/// <returns>A Task that resolves to a deserialized object of type T.</returns>
public static async Task<T> HttpGetAsync<T>(string url, int timeoutSeconds)
{
HttpClient.Timeout = TimeSpan.FromSeconds(timeoutSeconds);
using var httpResponse = await HttpClient.GetAsync(url).ConfigureAwait(false);
httpResponse.EnsureSuccessStatusCode();
var stream = await httpResponse.Content.ReadAsStreamAsync().ConfigureAwait(false);
return JsonSerializer.Deserialize<T>(stream)!;
}
/// <summary>
/// URL-encodes the specified string, treating null as an empty string.
/// </summary>
/// <param name="value">The string to URL-encode.</param>
/// <returns>URL-encoded representation of the input.</returns>
public static string UrlEncode(string value) => HttpUtility.UrlEncode(value ?? string.Empty);
}
Address Validation US 3 Python Code Snippet
'''
Service Objects, Inc.
This module provides the get_best_matches function to validate and standardize US addresses
using Service Objects’ AV3 API. It handles live/trial endpoints, fallback logic, and JSON parsing.
Functions:
get_best_matches(business_name: str,
address: str,
address_2: str,
city: str,
state: str,
postal_code: str,
license_key: str,
is_live: bool) -> dict:
'''
import requests # HTTP client for RESTful API calls
# Endpoint URLs for AV3 service
primary_url = 'https://sws.serviceobjects.com/AV3/api.svc/GetBestMatchesJson?'
backup_url = 'https://swsbackup.serviceobjects.com/AV3/api.svc/GetBestMatchesJson?'
trial_url = 'https://trial.serviceobjects.com/AV3/api.svc/GetBestMatchesJson?'
def get_best_matches(business_name: str,
address: str,
address_2: str,
city: str,
state: str,
postal_code: str,
license_key: str,
is_live: bool) -> dict:
'''
Call AV3 get_best_matches API and return validation results.
Parameters:
business_name (str): Company name to assist suite parsing.
address (str): Primary street address (e.g., '123 Main St'). Required.
address_2 (str): Secondary address info (e.g., 'C/O John Smith').
city (str): City name; required if PostalCode not provided.
state (str): State code or full name; required if PostalCode not provided.
postal_code (str): 5- or 9-digit ZIP; required if City/State not provided.
license_key (str): Service Objects license key.
is_live (bool): True for production endpoints, False for trial URL.
Returns:
dict: Parsed JSON response with address candidates or error info.
'''
# Prepare query parameters for AV3 API
params = {
'BusinessName': business_name,
'Address' : address,
'Address2' : address_2,
'City' : city,
'State' : state,
'PostalCode' : postal_code,
'LicenseKey' : license_key
}
# Select the base URL: production vs trial
url = primary_url if is_live else trial_url
# Attempt primary (or trial) endpoint first
try:
response = requests.get(url, params=params, timeout=10)
data = response.json()
# If API returned an error in JSON payload, trigger fallback
if 'Error' in data:
if is_live:
# Try backup URL when live
response = requests.get(backup_url, params=params, timeout=10)
data = response.json()
# If still error, propagate exception
if 'Error' in data:
raise RuntimeError(f"AV3 service error: {data['Error']}")
else:
# Trial mode should not fallback; error is terminal
raise RuntimeError(f"AV3 trial error: {data['Error']}")
# Success: return parsed JSON data
return data
except requests.RequestException as req_exc:
# Network or HTTP-level error occurred
# TODO: Instrument alerting on repeated failures
if is_live:
try:
# Fallback to backup URL on network failure
response = requests.get(backup_url, params=params, timeout=10)
data = response.json()
if 'Error' in data:
raise RuntimeError(f"AV3 backup error: {data['Error']}")
return data
except Exception as backup_exc:
# Both primary and backup failed; escalate
raise RuntimeError("AV3 service unreachable on both endpoints") from backup_exc
else:
# In trial mode, propagate the network exception
raise
Address Validation 3 NodeJS REST Code Snippet
/**
* @module AV3AddressValidation
* @description
* Client module for the AV3 GetBestMatchesJson operation.
* Validates and standardizes U.S. addresses via Service Objects’ AV3 API,
* with built‑in production/trial endpoints and automatic fallback logic.
*/
import fetch from 'node-fetch';
// Base endpoints for AV3 service
const ENDPOINTS = {
production: 'https://ws.serviceobjects.com/av3/api.svc/',
backup: 'https://wsbackup.serviceobjects.com/av3/api.svc/',
trial: 'https://trial.serviceobjects.com/av3/api.svc/'
};
/**
* Build a fully‑qualified URL for the GetBestMatchesJson endpoint.
* @param {object} params Key/value pairs of query parameters.
* @param {string} baseUrl Base URL (must end with '/').
* @returns {string} Fully‑qualified URL including encoded query string.
*/
function buildGetBestMatchesUrl(params, baseUrl) {
const url = new URL('GetBestMatchesJson', baseUrl);
Object.entries(params).forEach(([key, value]) => {
url.searchParams.append(key, value ?? '');
});
return url.toString();
}
/**
* Perform an HTTP GET request and parse JSON response.
* @param {string} url URL to request.
* @returns {Promise<any>} Parsed JSON body.
* @throws {Error} On HTTP or parse errors.
*/
async function httpGetJson(url) {
const res = await fetch(url);
if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
return res.json();
}
/**
* @typedef {object} GetBestMatchesOptions
* @property {string} businessName Company name to assist suite parsing.
* @property {string} address Primary street address (e.g., '123 Main St').
* @property {string} [address2] Secondary address info (e.g., 'C/O John Smith').
* @property {string} [city] City; required if postalCode omitted.
* @property {string} [state] State code or full name; required if postalCode omitted.
* @property {string} [postalCode] 5‑ or 9‑digit ZIP; required if city/state omitted.
* @property {string} licenseKey Valid AV3 license key.
* @property {'production'|'trial'} [environment='production']
* 'production' for live+backup, 'trial' for trial only.
* @property {number} [timeoutMs=15000]
* Request timeout in milliseconds.
*/
/**
* Retrieve standardized address candidates via AV3 GetBestMatches.
* Automatically falls back from production to backup on error TypeCode '3'.
* @param {GetBestMatchesOptions} opts Operation settings.
* @returns {Promise<object>} Service response JSON.
* @throws {Error} On unrecoverable HTTP or service errors.
*/
export async function getBestMatches(opts) {
const {
businessName,
address,
address2 = '',
city = '',
state = '',
postalCode = '',
licenseKey,
environment = 'production',
timeoutMs = 15000
} = opts;
// Assemble query parameters matching API names
const params = {
BusinessName: businessName,
Address: address,
Address2: address2,
City: city,
State: state,
PostalCode: postalCode,
LicenseKey: licenseKey
};
// Choose primary URL based on environment
const baseUrl = environment === 'trial' ? ENDPOINTS.trial : ENDPOINTS.production;
const primaryUrl = buildGetBestMatchesUrl(params, baseUrl);
// Helper to call with timeout
const call = url => Promise.race([
httpGetJson(url),
new Promise((_, rej) => setTimeout(() => rej(new Error('Timeout')), timeoutMs))
]);
try {
let result = await call(primaryUrl);
// Fallback if production + service-level fatal error
if (environment === 'production' && result.Error?.TypeCode === '3') {
const backupUrl = buildGetBestMatchesUrl(params, ENDPOINTS.backup);
result = await call(backupUrl);
}
return result;
} catch (err) {
// On network or HTTP failure, retry backup for production
if (environment === 'production') {
const backupUrl = buildGetBestMatchesUrl(params, ENDPOINTS.backup);
return call(backupUrl);
}
throw err;
}
}