Getting Started

Installation

To install

pip install patent_client

If you are only interested in using the USPTO API’s, no further setup is necessary. Skip ahead to the next section.

If you want to take advantage of the European Patent Office’s Open Patent Services, which supports Inpadoc and Epo Register documents, you will need to set up your API key.

Step 1: Go to EPO Open Patent Services and register a new account (Free up to 4GB of data / month, which is more than sufficient).

Step 2: Log in to EPO OPS, and click on “My Apps,” add a new app, and write down the corresponding API Consumer Key and Consumer Key Secret.

Step 3: Import patent_client from anywhere. E.g.

$ python
Python 3.6.5 (default, Jul 12 2018, 11:37:09)
>>> import patent_client

This will set up an empty settings file, located at ~/.iprc. The IPRC file is a JSON object containing settings for the project.

Step 4: Edit the IPRC file to contain your user key and secret. E.g.

{
    "EpoOpenPatentServices": {
        "ApiKey": "<Consumer Key Here>",
        "Secret": "<Consumer Key Secret Here>"
    }
}

Step 5: PROFIT! Every time you import a model that requires EPO OPS access, you will automatically be logged on using that key and secret.

Basic Use

All data is accessible through an Active Record model inspired by the Django ORM Query API. In particular, the API to Patent Client is a subset of the official Djanog QuerySet API. To access data, first import the model representing the data you want. E.g.

from patent_client import USApplication

All the API’s used in this library are Read Only, so there is no way to add, delete, or modify records. Data is queried by applying filters, orders, and by slicing the related “objects” attribute. For example, if you wanted all patent applications filed by “Google LLC,” you would write

google_apps = USApplication.objects.filter(first_named_applicant='Google LLC')

This returns a manager that can access all US Applications where the first named applicant is “Google LLC.” You can also apply ordering to the records, such as:

google_apps = google_apps.order_by('appl_filing_date')

which sorts the applications by filing date. Notice that calls to “.filter,” and “.order_by” can be chained, and each chained function returns a unique manager. All the filter and order by parameters accumulate, such that:

microsoft_pats = (USApplication.objects
                .filter(first_named_applicant='Microsoft')
                .filter(app_status='Patented Case')
                .order_by('patent_issue_date')
                )

returns a manager that returns all applications with Microsoft listed as the first applicant, that have issued as patents, and in order of their patent issue date (ascending order).

Once you have a manager, the data contained by the manager can be accessed in a few ways. Record objects can be obtained by slicing or iterating on the manager itself.

app = microsoft_pats[0]
app
'<USApplication(appl_id=13656185)>'
app.patent_title
'DOWNHOLE APPARATUS FOR ELECTRICAL POWER GENERATION FROM SHAFT FLEXURE'
app.app_status
'Patented Case'
app.patent_number
'9093875'
apps = microsoft_pats[:3]
apps
'[<USApplication(appl_id=13656185)>, <USApplication(appl_id=13660608)>, <USApplication(appl_id=13672932)>]'

The data can also be accessed in other ways. Just like the Django QuerySet API, Patent Client supports the values and values_list methods.

microsoft_pats.values('appl_id', 'patent_title')[:3]
[
    OrderedDict([('appl_id', '13656185'), ('patent_title', 'DOWNHOLE APPARATUS FOR ELECTRICAL POWER GENERATION FROM SHAFT FLEXURE')]),
    OrderedDict([('appl_id', '13660608'), ('patent_title', 'Hybrid Bearings for Downhole Motors')]),
    OrderedDict([('appl_id', '13672932'), ('patent_title', 'DOUBLE SHAFT DRILLING APPARATUS WITH HANGER BEARINGS')])
]
microsoft_pats.values_list('patent_title', flat=True)[:3]
[
    'DOWNHOLE APPARATUS FOR ELECTRICAL POWER GENERATION FROM SHAFT FLEXURE',
    'Hybrid Bearings for Downhole Motors',
    'DOUBLE SHAFT DRILLING APPARATUS WITH HANGER BEARINGS'
]

This is particularly useful in combination with the Pandas library, as a .values() manager can be used to create dataframes quickly and easily.

import pandas as pd
from patent_client import USApplication

pd.DataFrame.from_records(
    (USApplication.objects
        .filter(first_named_applicant='Microsoft')
        .values('appl_id', 'patent_number', 'patent_title')[:3]
    )
)
    appl_id patent_number                                       patent_title
0  13656185       9093875  DOWNHOLE APPARATUS FOR ELECTRICAL POWER GENERA...
1  13660608       9045941                Hybrid Bearings for Downhole Motors
2  13672932       9309720  DOUBLE SHAFT DRILLING APPARATUS WITH HANGER BE...