AV3 – REST 

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);
        }