My project

September 2020 0

TSDR API Key Manager

user guide

2020

USPTO | 600 Dulany Street, Alexandria VA, 22313

September 2020 1

Contents

About....................................................................................................................................... 2

Requesting a key ....................................................................................................................... 2

Using your API key.................................................................................................................. 3

Using Postman ................................................................................................................... 3

Using curl .......................................................................................................................... 3

Appendix .............................................................................................................................. 4

Rate limit rules ................................................................................................................... 4

Sample URL search queries .................................................................................................. 5

September 2020 2

About

We are implementing a new process for obtaining bulk data. You will now use a key to download bulk

data in the Trademark Status and Document Retrieval (TSDR) system by using application programing

interfaces (APIs). Rate limiting is enforced for each key.

An API key is a (approximately) 40 character string value that:

• Uniquely identifies you

• Gives you access to TSDR APIs

• Should be kept private and should not be shared

You will need to register to obtain a key from our enterprise API gateway server using your

USPTO.gov

accountat http://my.uspto.gov/. The API gateway server will serve as a single point of entry into our

other bulk APIs. After registering, you will append your key to your computerized HTTP download

request to access data.

This document provides step-by-step instructions for the following:

• Request an API key.

• Using the key to download bulk data from TSDR.

Requesting a key

You can request a key by completing the following steps:

1. Sign in to the API Key Manager at https://account.uspto.gov/api-manager/.

a. You will be first prompted to sign in to your USPTO.gov account.

b. If you don’t have a USPTO.gov account, you will need to create one. You can use the

above link to do so.

c. This works best with Chrome.

2. Select TSDR (Trademark Search and Data Retrieval) API to download bulk Trademark Data

from the list and press the Request API key button.

a. This page will automatically appear, once you sign in to your USPTO.gov account.

3. Your API key is automatically generated and saved.

September 2020 3

a. Do not share your key.

Using your API key

Below are instructions and examples of how to use your API key.

Using Postman

Postman is an API development collaboration tool you can use to make your bulk data requests. You can

download the tool from the Postman website

. There is a free version for testing purposes. Once you

have downloaded and installed it, use the following instructions to download a document:

1. Select GET HTTP method in the dropdown column and enter the URL of the document you want

to download. For these instructions, we’re using

https://tsdrapi.uspto.gov/ts/cd/casestatus/sn78787878/download.pdf

.

a. You can get sample URL search queries in our appendix.

2. Select Headers.

3. Enter in the key section “USPTO-API-KEY”.

a. You must enter “USPTO-API-KEY” exactly.

4. Enter the API key value that you received from the API Key Manager.

5. If you use a valid API key value, you will automatically receive a HTTP status code 200 along with

the requested data. If you send too many requests in a given time period, you will receive a

HTTP status code 429 instead indicating that you are exceeding the rate limits.

6. Since this request is a PDF document, it will not render by default in the body section. Click on

Save Response and select the Save to File option to download the file.

Using curl

Curl is a command line interface used to test API. You can use the curl command on Linux, UNIX, and

Mac OS. You can also use Cygwin in Windows.

1. Open a command terminal.

2. On a command line, you want to use the following commands:

September 2020 4

Curl

command

Description

Example

-i

This is for

interactive; it

includes the

response

headers in the

response.

curl -i

-o

This is for the

path of the file

where the

response is

saved.

-o 78787878.pdf

-H

This submits

the request for

header

information

provided as

key: value.

-H “USPTO-API-KEY: abcabcabcabcabcabcabcabc”

Note: You will use the key you received. The sequence used

here is for example only.

-X GET

This is the

HTTP method

followed by

the TSDR URL.

It instructs

“read from

database.”

-X GET

https://tsdrapi.upsto.gov/ts/cd/casestatus/sn78787878/download.pdf

Typed out, the command should look like this:

curl -i

-o 78787878.pdf

-X GET https://tsdrapi.upsto.gov/ts/cd/casestatus/sn78787878/download.pdf

-H “USPTO-API-KEY: abcabcabcabcabcabcabcabc”

Appendix

Rate limit rules

Below are some standard rate limits that are subject to change depending on system availability and

usage:

• All requests are rate limited at 60 requests per API Key per minute.

• PDF and ZIP downloads are rate limited at 4 requests per API Key per minute.

• Multi case PDF and ZIP downloads are rate limited at 4 requests per API Key per minute.

The following are off peak rate limits that will be in effect from 10 p.m. EST to 5 a.m. EST all seven days

