VGS, NCGS, and the USPS API

Alphabet Soup for a Monday

I am the web­mas­ter for three genealog­i­cal soci­eties, the North Car­oli­na Genealog­i­cal Soci­ety, the Vir­ginia Genealog­i­cal Soci­ety, and the North Car­oli­na Chap­ter of the APG. I also chair the Tech­nol­o­gy Com­mit­tee of the NGS.

In each of these realms, I find myself empow­ered by open source tech­nol­o­gy, using the LAMP (Lin­ux, Apache, MySQL and PHP) tech­nol­o­gy stack. This is a pow­er­ful suite of free tools that have been devel­oped by vol­un­teers, or in oth­er ways made avail­able for free use. Much of the tech­nol­o­gy involved in these sites is — as is com­mon­ly said, “Free as in ‘Free beer’ and free as in ‘Free speech.’ ”

A key tech­nol­o­gy that I’m using is Joom­la. This is an open source web con­tent man­age­ment sys­tem designed to pro­vide a dynam­ic web­site, chang­ing as con­tent and meta­da­ta is changed in the data­base. It relies on hav­ing LAMP under­neath it, and builds web pages from the files on the Apache Serv­er and the data in the MySQL data­base. While you can have page ele­ments cached if they are fre­quent­ly used, in gen­er­al the pages are deliv­ered by query­ing the data­base when some­one comes to a page, then tak­ing the data and some HTML and styling tem­plates, and assem­bling an HTML page “on the fly.”

I am not the only per­son who uses Joom­la for geneal­o­gy soci­ety web­sites. Among oth­ers, there is the Dal­las Genealog­i­cal Soci­ety, the New Eng­land Chap­ter of the APG, and the Nebras­ka State Genealog­i­cal Soci­ety.

The most recent of the sites that I have put togeth­er is for the Vir­ginia Genealog­i­cal Soci­ety. I launched the VGS beta web­site this morn­ing. There is still a lot more to do with that site, but the look and feel and the core func­tions are avail­able.

In mid Decem­ber, I had updat­ed the method of ship­ping cal­cu­la­tion on both the NCGS site and the VGS site to use the US Postal Ser­vice Appli­ca­tion Pro­gram­mer’s Inter­face (API). This allows both sites to pro­vide pric­ing based on what the USPS would actu­al­ly charge to ship, say a book, from one par­tic­u­lar loca­tion to anoth­er. The API takes into con­sid­er­a­tion the weight of the item, whether it is a let­ter or a pack­age, the source and des­ti­na­tion zip codes, etc., then returns a price that the Joom­la site can add han­dling expens­es to, and dis­play to the buy­er.

The share­ware mod­ule to inte­gra­tion the USPS API with Joom­la (from Park­beach Sys­tems) was prob­a­bly the eas­i­est of mod­ules to set up, though it did require a brief call to the USPS to request the accounts be put on the pro­duc­tion serv­er.

This after­noon, a geneal­o­gist who was try­ing to pur­chase one of the books from the North Car­oli­na Genealog­i­cal Soci­ety’s web­site not­ed that they were unable to make a pur­chase. I went over to the site and saw the same symp­toms. I had­n’t changed any­thing since our last order for a ship­ping item (on Decem­ber 31), but I duti­ful­ly spent hours search­ing the con­fig­u­ra­tions for some anom­aly, some tog­gle I had for­got­ten to switch.

Even­tu­al­ly, I need­ed some din­ner and came home to have it. After that break, I came back and start­ed Googling again for USPS API and told Google to sort results based on how recent they were. Up popped a tweet about what was hap­pen­ing, from @floodlight:

USPS decid­ed to update their ship­ping rate API with­out telling any­one. #FAIL http://url.fldweb.com/fyLQ8z

Geneal­o­gy sites, gar­den­ing sites, mom­my-and-me sites, all kinds of web­sites rely on this API, and the USPS decid­ed it was high time that they made sure peo­ple knew that phras­es such as “Pri­or­i­ty Mail” were reg­is­tered trade­marks, so they put the code:

<sup>®</sup>

after every one of their reg­is­tered trade­marks. Since none of the devel­op­ers of inte­gra­tions with the API had account­ed for this, or even knew it was about to hap­pen, and since the USPS API sent the reg­is­tered trade­mark sym­bol as a Uni­code char­ac­ter instead of as HTML com­mands for the char­ac­ter (® or ® or ®) every­one’s USPS inte­gra­tions filled up with junk and failed, some­times in cre­ative ways. Our site sim­ply stopped offer­ing a ship­ping option, though it demand­ed that users choose one …

By the way, the USPS web­site still does not men­tion this issue, though a quick search of the Twit­ter stream will show you it’s still on peo­ple’s minds: http://twitter.com/#!/search/USPS%20API

So, this is how I spent my evening, fret­ting over a prob­lem that did­n’t need to be there in the first place. Folks: Doc­u­ment your APIs, com­mu­ni­cate your pro­posed changes in advance, please.

The good news in all this is that once I real­ized that the API was to blame, and not some mis­con­fig­u­ra­tion of my own doing, I went to the com­pa­ny that pro­vides the API I’m using with Joom­la, and they had already post­ed an updat­ed ver­sion. Both sites are work­ing fine in terms of ship­ping and the USPS ship­ping API.

So now, I can rest. Tomor­row I’m start­ing an Aiki­do class with my step­son, but per­haps I will get more of an oppor­tu­ni­ty to work on geneal­o­gy in the evening tomor­row, even with that going on, than I did today. We shall see.