Using USPS APIs in C#
Do you want to know how to use the USPS API in C#? We'll show you how, and share step-by-step examples with you. (You may also want to check out our video tutorial on how to use the USPS APIs in C#).
In this article, we'll discuss:
Creating a USPS Account
Before you can use the USPS APIs, you will need to
register
with the USPS to receive a USERID. This ID is used in the sample code below where
"USERID" is mentioned.
Types of USPS APIs
- There are three USPS APIs available:
- Address Standardization: validates an address and returns the accepted standardized version of it with other helpful metadata.
- ZIP Code Lookup: a simplified version of the standardization API and returns the ZIP Code and ZIP+4.
- City/State Lookup: returns the city and state associated with a specified ZIP Code.
- You can only make up to 5 requests per API call.
- XML is used for the Request and Response docs. (Bummer)
Code Examples
Note that these samples require a USERID (see Register above).
Address Standardization Sample Code
using System;
using System.Net;
using System.Xml.Linq;
namespace USPSApi_CLI {
class USPSAddressStandardization {
public static void Main() {
XDocument requestDoc = new XDocument(
new XElement("AddressValidateRequest",
new XAttribute("USERID", ""),
new XElement("Revision", "1"),
new XElement("Address",
new XAttribute("ID", "0"),
new XElement("Address1", "2335 S State"),
new XElement("Address2", "Suite 300"),
new XElement("City", "Provo"),
new XElement("State", "UT"),
new XElement("Zip5", "84604"),
new XElement("Zip4", "")
)
)
);
try {
var url = "http://production.shippingapis.com/ShippingAPI.dll?API=Verify&XML=" + requestDoc;
Console.WriteLine(url);
var client = new WebClient();
var response = client.DownloadString(url);
var xdoc = XDocument.Parse(response.ToString());
Console.WriteLine(xdoc.ToString());
foreach (XElement element in xdoc.Descendants("Address")) {
Console.WriteLine("-------------------------------");
Console.WriteLine("Address ID: " + GetXMLAttribute(element, "ID"));
Console.WriteLine("Address1: " + GetXMLElement(element, "Address1"));
Console.WriteLine("Address2: " + GetXMLElement(element, "Address2"));
Console.WriteLine("City: " + GetXMLElement(element, "City"));
Console.WriteLine("State: " + GetXMLElement(element, "State"));
Console.WriteLine("Zip5: " + GetXMLElement(element, "Zip5"));
Console.WriteLine("Zip4: " + GetXMLElement(element, "Zip4"));
}
}
catch (WebException e) {
Console.WriteLine(e.ToString());
}
}
public static string GetXMLElement(XElement element, string name) {
var el = element.Element(name);
if (el != null) {
return el.Value;
}
return "";
}
public static string GetXMLAttribute(XElement element, string name) {
var el = element.Attribute(name);
if (el != null) {
return el.Value;
}
return "";
}
}
}ZIP Code Lookup Sample Code
using System;
using System.Net;
using System.Xml.Linq;
namespace USPSApi_CLI {
public class USPSApiZipCode {
public static void Main() {
XDocument requestDoc = new XDocument(
new XElement("ZipCodeLookupRequest",
new XAttribute("USERID", ""),
new XElement("Revision", "1"),
new XElement("Address",
new XAttribute("ID", "0"),
new XElement("Address1", "2335 S State"),
new XElement("Address2", "Suite 300"),
new XElement("City", "Provo"),
new XElement("State", "UT"),
new XElement("Zip5", "84604"),
new XElement("Zip4", "")
),
new XElement("Address",
new XAttribute("ID", "1"),
new XElement("Address1", "1427 S 2340 E"),
new XElement("Address2", ""),
new XElement("City", "Spanish Fork"),
new XElement("State", "UT"),
new XElement("Zip5", "84660"),
new XElement("Zip4", "")
)
)
);
try {
var url = "http://production.shippingapis.com/ShippingAPI.dll?API=ZipCodeLookup&XML=" + requestDoc;
Console.WriteLine(url);
var client = new WebClient();
var response = client.DownloadString(url);
var xdoc = XDocument.Parse(response.ToString());
Console.WriteLine(xdoc.ToString());
foreach (XElement element in xdoc.Descendants("Address")) {
Console.WriteLine("-------------------------------");
Console.WriteLine("Address ID: " + GetXMLAttribute(element, "ID"));
Console.WriteLine("Address1: " + GetXMLElement(element, "Address1"));
Console.WriteLine("Address2: " + GetXMLElement(element, "Address2"));
Console.WriteLine("City: " + GetXMLElement(element, "City"));
Console.WriteLine("State: " + GetXMLElement(element, "State"));
Console.WriteLine("Zip5: " + GetXMLElement(element, "Zip5"));
Console.WriteLine("Zip4: " + GetXMLElement(element, "Zip4"));
Console.WriteLine("Urbanization: " + GetXMLElement(element, "Urbanization"));
}
}
catch (WebException e) {
Console.WriteLine(e.ToString());
}
}
public static string GetXMLElement(XElement element, string name) {
var el = element.Element(name);
if (el != null) {
return el.Value;
}
return "";
}
public static string GetXMLAttribute(XElement element, string name) {
var el = element.Attribute(name);
if (el != null) {
return el.Value;
}
return "";
}
}
}City/State Lookup Sample Code
using System;
using System.Net;
using System.Xml.Linq;
namespace USPSApi_CLI {
public class USPSApiCityStateLookup {
public static void Main() {
XDocument requestDoc = new XDocument(
new XElement("CityStateLookupRequest",
new XAttribute("USERID", ""),
new XElement("Revision", "1"),
new XElement("ZipCode",
new XAttribute("ID", "0"),
new XElement("Zip5", "84414")
),
new XElement("ZipCode",
new XAttribute("ID", "1"),
new XElement("Zip5", "84660")
)
)
);
try {
var url = "http://production.shippingapis.com/ShippingAPI.dll?API=CityStateLookup&XML=" + requestDoc;
Console.WriteLine(url);
var client = new WebClient();
var response = client.DownloadString(url);
var xdoc = XDocument.Parse(response.ToString());
Console.WriteLine(xdoc.ToString());
foreach (XElement element in xdoc.Descendants("ZipCode")) {
Console.WriteLine("-------------------------------");
Console.WriteLine("ZipCode ID: " + GetXMLAttribute(element, "ID"));
Console.WriteLine("City: " + GetXMLElement(element, "City"));
Console.WriteLine("State: " + GetXMLElement(element, "State"));
Console.WriteLine("Zip5: " + GetXMLElement(element, "Zip5"));
}
}
catch (WebException e) {
Console.WriteLine(e.ToString());
}
}
public static string GetXMLElement(XElement element, string name) {
var el = element.Element(name);
if (el != null) {
return el.Value;
}
return "";
}
public static string GetXMLAttribute(XElement element, string name) {
var el = element.Attribute(name);
if (el != null) {
return el.Value;
}
return "";
}
}
}Alternative Address Validation APIs
We know what you're thinking. Why would Smarty assist me in using an API that isn't theirs?
The answer is simple - we care. We want you to get your job done, and if you really want to use the USPS API, then hopefully this article will help you.
However, we think that once you see how much easier the Smarty .NET SDK is to use, you will want to use it instead of the USPS APIs. And, if you do, you'll get excellent customer service in the process. And of course we won't even mention that Smarty APIs are blazingly fast!
Take a moment and compare the sample code above with the Smarty .NET SDK sample code.
When you compare the USPS API experience with the experience of using the various Smarty APIs, you'll see that Smarty wins, every time. From the easy-to-use JSON response, to the stellar support, and the faster response times, and the fact that you can make up to 100 requests per API call to Smarty APIs, Smarty wins everytime.
Try Smarty for yourself with a free demo account. You'll be glad that you did.