of week:

September 2020 5

• All requests are rate limited at 120 requests per API Key per minute.

• PDF and ZIP downloads are rate limited at 12 requests per API Key per minute.

• Multi case PDF and ZIP downloads are rate limited at 12 requests per API Key per minute.

Sample URL search queries

A few sample URLs can be found below. We’ve selected some random case numbers to illustrate the

URLs.

• Status for serial number 78787878 as a pdf

https://tsdrapi.uspto.gov/ts/cd/casestatus/sn78787878/download.pdf

• Status for serial number 75757575 as a zip that includes XML and CSS files

https://tsdrapi.uspto.gov/ts/cd/casestatus/sn75757575/content.zip

• Status for serial number 78787878 as a html

https://tsdrapi.uspto.gov/ts/cd/casestatus/sn78787878/content

• Status for serial number 78787878 as XML

https://tsdrapi.uspto.gov/ts/cd/casestatus/sn78787878/info.xml

• All documents for serial number 72131351 as a PDF

https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.pdf?sn=72131351

• A full sized image of a trademark for a serial number 78787878

https://tsdrapi.uspto.gov/ts/cd/rawImage/78787878

• All documents for reference number Z1231384 as a PDF

https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.pdf?ref=Z1231384

• All documents for registration number 3,500,030 as a PDF

https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.pdf?rn=3500030

• Documents sent/received on Nov. 30, 2003, for serial number 72-131351 as a PDF

https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.pdf?sn=72131351&date=2003-11-30

• All specimens for serial numbers 72131351 and 76515878 as a single PDF

https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.pdf?sn=72131351,76515878&type=SPE

• Metadata (in XML) about all documents for serial number 75008897 sent/received during 2006

https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.xml?sn=75008897&fromDate=2006-01-

01&toDate=2006-12-31

September 2020 6

• Metadata (in XML) about all documents for

international registration number 0835690 sorted

from earliest to latest

https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.xml?ir=0835690&sort=date:A

• The registration certificate for registration number 3,500,038 as a PDF

https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.pdf?rn=3500038&category=RC

• The registration certificates for registration numbers 3,500,038 and 3,500,039 as a ZIP of their

original TIFF images

https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.zip?rn=3500038,3500039&category=RC

TM-LUS

---------------------------------------------

• Ret

rieves the last update time when a prosecution history was updated on a case (XML Response)

https://tsdrapi.uspto.gov/last-update/info.xml?sn=78787878

curl -X GET 'ht

tps://tsdrapi.uspto.gov/last-update/info.xml?sn=78787878' -H 'accept:

application/xml'

Response:

----------------------

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

< CaseUpdateInfo xmlns="urn:us:gov:doc:uspto:trademark">

< CaseData>

< CaseStatusData/>

< CaseProsecutionData>

< LastModifiedDate>2020-10-14</LastModifiedDate>

< /CaseProsecutionData>

< CaseDocumentsData/>

< /CaseData>

</CaseUpdateInfo>

Successful retrieval of last update time:

----------------------

Successful retrieval of last update time:

----------------------

<?xml version="1.0" encoding="UTF-8"?>

<lastModifiedDate>string</lastModifiedDate>

<lastModifiedDate>string</lastModifiedDate>

</caseStatusData>

<lastModifiedDate>string</lastModifiedDate>

</caseProsecutionData>

<lastModifiedDate>string</lastModifiedDate>

</caseDocsData>

</caseData>

<name>string</name>

<value>string</value>

</caseUpdateInfo>

</CaseUpdateInfoList>

• Retrieves the last update time when a prosecution history was updated on a

case(JSON Response)

https://tsdrapi.uspto.gov/last-update/info.json?sn=78787878

curl -X GET https://tsdrapi.uspto.gov/last-update/info.json?sn=78787878 -H

'accept: application/json'

Response:

---------

{

"caseUpdateInfo": [

{

"caseData": {

"caseProsecutionData": {

"lastModifiedDate": "2020-10-14"

}

},

"serialNumber": "78787878"

}

]

}

"value": "string"

}

]

}

Successful retrieval of last update time

----------------------------------------

{

"caseUpdateInfo": [

{

"caseData": {

"lastModifiedDate": "string",

"caseStatusData": {

"lastModifiedDate": "string"

},

"caseProsecutionData": {

"lastModifiedDate": "string"

},

"caseDocsData": {

"lastModifiedDate": "string"

}

},

"name": "string",

"value": "string"

}

]

}