Receive this blog in your e-mail.

* = required field

powered by MailChimp!

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 Carolina Genealogical Society, the Virginia Genealogical Society, and the North Carolina Chapter of the APG. I also chair the Technology Committee of the NGS.

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

A key tech­nol­ogy that I’m using is Joomla. This is an open source web con­tent man­age­ment sys­tem designed to pro­vide a dynamic web­site, chang­ing as con­tent and meta­data 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 Server and the data in the MySQL data­base. While you can have page ele­ments cached if they are fre­quently used, in gen­eral 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 Joomla for geneal­ogy soci­ety web­sites. Among oth­ers, there is the Dallas Genealogical Society, the New England Chapter of the APG, and the Nebraska State Genealogical Society.

The most recent of the sites that I have put together is for the Virginia Genealogical Society. 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 available.

In mid December, I had updated the method of ship­ping cal­cu­la­tion on both the NCGS site and the VGS site to use the US Postal Service Application Programmer’s Interface (API). This allows both sites to pro­vide pric­ing based on what the USPS would actu­ally charge to ship, say a book, from one par­tic­u­lar loca­tion to another. 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 Joomla site can add han­dling expenses to, and dis­play to the buyer.

The share­ware mod­ule to inte­gra­tion the USPS API with Joomla (from Parkbeach Systems) 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 server.

This after­noon, a geneal­o­gist who was try­ing to pur­chase one of the books from the North Carolina Genealogical Society’s web­site noted that they were unable to make a pur­chase. I went over to the site and saw the same symp­toms. I hadn’t changed any­thing since our last order for a ship­ping item (on December 31), but I duti­fully spent hours search­ing the con­fig­u­ra­tions for some anom­aly, some tog­gle I had for­got­ten to switch.

Eventually, I needed some din­ner and came home to have it. After that break, I came back and started 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 decided to update their ship­ping rate API with­out telling any­one. #FAIL http://url.fldweb.com/fyLQ8z

Genealogy sites, gar­den­ing sites, mommy-and-me sites, all kinds of web­sites rely on this API, and the USPS decided it was high time that they made sure peo­ple knew that phrases such as “Priority 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 accounted 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 Unicode char­ac­ter instead of as HTML com­mands for the char­ac­ter (&reg; or &#x00AE; or &#174;) everyone’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 demanded that users choose one …

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

So, this is how I spent my evening, fret­ting over a prob­lem that didn’t need to be there in the first place. Folks: Document 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­pany that pro­vides the API I’m using with Joomla, and they had already posted an updated ver­sion. Both sites are work­ing fine in terms of ship­ping and the USPS ship­ping API.

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

 
OPENGEN - Genealogy Standards Alliance OPENGEN.ORG - Genealogy Standards Alliance