pyuspto

library0.5.2pypypi✓ verified 82d ago

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.

http-networking data serialization

pip install pyuspto

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PYUSPTO

pyuspto

http-networkingpythonv0.5.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BulkDataClient

✓ from pyUSPTO import BulkDataClient

✗ from pyuspto import USPTOConfig

EnrichedCitationsClient

✓ from pyUSPTO import EnrichedCitationsClient

OAActionsClient

✓ from pyUSPTO import OAActionsClient

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)

Debug

Known issues

breakingIn 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.

affects: >=0.4.0

breakingIn 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`.

affects: >=0.4.5

deprecatedThe `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.

affects: >=0.4.0

gotchaThe 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.

affects: all

gotchaPagination: 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.

affects: >=0.4.0

breakingIn 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.

affects: >=0.4.0

Upgrade

Version history

0.5.2latest on PyPI · released Apr 16, 2026

Audit

Dependencies

requestsrequiredHTTP client used for all API calls

pydanticrequiredData validation and settings management

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/DunlapCoddingPC/pyUSPTO ↗

packagehttps://pypi.org/project/pyuspto/ ↗

docshttps://pyuspto.readthedocs.io/en/latest/ ↗