USPTO Patent Examination Data System API client¶
About¶
The USPTO Patent Examination Data System (PEDS) contains bibliographic, published document and patent term extension data in Public PAIR from 1981 to present. There is also some data dating back to 1935.
The PEDS system provides additional information concerning the transaction activity that has occurred for each patent. The transaction history includes the transaction date, transaction code and transaction description for each transaction activity.
Please also refer to the API documentation of this service at USPTO.
Introduction¶
This software library implements a client to access the PEDS API through the one-stop
UsptoPatentExaminationDataSystemClient
class and also provides a respective command line program uspto-peds
.
Both can be used for searching and for downloading packages of bundled artefacts.
Synopsis¶
Search interface¶
Simple usage:
from uspto.peds.client import UsptoPatentExaminationDataSystemClient
client = UsptoPatentExaminationDataSystemClient()
expression = 'firstNamedApplicant:(nasa)'
result = client.search(expression)
Advanced usage:
expression = 'firstNamedApplicant:(*grohe*)'
filter = 'appFilingDate:[2000-01-01T00:00:00Z TO 2015-12-31T23:59:59Z]'
result = client.search(expression, filter=filter, sort='applId asc', start=0, rows=20)
The query syntax follows the standard Apache Solr search syntax, the JSON documents returned also follow the Solr response formats.
Please note the maximum number of records available per request is limited to 20,
so you have to use the argument options start
and rows
to iterate
through result pages.
Download interface¶
The download interface uses the search interface and adds automation for requesting and downloading package bundles for search results as outlined in the »API Tutorial« section of the API documentation. It has two different modes, synchronous and asynchronous.
Synchronous mode¶
Simple usage:
from uspto.peds.client import UsptoPatentExaminationDataSystemClient
client = UsptoPatentExaminationDataSystemClient()
# Download document by document number
# Automatically guesses the document type (application, publication, patent) from the document number schema
# Will acquire both XML and JSON formats
result = client.download_document('PP28532')
Advanced usage:
# Explicitly request a document by application number, acquire XML format only
result = client.download_document(type='application', number='15431686', format='xml')
# Download published application by early publication number, acquire JSON format only
result = client.download_document(type='publication', number='US20170293197A1', format='json')
# Download granted patent by patent number, acquire both XML and JSON formats
result = client.download_document(type='patent', number='PP28532', format=['xml', 'json'])
Asynchronous mode¶
The software can also operate asynchronously by using Celery as a task queue for scheduling downloads in the background. Please refer to the taskqueue documentation.
To make the background task scheduler operate it in a simple manner, just start Redis and Celery like that:
redis-server
celery worker --app uspto.tasks --loglevel=info
See also: taskqueue documentation.
Simple usage:
from uspto.peds.tasks import UsptoPatentExaminationDataSystemDownloader
downloader = UsptoPatentExaminationDataSystemDownloader()
# Start downloading single document
# Automatically guesses the document type
# Will acquire both XML and JSON formats
downloader.run('PP28532')
# Start downloading multiple documents, with document type autoguessing and dual format acquisition
downloader.run(['PP28532', 'US20170293197A1'])
# Wait until results arrived
result = downloader.poll()
Advanced usage:
# Start downloading single document, explicitly requesting a patent document in XML format
downloader.run({'type': 'patent', 'number': 'PP28532', 'format': 'xml'})
# Start downloading multiple documents, each with both XML and JSON formats
downloader.run([{'type': 'publication', 'number': 'US20170293197A1'}, {'type': 'patent', 'number': 'PP28532'}])
# Save multiple documents to designated directory using the application identifier as filename
# The first document should be loaded in XML format, the second one in both XML and JSON formats
job = downloader.run(
[
{'type': 'publication', 'number': 'US20170293197A1', 'format': 'xml'},
{'type': 'patent', 'number': 'PP28532', 'format': ['xml', 'json']},
],
options = {
'save': True,
'directory': './tmp',
'overwrite': False,
'use-application-id': True,
}
)
# Is the job ready?
job.ready()
False
# Iterate the results after finishing
results = list(map(lambda task: task.result, job.results))
Utilities¶
The UsptoPatentExaminationDataSystemDocument
class can be used to inquire information about the downloaded document:
from uspto.peds.client import UsptoPatentExaminationDataSystemClient
from uspto.peds.document import UsptoPatentExaminationDataSystemDocument
client = UsptoPatentExaminationDataSystemClient()
# Download document
result = client.download_document('PP28532')
# Get document identifiers
document = UsptoPatentExaminationDataSystemDocument(result)
document.get_identifiers()
{'patent': u'PP28532', 'application': u'14999644'}
Another example:
UsptoPatentExaminationDataSystemDocument(client.download_document('US20170293197A1')).get_identifiers()
{'application': u'15431686', 'publication': u'US20170293197A1'}
Command line¶
$ uspto-peds --help
Usage:
uspto-peds get <document-number> --format=xml [--type=publication] [--pretty] [--background] [--wait] [--debug]
uspto-peds save <document-number> --format=xml [--type=publication] [--pretty] [--directory=/var/spool/uspto] [--use-application-id] [--overwrite] [--background] [--wait] [--debug]
uspto-peds bulk get --numberfile=numbers.txt --format=xml,json [--pretty] [--use-application-id] [--wait] [--debug]
uspto-peds bulk save --numberfile=numbers.txt --format=xml,json [--pretty] --directory=/var/spool/uspto [--use-application-id] [--overwrite] [--wait] [--debug]
uspto-peds search [<expression>] [--filter=filter] [--start=0] [--rows=20] [--download] [--format=xml,json] [--directory=/var/spool/uspto] [--debug]
uspto-peds info
uspto-peds --version
uspto-peds (-h | --help)
Document acquisition options:
<document-number> Document number, e.g. 2017/0293197, US20170293197A1, PP28532, 15431686.
Format depends on data source.
--type=<type> Document type, one of "publication", "application", "patent" or "auto".
When using "auto", the program tries to to guess the document number type
(application, publication, patent) from the document number itself.
--format=<target> Data format, one of "xml" or "json".
In bulk mode, it can also be "--type=xml,json".
Search options:
<expression> Search expression for generic querying.
Examples:
- firstNamedApplicant:(nasa)
- patentTitle:(network AND security) AND appStatus_txt:(patented)
- appCls:(701) AND appStatus_txt:(patented)
--filter=<filter> Filter expression.
Example:
- appFilingDate:[2000-01-01T00:00:00Z TO 2005-12-31T23:59:59Z]
--start=<start> Start record. Default: 0
--rows=<rows> Number of records returned. Default: 20 (which is also the limit).
Output options:
--pretty Pretty-print output data. This currently applies to "--format=json" only.
Save options:
--directory=<directory> Save downloaded documents to designated target directory.
--use-application-id Use the application identifier as filename.
--overwrite Overwrite already existing documents.
Background mode:
--background Run the download process in the background.
--wait Wait for the background download job to finish.
Bulk options:
--numberfile=<numberfile> Read document numbers from file. Implicitly uses "--background" mode.
Guess document number type by implicitly using "--type=auto".
Download multiple formats by specifying "--format=xml,json".
Miscellaneous options:
--debug Enable debug messages
--version Show version information
-h --help Show this screen
Operation modes:
"uspto-peds get" Download one document and print the result to STDOUT.
"uspto-peds save" Download one document and save it to the target directory,
defaulting to the current working directory.
"uspto-peds bulk get" Submit task for downloading multiple documents to the background job machinery.
After finishing, print the results to STDOUT when using the "--wait" option.
"uspto-peds bulk save" Submit task for downloading multiple documents to the background job machinery.
While doing so, progressively save documents to the target directory.
After finishing, print the full file names to STDOUT when using the "--wait" option.
Examples:
# Display published application by publication number in XML format
uspto-peds get "US20170293197A1" --type=publication --format=xml
# ... same in JSON format, with pretty-printing
uspto-peds get "US20170293197A1" --type=publication --format=json --pretty
# Display published application by application number
uspto-peds get "15431686" --type=application --format=xml
# Display granted patent by patent number
uspto-peds get "PP28532" --type=patent --format=xml
# Display granted patent by automatically guessing document type
uspto-peds get "PP28532" --format=xml
# Download granted patent by patent number and save to /var/spool/uspto/PP28532.peds.xml
uspto-peds save "PP28532" --type=patent --format=xml --directory=/var/spool/uspto
Bulk example:
# Download all documents from numbers.txt and save them /var/spool/uspto/$number.peds.(xml|json)
uspto-peds bulk save --numberfile=numbers.txt --format=xml,json --pretty --directory=/var/spool/uspto --wait
Search examples:
# Search for documents matching "applicant=nasa" and display polished JSON response
uspto-peds search 'firstNamedApplicant:(nasa)'
# Search for documents matching "applicant=grohe" filed between 2010 and 2017
uspto-peds search 'firstNamedApplicant:(*grohe*)' --filter='appFilingDate:[2010-01-01T00:00:00Z TO 2017-12-31T23:59:59Z]'
# Search for documents matching "applicant=nasa" and download zip archives containing bundles in XML and JSON formats
uspto-peds search 'firstNamedApplicant:(nasa)' --download --format=xml,json --directory=/tmp