Documentation

 

SmartyStreets .NET SDK

If you want to access our APIs (other than the Download API) from a C#, F#, or Visual Basic application, the SmartyStreets .NET SDK can make it a lot easier. Our .NET SDK includes ready-made data structures and takes care of all the gritty, low-level HTTP intricacies for you.

Contents

  1. Requirements
  2. How to Get It
    1. NuGet
    2. Download the Source Code
  3. How to Use It
    1. Demo
    2. Examples
  4. API Reference Material

Requirements

  1. Decide to build a software project using a programming language compatible with the .Net/Mono framework (like C#).
  2. The minimum supported .NET framework is version 4.5.
  3. Build enough of the project to realize that you now need an address verification component.
  4. Wisely conclude that you don't want to build your own address verification component.
  5. Realize that SmartyStreets has already created an address verification component.
  6. Congratulations! You are now ready to use the SmartyStreets .NET SDK.

How to Get It

NuGet

The easiest way to install this SDK is by using NuGet. Visual Studio and Xamarin both have NuGet plugins, but you can also run the following command in the Package Manager Console:

PM> Install-Package smartystreets-dotnet-sdk

Or you can run this command in the command line:

nuget install smartystreets-dotnet-sdk

Download the Source Code

You can download the source code from the SmartyStreets .Net SDK repository on Github.

Use the source, Luke!

How to Use It

Demo

Examples

Here are a few pieces of example code to show how to use our .NET library/SDK.

Verifying a Single US Street Address

namespace Examples
{
	using System;
	using System.IO;
	using SmartyStreets;
	using SmartyStreets.USStreetApi;

	public class USStreetSingleAddressExample
	{
		public static void Run()
		{
			var authId = Environment.GetEnvironmentVariable("SMARTY_AUTH_ID");
			var authToken = Environment.GetEnvironmentVariable("SMARTY_AUTH_TOKEN");
			var client = new ClientBuilder(authId, authToken).BuildUsStreetApiClient();

			var lookup = new Lookup
			{
				Street = "1600 Amphitheatre Pkwy",
				City = "Mountain View",
				State = "CA"
			};

			try
			{
				client.Send(lookup);
			}
			catch (SmartyException ex)
			{
				Console.WriteLine(ex.Message);
				Console.WriteLine(ex.StackTrace);
			}
			catch (IOException ex)
			{
				Console.WriteLine(ex.StackTrace);
			}

			var candidates = lookup.Result;

			if (candidates.Count == 0)
			{
				Console.WriteLine("No candidates. This means the address is not valid.");
				return;
			}

			var firstCandidate = candidates[0];

			Console.WriteLine("Address is valid. (There is at least one candidate)\n");
			Console.WriteLine("ZIP Code: " + firstCandidate.Components.ZipCode);
			Console.WriteLine("County: " + firstCandidate.Metadata.CountyName);
			Console.WriteLine("Latitude: " + firstCandidate.Metadata.Latitude);
			Console.WriteLine("Longitude: " + firstCandidate.Metadata.Longitude);
		}
	}
}

Verifying Multiple US Street Addresses

namespace Examples
{
	using System;
	using System.IO;
	using SmartyStreets;
	using SmartyStreets.USStreetApi;

	public class USStreetMultipleAddressesExample
	{
		public static void Run()
		{
			var authId = Environment.GetEnvironmentVariable("SMARTY_AUTH_ID");
			var authToken = Environment.GetEnvironmentVariable("SMARTY_AUTH_TOKEN");
			var client = new ClientBuilder(authId, authToken).BuildUsStreetApiClient();
			var batch = new Batch();

			var address1 = new Lookup
			{
				Street = "1600 amphitheatre parkway",
				City = "Mountain view",
				State = "california"
			};

			var address2 = new Lookup("1 Rosedale, Baltimore, Maryland")
			{
				MaxCandidates = 10
			}; // Freeform addresses work too.

			var address3 = new Lookup("123 Bogus Street, Pretend Lake, Oklahoma");

			var address4 = new Lookup
			{
				Street = "1 Infinite Loop",
				ZipCode = "95014"
			};

			try
			{
				batch.Add(address1);
				batch.Add(address2);
				batch.Add(address3);
				batch.Add(address4);

				client.Send(batch);
			}
			catch (BatchFullException)
			{
				Console.WriteLine("Error. The batch is already full.");
			}
			catch (SmartyException ex)
			{
				Console.WriteLine(ex.Message);
				Console.WriteLine(ex.StackTrace);
			}
			catch (IOException ex)
			{
				Console.WriteLine(ex.StackTrace);
			}

			for (var i = 0; i < batch.Count; i++)
			{
				var candidates = batch[i].Result;

				if (candidates.Count == 0)
				{
					Console.WriteLine("Address " + i + " is invalid.\n");
					continue;
				}

				Console.WriteLine("Address " + i + " is valid. (There is at least one candidate)");

				foreach (var candidate in candidates)
				{
					var components = candidate.Components;
					var metadata = candidate.Metadata;

					Console.WriteLine("\nCandidate " + candidate.CandidateIndex + ":");
					Console.WriteLine("Delivery line 1: " + candidate.DeliveryLine1);
					Console.WriteLine("Last line:       " + candidate.LastLine);
					Console.WriteLine("ZIP Code:        " + components.ZipCode + "-" + components.Plus4Code);
					Console.WriteLine("County:          " + metadata.CountyName);
					Console.WriteLine("Latitude:        " + metadata.Latitude);
					Console.WriteLine("Longitude:       " + metadata.Longitude);
				}
				Console.WriteLine();
			}
		}
	}
}

Sending a Single Lookup to the US ZIP Code API

namespace Examples
{
	using System;
	using System.IO;
	using SmartyStreets;
	using SmartyStreets.USZipCodeApi;

	public class USZipCodeSingleLookupExample
	{
		public static void Run()
		{
			var authId = Environment.GetEnvironmentVariable("SMARTY_AUTH_ID");
			var authToken = Environment.GetEnvironmentVariable("SMARTY_AUTH_TOKEN");
			var client = new ClientBuilder(authId, authToken).BuildUsZipCodeApiClient();

			var lookup = new Lookup
			{
				City = "Mountain View",
				State = "California"
			};

			try
			{
				client.Send(lookup);
			}
			catch (SmartyException ex)
			{
				Console.WriteLine(ex.Message);
				Console.WriteLine(ex.StackTrace);
			}
			catch (IOException ex)
			{
				Console.WriteLine(ex.StackTrace);
			}

			var result = lookup.Result;
			var cities = result.CityStates;
			var zipCodes = result.ZipCodes;

			foreach (var city in cities)
			{
				Console.WriteLine("\nCity: " + city.City);
				Console.WriteLine("State: " + city.State);
				Console.WriteLine("Mailable City: " + city.MailableCity);
			}

			foreach (var zipCode in zipCodes)
			{
				Console.WriteLine("\nZIP Code: " + zipCode.ZipCode);
				Console.WriteLine("Latitude: " + zipCode.Latitude);
				Console.WriteLine("Longitude: " + zipCode.Longitude);
			}
		}
	}
}

Sending Multiple Lookups to the US ZIP Code API

namespace Examples
{
	using System;
	using System.IO;
	using SmartyStreets;
	using SmartyStreets.USZipCodeApi;

	public class USZipCodeMultipleLookupsExample
	{
		public static void Run()
		{
			var authId = Environment.GetEnvironmentVariable("SMARTY_AUTH_ID");
			var authToken = Environment.GetEnvironmentVariable("SMARTY_AUTH_TOKEN");
			var client = new ClientBuilder(authId, authToken).BuildUsZipCodeApiClient();

			var lookup1 = new Lookup
			{
				ZipCode = "12345"
			};

			var lookup2 = new Lookup
			{
				City = "Phoenix",
				State = "Arizona"
			};

			var lookup3 = new Lookup("cupertino", "CA", "95014"); // You can also set these with arguments

			var batch = new Batch();

			try
			{
				batch.Add(lookup1);
				batch.Add(lookup2);
				batch.Add(lookup3);

				client.Send(batch);
			}
			catch (BatchFullException)
			{
				Console.WriteLine("Error. The batch is already full.");
			}
			catch (SmartyException ex)
			{
				Console.WriteLine(ex.Message);
				Console.WriteLine(ex.StackTrace);
			}
			catch (IOException ex)
			{
				Console.WriteLine(ex.StackTrace);
			}

			for (var i = 0; i < batch.Count; i++)
			{
				var result = batch[i].Result;
				Console.WriteLine("Lookup " + i + ":\n");

				if (result.Status != null)
				{
					Console.WriteLine("Status: " + result.Status);
					Console.WriteLine("Reason: " + result.Reason);
					continue;
				}

				var cityStates = result.CityStates;
				Console.WriteLine(cityStates.Length + " City and State match" + ((cityStates.Length == 1) ? ":" : "es:"));

				foreach (var cityState in cityStates)
				{
					Console.WriteLine("City: " + cityState.City);
					Console.WriteLine("State: " + cityState.State);
					Console.WriteLine("Mailable City: " + cityState.MailableCity);
					Console.WriteLine();
				}

				var zipCodes = result.ZipCodes;
				Console.WriteLine(zipCodes.Length + " ZIP Code match" + ((cityStates.Length == 1) ? ":" : "es:"));

				foreach (var zipCode in zipCodes)
				{
					Console.WriteLine("ZIP Code: " + zipCode.ZipCode);
					Console.WriteLine("County: " + zipCode.CountyName);
					Console.WriteLine("Latitude: " + zipCode.Latitude);
					Console.WriteLine("Longitude: " + zipCode.Longitude);
					Console.WriteLine();
				}
				Console.WriteLine("***********************************");
			}
		}
	}
}

Sending the Beginning of an Address to the US Autocomplete API

using System;
using SmartyStreets;
using SmartyStreets.USAutocompleteApi;

namespace Examples
{
    public class USAutocompleteExample
    {
        public static void Run()
        {
            // We recommend storing your secret keys in environment variables.
            var authId = Environment.GetEnvironmentVariable("SMARTY_AUTH_ID");
            var authToken = Environment.GetEnvironmentVariable("SMARTY_AUTH_TOKEN");
            var client = new ClientBuilder(authId, authToken).BuildUsAutocompleteApiClient();
            var lookup = new Lookup("4770 Lincoln Ave O");

            client.Send(lookup);

            Console.WriteLine("*** Result with no filter ***");
            Console.WriteLine();
            foreach (var suggestion in lookup.Result)
            {
                Console.WriteLine(suggestion.Text);
            }

            lookup.AddStateFilter("IL");
            lookup.MaxSuggestions = 5;

            var suggestions = client.Send(lookup); // The client will also return the suggestions directly

            Console.WriteLine();
            Console.WriteLine("*** Result with some filters ***");
            foreach (var suggestion in suggestions)
            {
                Console.WriteLine(suggestion.Text);
            }
        }
    }
}

Sending Text to the US Extract API

using System;
using SmartyStreets;
using Lookup = SmartyStreets.USExtractApi.Lookup;

namespace Examples
{
    public class USExtractExample
    {
        public static void Run()
        {
            // We recommend storing your secret keys in environment variables.
            var authId = Environment.GetEnvironmentVariable("SMARTY_AUTH_ID");
            var authToken = Environment.GetEnvironmentVariable("SMARTY_AUTH_TOKEN");
            var client = new ClientBuilder(authId, authToken).BuildUsExtractApiClient();
            var text = "Here is some text.\r\nMy address is 3785 Las Vegs Av." +
                          "\r\nLos Vegas, Nevada." +
                          "\r\nMeet me at 1 Rosedale Baltimore Maryland, not at 123 Phony Street, Boise Idaho.";
            var lookup = new Lookup(text);

            var result = client.Send(lookup);

            var metadata = result.Metadata;
            Console.WriteLine("Found " + metadata.AddressCount + " addresses.");
            Console.WriteLine(metadata.VerifiedCount + " of them were valid.");
            Console.WriteLine();

            var addresses = result.Addresses;

            Console.WriteLine("Addresses: \r\n**********************\r\n");
            foreach (var address in addresses)
            {
                Console.WriteLine("\"" + address.Text + "\"\n");
                Console.WriteLine("Verified? " + address.Verified);
                if (address.Candidates.Length > 0)
                {
                    Console.WriteLine("\nMatches:");

                    foreach (var candidate in address.Candidates)
                    {
                        Console.WriteLine(candidate.DeliveryLine1);
                        Console.WriteLine(candidate.LastLine);
                        Console.WriteLine();
                    }
                } else Console.WriteLine();

                Console.WriteLine("**********************\n");
            }
        }
    }
}

Verifying an International Street Address

using System;
using SmartyStreets;
using SmartyStreets.InternationalStreetApi;

namespace Examples
{
    public class InternationalStreetExample
    {
        public static void Run()
        {
            // We recommend storing your secret keys in environment variables.
            var authId = Environment.GetEnvironmentVariable("SMARTY_AUTH_ID");
            var authToken = Environment.GetEnvironmentVariable("SMARTY_AUTH_TOKEN");
            var client = new ClientBuilder(authId, authToken).BuildInternationalStreetApiClient();

            var lookup = new Lookup("Rua Padre Antonio D'Angelo 121 Casa Verde, Sao Paulo", "Brazil");
            lookup.Geocode = true; // Must be expressly set to get latitude and longitude.

            var candidates = client.Send(lookup); // The candidates are also stored in the lookup's 'result' field.

            var firstCandidate = candidates[0];
            Console.WriteLine("Address is " + firstCandidate.Analysis.VerificationStatus);
            Console.WriteLine("Address precision: " + firstCandidate.Analysis.AddressPrecision + "\n");

            Console.WriteLine("First Line: " + firstCandidate.Address1);
            Console.WriteLine("Second Line: " + firstCandidate.Address2);
            Console.WriteLine("Third Line: " + firstCandidate.Address3);
            Console.WriteLine("Fourth Line: " + firstCandidate.Address4);
            Console.WriteLine("Latitude: " + firstCandidate.Metadata.Latitude);
            Console.WriteLine("Longitude: " + firstCandidate.Metadata.Longitude);
        }
    }
}