Skip to content

V1.4.0 ("Experiment IV")

Latest
Latest
Compare
Choose a tag to compare
@codingatty codingatty released this 04 Feb 22:58
· 4 commits to master since this release
V1.4.0
a3236c7

Summary of new features

  • USPTO API key support
  • Pauses between TSDR calls to comply with PTO policy
  • TSDR calls now default to requests for ST.96-format XML files
  • New unbound method GetMetainfo()
  • New reporting: trademark classes and first-use dates

Details

USPTO API key support

The USPTO recently instituted a requirement that calls to TSDR must specify an API key. There is no charge for the API key, but you must register with the USPTO to obtain one. Calls without specifying an API key will fail as 401 Not Authorized. To set the API key, use the SetAPIKey(key) prior to any call (such as getTSDRInfo or getXMLData) that calls TSDR.

For example:

TSDRReq t = new TSDRReq();
t.SetAPIKey("32characterAPIKeyYouGotFromTheUSPTO");
t.getTSDRInfo("75181334", "s");

Pauses between TSDR calls to comply with PTO policy

By default, there is now a one-second delay between TSDR calls. I was going to add this delay in any event, to prevent an inadvertent denial-of-service attack on the TSDR servers. However, it's become even more essential now that the PTO has implemented the API key approach. As part of the new API key requirement, the PTO limits TSDR calls to 60 calls per minute for XML fetches; more than 60 calls per minute results in an error. By inserting a one-second pause between each call, Plumage ensures keeping within the PTO-enforced limit.

The length of the delay can be modified by calling SetIntervalTime(), and can be eliminated entirely by using SetIntervalTime(0). Be aware that if the delay is shortened or eliminated, calls in excess of USPTO policy will be rejected by the server.

This approach to complying with the PTO's constraints may change in the next release. See the Additional comments section, below.

TSDR calls now default to requests for ST.96-format XML files.

By default, TSDR queries are now for XML files; specifically, ST.96-format. Prior to 1.4.0, the default was for a zip file. Zip files contain some additional data, most notably image files that correspond to the published trademark specimen. However, the PTO restriction for zip files is significantly tighter than its restriction for XML text files: it only allows 4 zip files per minute, compared to 60 XML files per minute. In order to allow for more calls, XML is now the default.

If you require image data, you can still request zip format by calling the setPTOFormat method. If making successive calls, you should change from the default one-second pause between TSDR calls to a fifteen-second pause to avoid having excessive calls rejected:

TSDRReq t = new TSDRReq();
t.SetAPIKey("32characterAPIKeyYouGotFromTheUSPTO");
t.SetIntervalTime(15);
t.setPTOFormat("zip");
t.getTSDRInfo("75181334", "s");

New unbound method GetMetainfo()

The new method method GetMetainfo() is available to obtain metainfo about the library and environment without instantiating a TSDRReq object and without invoking a TSDR call.

Example:

metainfo = TSDRReq.GetMetainfo();
Console.WriteLine(metainfo["MetaInfoLibraryVersion"]);

will print:

1.4.0

New reporting: trademark classes and first-use dates

This release incorporates XSL transforms from Plumage-XSL V1.4.0. Plumage-XSL V1.4.0 reports additional information about trademark classes (both international and domestic) as well as first-use dates. See the Plumage-XSL V1.4.0 release notes for details.

For example, the following code fetches application no. 76/044,902 (the trademark "Python" for the Python programming language) and prints the class number and goods & services information for the first-listed international class; and the first-use date for the first of the documented use dates (in the PTO-supplied formats, YYYYMMDD):

TSDRReq t = new TSDRReq();
t.setAPIKey("api-key");
t.getTSDRInfo("76044902", "s") ;
Console.WriteLine("Registration no.: " + t.TSDRData.TSDRSingle["RegistrationNumber"]);
Console.WriteLine("Mark text: " + t.TSDRData.TSDRSingle["MarkVerbalElementText"]);

var international_class_list = t.TSDRData.TSDRMulti["InternationalClassDescriptionList"];
var first_ic = international_class_list[0];
Console.WriteLine("Class: " + first_ic["InternationalClassNumber"]);
Console.WriteLine("G&S: " + first_ic["GoodsServicesDescription"]);

var use_date_list = t.TSDRData.TSDRMulti["FirstUseDateList"];
var first_ud = use_date_list[0];
Console.WriteLine("Class: " + first_ud["NiceClassNumber"]);
Console.WriteLine("First use: " + first_ud["FirstUseDateNumber"]);
Console.WriteLine("First use in commerce: " + first_ud["FirstUseInCommerceDate"]);

prints:

Registration no.:  2824281
Mark text:  PYTHON
Class:  009
G&S: Computer programs and downloadable computer programs that implement an object-oriented computer programming language
Class:  009
First use: 19951013
First use in commerce: 19951013

Additional comments

Future of complying with PTO timing constraints

As mentioned above, the USPTO imposes a constraint of 60 queries per minute for XML retrieval. This is addressed by pausing to ensure that at least one second elapses between each query, thereby keeping queries to at most 60 in one minute.

Plumage tries to limit the delays. The first call is not delayed at all. On subsequent calls, the delay is shortened or eliminated if possible. For example. if the calling program makes a TDSR call, then spends a half-second processing the data from the call before making a second TSDR call, the subsequent call will be delayed only a half-second. If more than a second is spent between calls, no additional pause is added at all.

However, this does impede the throughput of small bursts. For example, if you need to make only 15 queries, it is fully compliant with the PTO constraints to make those 15 queries immediately, and it would likely take only about 5 seconds. 15 queries in 5 seconds complies with the PTO's "no more than 60 queries in one minute" constraint. However, the current approach will take 14 seconds: 15 calls, with up to a one-second delay between each call (the initial call is not delayed at all).

I'm considering other approaches that would allow better throughput for short bursts of fewer than 60 queries. In the interest of getting the API key support (and the concomitant timing compliance) out in a timely manner, I went with the current approach; but I may revisit it in the future release, hopefully in a not-too-incompatible way.

Development environment

This release was developed and tested using:

Assets 3
Loading