V1.1.0 ("Baby, If")

Summary of new features

• USPTO API key support via --key and/or --config options
• New option syntax
• Update to Plumage-dotnet 1.4.0, reporting additional fields
• New --config option
• New --output option to write to file
• New documentary options --version and --help

Details

USPTO API key support

The USPTO recently instituted a requirement that calls to TSDR must specify an API key. This is what motivated this release; with the new API requirement, TSDR2JSON no longer worked.

You can now specify an API key using the option --key="32CharacterAPIKeyYouGotFromUSPTO" (with or without the quotes).

The --key is not required by TSDR2JSON, but under the PTO's current configuration, calls that don't specify an API key will fail as 401 Not Authorized. In the (admittedly unlikely) event the PTO drops the API key requirement, TSDR2JSON will work again without it, so the program does not make it mandatory.

There is no charge for the API key, but you must register with the USPTO to obtain one.

For convenience, instead of typing an awkward 32-character string on the command line, you can put your API key in a configuration file and use that instead; see "New --config option", below.

New option syntax

Previously, for example, to fetch trademark registration no. 1,234,567, you specified TSDR2JSON r 1234567; to get application serial no. 78/123.456 you'd use TSDR2JSON s 78123456. That was simple enough as long as there were no operands other than identifying the type and number of the instrument you were fetching; but adding the ability to specify an API key, and to do so either directly or via a configuration file, really would have made this messy without a new approach.

Beginning with this release 1.1.0, TSDR2JSON uses industry standard POSIX-style option specification. In simplest terms, where you used to use:

TSDR2JSON r 1234567

you now need to use:

TSDR2JSON -r 1234567

Or, if you prefer a longer form:

TSDR2JSON --registration 1234567

That's it.

Windows command-line users who are accustomed to using a '/' instead of a '-' can do so. Also, for options that take operands, you can separate the operand from the option by either ' ' (a space, as in the examples above) or an '=' (equal sign).

Using a ":" or omitting it entirely should also work, but are less clear. In other words, the following ways (and others) of specifying a registration number are equivalent:

-r 78123456                  -r=78123456                  -r:78123456                  -r78123456
--registration 78123456     --registration=78123456      --registration:78123456      --registration78123456 
/r 78123456                  /r=78123456                  /r:78123456                  /r78123456

The way of requesting an TSDR entry by application serial number has similarly changed. For example, to look up ser. no. 78/123,456, where you used to use:

TSDR2JSON s 78123456

you now need to use:

TSDR2JSON -s 78123456

Or, using the longer form:

TSDR2JSON --serial 78123456

Update to Plumage-dotnet 1.4.0, reporting additional fields

TSDR now uses Plumage-dotnet 1.4.0 for its underlying TSDR access. 1.4.0 is the first release to support API keys.

In addition to API key support, Plumage-dotnet 1.4.0 incorporates Plumage-xsl 1.4.0, which.reports additional information from TSDR, including the PTO staff identification; international and domestic classification for the mark; and first-use dates. This additional information is now included in the TSDR2JSON output. For more information, For details, see the Plumage-dotnet 1.4.0 release notes and the Plumage-xsl 1.4.0 release notes.

New --config option

As an alternative to using the --key option, you can place the API key in a JSON dictionary configuration file. The only requirement at the moment is that the file include a key/value pair, where the key is named TSDRAPIKey and the value is the 32-character API key provided by the USPTO. Here is a minimum config file:

{ "TSDRAPIKey": "32CharacterAPIKeyYouGotFromUSPTO" }

At present, any key other than TSDRAPIKey is ignored. A sample config file sample-config.json is provided for you to edit.

To tell TSDR2JSON to use a configuration file, use the -c or --config option. For example, to use a configuration file name myconfigfile.json in the same directory in which TSDR2JSON is executing, you would specify:

--config=myconfigfile.json

You can omit the filename:

--config

in which case, TSDR2JSON will look for a file named tsdr2json-config.json.

There is no requirement that the filename use the .json extension.

If providing a filename, you cannot use a space between --config and the filename; the cleanest way is to use the '=' equals sign.

If you specify both --config and --key, the key specified by the --key option will be used; the TSDRAPIKey field will be ignored.

New --output option to write to file

By default, TSDR2JSON displays its output on the console. To route it to a file, you can now use the -o or --outfile option:

--outfile="trademark-info.txt"

There is no requirement that the filename be in quotes, unless the filename itself contains spaces (e.g., the quotes around the filename in --outfile="trademark info.txt" are required because of the blank space in the filename).

If the --outfile option is used and no filename is specified, the default filename is tsdr2json-out.json.

If providing a filename, you cannot use a space between --outfile and the filename; the cleanest way is to use the '=' equals sign.

New documentary options --version and --help

There are two additional traditional options:

• -v or --version will print the name and version of TSDR2JSON and the underlying Plumage library:

  > tsdr2json --version
  TSDR2JSON version 1.1.0.0 (Plumage library: Plumage-dotnet 1.4.0)

• -h or --help will print a few lines of help information.

Examples

TSDR2JSON --key="ABCDEFGHIJKLMNOPancdefghijklmnop" -r 1234567

will fetch information for reg. no 1,234,567 and dump the JSON information to the console.

TSDR2JSON --key="ABCDEFGHIJKLMNOPancdefghijklmnop" -s 73327697

will do the same (registration 1,234,567 and application serial no. 73/327,697 are the same document).

TSDR2JSON -c --outfile=r1234567-report.txt -r 1234567

Using the API key obtained from the tsdr2json-config.json file, fetch information for registration no. 1,234,567, and write it out to the file named "r1234567-report.txt"

Development environment

This release was developed and tested using:

• Microsoft Visual Studio 2019 V 16.8.4
• Microsoft .NET Framework 4.6.1
• Newtonsoft Json.NET 12.0.2
• Microsoft Mono.Options 6.6.0.161

V1.0.0 ("All I Want, All I Need")

Initial release.