USPS Web Service

[Mike London]

Has anybody successfully written a WS client that access the USPS Web Service?

The service is cool in principle, but there isn't much documentation.

http://www.usps.com/webtools/address.htm

Look forward to any replies.

Thanks.

-- Mike

[Ulf Dittmer]

A couple of years ago I implemented both the automatic generation of shipment files (that interfaces with the Worldship program, though, not the WS), and the automatic retrieval of delivery statuses via the WS. I did get started by the Java examples that are online, but the service may have changed since (although I doubt it). Do you have any particular questions?

[Mike London]

Hey,

Thanks for writing back.

Yes, I have a couple questions.

I'm trying to get started with the address verification API.

The USPS requires that you verify you can connect to their site before they will switch you to the "production" server.

I'm not sure, from the doucumentation how to actually do this initial connection. I do have an account, but it's not clear to me if "verification" means I just need to pack up some URL line with parameters and send it to them with my ID embedded or if I need to write some code.

Then, I couldn't find any Java examples of how to package up a SOAP request, ship it off and how to unpack it when it returns.

I bet it's pretty simple; I'm just having trouble getting started.

Any help or suggestions would be greatly appreciated. <s>

Thanks again.

-- Mike

[Ulf Dittmer]

D'oh! I read your initial post a bit too quickly - what I was accessing was UPS, not USPS, about which I have no clue. Sorry about that.

[Jesus Angeles]

Hi Mike,

I looked at http://www.usps.com/webtools/_pdf/Address-Information.pdf.

It looks like the client will send an xml as an html parameter. It doesnt use soap.

For that reason, maybe you can test right now, by pasting the below at your browser url input, and press enter:

http://SERVERNAME/ShippingAPITest.dll?API=Verify&XML=<AddressValidateRequest%20USERID="xxxxxxx"%20PASSWORD="xxxxxxx"><Address ID="0"><Address1></Address1>
<Address2>6406 Ivy Lane</Address2><City>Greenbelt</City><State>MD</State>
<Zip5></Zip5><Zip4></Zip4></Address></AddressValidateRequest>

I got this from the documentation I mentioned above.

Replace the SERVERNAME, xxxxxxx and xxxxxxx for the approriate value(server, user, password). And input the address details that you want.

In addition, the entire xml string must be url-encoded. This is quite expected, as it is an html url parameter. For this one, I am not familiar with url encoding; I see spaces in the sample above so you might need to manually url-encode it now before sending it.

Other than that, I think you can test it now.

That pdf seems to give enough details, but is implemented in microsoft technology. So instead of the microsoft dom codes, you might use java. As I have mentioned, it looks like it is pure xml, no soap.

The user and password are exposed, so I think you will have some additional stuff in production, like https.

[Jesus Angeles]

When you start coding in java, you will need a java implementation of dom, to build the xml. (like those you use in coding in book Beginning Java WEb Services. The book also has sample codes on parsing using dom, which you can imitate in processing the xml reply)

And then send the html request, along with the html parameters required, like the API parameter (e.g. API=Verify), and the XML(the xml you built)

I am not familiar how to send the html request via java code; maybe via java http connection classes. Also, that class might have methods to encode the url for you.
[ January 08, 2006: Message edited by: Jesus Angeles ]

[Jesus Angeles]

If I were you, I try run in using microsoft first, as they have given runnable sample codes. You just cut and paste from that pdf.

After that, you can convert to java codes.

[Mike London]

Thanks.

I got the Java Web Services book at your suggestion, but was disappointed that the very first example I downloaded from their site didn't work. I tried with two different versions of xerces.

I supposed I'd really use JDOM in practice anyway. <s>

Thanks for your other suggestions.

-- Mike

[Jesus Angeles]

Yes, I saw your posts.

I did the chapter 2 handsons last week. And I wouldnt have been able to run the first one without your posts. The null trick did it. But all the other codes in the chapter went flawlessly.

This chapter 2 has codes that both build xml via dom, and parse an xml using dom(to process it).

[Mike London]

Cool, thanks.

Based on your success, I'll press on with the book <s>

Are there any cool (& useful) Web Services you use that there's Java code for? I haven't looked that far into the book yet so there may be code there.

Thanks again!!!

-- Mike

[Peter DeGregorio]

Mike London wrote:Has anybody successfully written a WS client that access the USPS Web Service?

The service is cool in principle, but there isn't much documentation.

http://www.usps.com/webtools/address.htm

Look forward to any replies.

Thanks.

-- Mike

This is an old post I'm replying to but info is kind of sparse even now for Java and USPS web tools. Today I got the zip code lookup API working in Java. I used Groovy for the XML part. Here is the Groovy part for putting an address into the required XML form
The user ID is obtained at the USPS web site https://www.usps.com/business/webtools.htm ... Once you register you get access to their test server.

   public static String zipLookupToXml (UspsZipLookupAddress address) {
      def writer = new StringWriter()
      def xml = new groovy.xml.MarkupBuilder(writer)
      xml.useDoubleQuotes=true
      xml.ZipCodeLookupRequest(USERID:"XXXXXXXX"){
        Address(ID:address.id) {
           Address1(address.address1)
           Address2(address.address2)
           City(address.city)
           State(address.state)
//  Getting error "Invalid XML Element content is invalid according to the DTD/Schema." when zip5 and/or zip4 passed in
//           Zip5(address.zip5)
//           Zip4(address.zip4)
        }
      }
      return writer.toString()
   }

Here is the Groovy code for parsing the XML back into fields

   public static UspsZipLookupAddress zipLookupFromXmlToAddress(String xml) {
      def ZipCodeLookupResponse = new XmlParser().parseText(xml)
      println ZipCodeLookupResponse
      println ZipCodeLookupResponse.Address.size()
      def index = 0
      ZipCodeLookupResponse.Address.each{
         UspsZipLookupAddress address = new UspsZipLookupAddress()
         address.id=it.'@ID'
         address.address1=it.Address1.text()
         address.address2=it.Address2.text()
         address.city=it.City.text()
         address.state=it.State.text()
         address.zip5=it.Zip5.text()
         address.zip4=it.Zip4.text()
         return address
       }

      return null
   }