Basic examples

These examples illustrate basic use of Plumage to retrieve status information on a trademark application. The example calls getTSDRInfo to get TSDR information on application number 75/181,334. The boolean flag TSDRMapIsValid can be queried to ensure that the TSDR call completed successfully.

TSDRMap is a mapping of the TSDR data returned. In Plumage-py it is implemented as a dictionary. In Plumage-dotnet (C#), it is implemented as Dictionary<string, Object>. TSDRMap keys typically correspond to the attribute names in the XML data provided by TSDR (which may vary from the labels displayed on TSDR itself). Values are either strings, for non-recurring data (such as application number, registration date, etc.); or lists, for recurring (or potentially recurring) data (such as events in the application prosecution history, ownership at various stages of prosecution, or assignments of the application).

In Plumage-py non-recurring data is represented as the type string. In Plumage-dotnet, its is also string, but stored as Object (because TSDRMap values may be either strings of non-recurring data or lists of recurring data).

In Plumage-py, recurring data is represented as a Python list. Each entry in the list is a dictionary whose keys and data are each strings. In Plumage-dotnet, recurring data is represented as type ArrayList. Each entry in the ArrayList is of type Dictionary<string, Object>, whose keys and data are each strings.

Entries for recurring and non-recurring data can be distinguished by key name. All keys for recurring data end in "List" (e.g., MarkEventList, ApplicantList, AssignmentList). No keys for non-recurring data end in "List".

The example below (in Python and multiple .NET languages) illustrate the extraction and display of both non-recurring and recurring data. It displays several pieces of non-recurring data (such as the application and registration numbers and dates). For recurring data, it selects the most recent (first-listed) entries in ApplicantList and MarkEventList, and displays owner and status information for those entries, respectively.

A complete list of elements returned in TSDRMap can be found in TSDRMap contents.

#Python

from Plumage import plumage
t = plumage.TSDRReq()
t.getTSDRInfo("75181334", "s")   # get info on application ser. no 75/181,334
if t.TSDRMapIsValid:
   print "Application serial no: ", t.TSDRMap["ApplicationNumber"]
   print "Trademark text: ", t.TSDRMap["MarkVerbalElementText"]
   print "Application filing date: ", t.TSDRMap["ApplicationDate"]
   print "Registration no: ", t.TSDRMap["RegistrationNumber"]
   # Owner info is in most recent (0th) entry in ApplicantList
   applicant_list = t.TSDRMap["ApplicantList"]
   current_owner_info = applicant_list[0]
   print "Owner:", current_owner_info["ApplicantName"]
   print "Owner address: ", current_owner_info["ApplicantCombinedAddress"]
   # Get most recent event: 0th entry in event list
   event_list = t.TSDRMap["MarkEventList"]
   most_recent_event = event_list[0]
   print "Most recent event: ", most_recent_event["MarkEventDescription"]
   print "Event date: ", most_recent_event["MarkEventDate"]

#C#

Plumage.TSDRReq t = new Plumage.TSDRReq();
t.getTSDRInfo("75181334", "s");  // get info on application ser. no 75/181,334
if (t.TSDRMapIsValid){
    Console.WriteLine("Application serial no: " + t.TSDRMap["ApplicationNumber"]);
    Console.WriteLine("Trademark text: " + t.TSDRMap["MarkVerbalElementText"]);
    Console.WriteLine("Application filing date: " + t.TSDRMap["ApplicationDate"]);
    Console.WriteLine("Registration no: " + t.TSDRMap["RegistrationNumber"]);
    // Owner info is in most recent (0th) entry in ApplicantList
    ArrayList applicant_list = (ArrayList)t.TSDRMap["ApplicantList"];
    Dictionary<string, Object> current_owner_info = (Dictionary<string, Object>)applicant_list[0];
    Console.WriteLine("Owner: " + current_owner_info["ApplicantName"]);
    Console.WriteLine("Owner address: " + current_owner_info["ApplicantCombinedAddress"]);
    // Get most recent event: 0th entry in event list
    ArrayList event_list = (ArrayList)t.TSDRMap["MarkEventList"];
    Dictionary<string, Object> most_recent_event = (Dictionary<string, Object>)event_list[0];
    Console.WriteLine("Most recent event: " + most_recent_event["MarkEventDescription"]);
    Console.WriteLine("Event date: " + most_recent_event["MarkEventDate"]);
}

Although coded in C#, Plumage is a .NET library, and can be invoked from other .NET languages, e.g. Visual Basic .NET and C++ .NET. (Note, I learned just enough VB and C++ to write and test these examples; they are likely not idiomatic code.)

#Visual Basic .NET

Dim t As Plumage.TSDRReq = New Plumage.TSDRReq
t.getTSDRInfo("75181334", "s")   ' get info on application ser. no 75/181,334
If t.TSDRMapIsValid Then
    Console.WriteLine("Application serial no: " + t.TSDRMap("ApplicationNumber"))
    Console.WriteLine("Trademark text: " + t.TSDRMap("MarkVerbalElementText"))
    Console.WriteLine("Application filing date: " + t.TSDRMap("ApplicationDate"))
    Console.WriteLine("Registration no: " + t.TSDRMap("RegistrationNumber"))
    ' Owner info is in most recent (0th) entry in ApplicantList
    Dim applicant_list As ArrayList = t.TSDRMap("ApplicantList")
    Dim current_owner_info As Dictionary(Of String, Object) = applicant_list(0)
    Console.WriteLine("Owner: " + current_owner_info("ApplicantName"))
    Console.WriteLine("Owner address: " + current_owner_info("ApplicantCombinedAddress"))
    ' Get most recent event: 0th entry in event list
    Dim event_list As ArrayList = t.TSDRMap("MarkEventList")
    Dim most_recent_event As Dictionary(Of String, Object) = event_list(0)
    Console.WriteLine("Most recent event: " + most_recent_event("MarkEventDescription"))
    Console.WriteLine("Event date: " + most_recent_event("MarkEventDate"))
End If

#C++ .NET

Plumage::TSDRReq^ t =  gcnew Plumage::TSDRReq;
t->getTSDRInfo("75181334", "s");  // get info on application ser. no 75/181,334
if (t->TSDRMapIsValid){
    Console::WriteLine("Application serial no: " + t->TSDRMap["ApplicationNumber"]);
    Console::WriteLine("Trademark text: " + t->TSDRMap["MarkVerbalElementText"]);
    Console::WriteLine("Application filing date: " + t->TSDRMap["ApplicationDate"]);
    Console::WriteLine("Registration no: " + t->TSDRMap["RegistrationNumber"]);
    // Owner info is in most recent (0th) entry in ApplicantList
    ArrayList^ applicant_list = (ArrayList^)(t->TSDRMap["ApplicantList"]);
    Dictionary<String^, Object^>^ current_owner_info = (Dictionary<String^, Object^>^)applicant_list[0];
    Console::WriteLine("Owner: " + current_owner_info["ApplicantName"]);
    Console::WriteLine("Owner address: " + current_owner_info["ApplicantCombinedAddress"]);
    // Get most recent event: 0th entry in event list
    ArrayList^ event_list = (ArrayList^)(t->TSDRMap["MarkEventList"]);
    Dictionary<String^, Object^>^ most_recent_event = (Dictionary<String^, Object^>^)event_list[0];
    Console::WriteLine("Most recent event: " + most_recent_event["MarkEventDescription"]);
    Console::WriteLine("Event date: " + most_recent_event["MarkEventDate"]);
};

#Sample output In each of the above cases, the examples will print the following information (as of August 2014) on U.S. trademark application serial number 75/181,334.

Application serial no:  75181334
Trademark text:  MONTY PYTHON'S FLYING CIRCUS
Application filing date:  1996-10-15-04:00
Registration no:  2564831
Owner: Python (Monty) Pictures Ltd.
Owner address:  Room 537/538, The Linen Hall//London//W1R 5TB/GB
Most recent event:  CANCELLED SEC. 8 (6-YR)
Event date:  2009-02-07-05:00

#Querying by registration number In the examples show above, the application has matured to registration, and therefore has a ''registration number'' (2,564,831) in addition to its ''application serial number'' (75/181,334). So in this case, the same date would have been displayed if the getTSDRInfo call had requested data for registration no. 2,564,831 instead of for application serial no. 75/181,334.

Python:

t.getTSDRInfo("2564831", "r")   # get info on reg. no 2,564,831

C#:

t.getTSDRInfo("2564831", "r");  // get info on reg. no 2,564,831

Visual Basic .NET:

t.getTSDRInfo("2564831", "r")   ' get info on reg. no 2,564,831

C++ .NET:

t->getTSDRInfo("2564831", "r");  // get info on reg. no 2,564,831

Note the second parameter has changed from "s" (indicating a serial number) to "r" (indicating a registration number). #Multiple queries A single TSDRReq object may be reused to successively query TSDR, as shown in the following example (Python), which displays the text of five trademarks, fetched by application number.

t = plumage.TSDRReq()
application_numbers = ["76535603", "75854426", "86142154", "78790815", "75533975"] 
for application_number in application_numbers:
    result = t.getTSDRInfo(application_number, "s")
    print t.TSDRMap["MarkVerbalElementText"]

This displays:

NO BUDDY
ESPEX
ZA
SPANISH
INQUISITION

If making a large number of TSDR queries, please insert a short pause between queries, to avoid hammering the TSDR server. The PTO advises: "In order to maintain general availability of USPTO information and services provided on the Internet, any activity or operation by a third party that has the potential to cause a denial or diminution (decrease) of services to other customers, whether generated automatically or manually, will result in the Office denying or limiting access to the Office Internet resources to that third party."

#Additional features

For simply accessing TSDR status information, the use described above is all that is generally required. However, Plumage provides additional information and options. These include:

• access to other TSDR data, such as images;
• invoking Plumage in stages, to obtain intermediate data, i.e., the raw XML or the CSV-parsed data, and potentially modifying them before they are processed in later stages;
• obtaining data in ST.66 or ST.96 XML format, rather than the default ZIP file;
• overriding the XSLT to obtain different data or additional to accommodate potential future changes made by the USPTO; and
• obtaining data from a local file rather than from the USPTO.

See Data members and List of methods for details.