pyUSPTO

0.5.2 verified Sat May 09 auth: no python

A modern Python client for accessing the United States Patent and Trademark Office (USPTO) Open Data Portal (ODP) APIs. Current version 0.5.2, requires Python >=3.10, and follows a monthly-ish release cadence. Supports patent search, bulk data, IFW, office actions, enriched citations, and more.

pip install pyuspto

Common errors

error AttributeError: module 'pyuspto' has no attribute 'USPTOClient' ↓

cause There is no 'USPTOClient' class. The correct base configuration is 'USPTOConfig' and specific clients like 'PatentClient'.

fix

Use 'from pyuspto import USPTOConfig' and then create a client like 'PatentClient(config)'.

error TypeError: __init__() got an unexpected keyword argument 'api_key' ↓

cause The 'api_key' parameter is passed directly to a client instead of being passed to USPTOConfig.

fix

Create a USPTOConfig object with the api_key, then pass that config to the client: 'config = USPTOConfig(api_key='your_key'); client = PatentClient(config)'.

error requests.exceptions.HTTPError: 403 Client Error: Forbidden ↓

cause Missing or invalid API key. The USPTO API requires a valid key.

fix

Obtain an API key from https://developer.uspto.gov/api-catalog and set it in USPTOConfig.

error AttributeError: 'Generator' object has no attribute '...' ↓

cause The search method returns a generator, not a list. Iterate over it or convert to list with list() before accessing items by index.

fix

Use 'for patent in client.search(...):' or 'results = list(client.search(...))'.

Warnings

breaking In v0.4.0, session management was centralized in USPTOConfig. Previously, each client managed its own session. All clients now share the session from the config object. ↓

fix Pass a single USPTOConfig instance to all clients.

breaking In v0.4.5, the polymorphic `_make_request` method was split into typed request methods (`get`, `post`, etc.). Any custom code relying on `_make_request` will break. ↓

fix Use the new explicit request methods (`client.get(...)`, etc.) instead of `_make_request`.

deprecated The `download_file` method's default changed in v0.4.0 from extracting archives to no extraction. To extract, you must now pass `extract=True` explicitly. ↓

fix If you need archive extraction, add `extract=True` to your `download_file` call.

gotcha The USPTO API key is required. Without it, most endpoints will return 403. The library does not mock or generate a key. ↓

fix Register for a free API key at https://developer.uspto.gov/api-catalog.

gotcha Pagination: The `search` method on PatentClient returns a generator that automatically pages through results. However, the `paginate_products` method on BulkDataClient does not accept a `post_body` parameter (removed in v0.4.0). ↓

fix Use the generator pattern for PatentClient search. For BulkDataClient, use the appropriate `paginate_*` methods without post_body.

breaking In v0.4.0, the bulk download URL changed to include a year subfolder. Old hardcoded URLs will fail. ↓

fix Use the client's methods to generate URLs dynamically; do not hardcode download URLs.

Imports

USPTOConfig
```
from pyuspto import USPTOConfig
```
PatentClient
```
from pyuspto import PatentClient
```
BulkDataClient
```
from pyuspto import BulkDataClient
```
IFWClient
```
from pyuspto import IFWClient
```
OfficeActionClient
```
from pyuspto import OfficeActionClient
```

EnrichedCitationsClient

from pyuspto import EnrichedCitationsClient

Quickstart

Initialize a USPTOConfig with your API key, instantiate a PatentClient, and run a simple search query.

from pyuspto import USPTOConfig, PatentClient

config = USPTOConfig(api_key='your_api_key_here')
client = PatentClient(config)
results = client.search(query='tennis ball')
for patent in results:
    print(patent.patent_title)