{"id":28115,"library":"pyuspto","title":"pyUSPTO","description":"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.","status":"active","version":"0.5.2","language":"python","source_language":"en","source_url":"https://github.com/DunlapCoddingPC/pyUSPTO","tags":["USPTO","patents","API","IP","legal"],"install":[{"cmd":"pip install pyuspto","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"HTTP client used for all API calls","package":"requests","optional":false},{"reason":"Data validation and settings management","package":"pydantic","optional":false}],"imports":[{"note":"","wrong":"","symbol":"USPTOConfig","correct":"from pyuspto import USPTOConfig"},{"note":"","wrong":"","symbol":"PatentClient","correct":"from pyuspto import PatentClient"},{"note":"","wrong":"","symbol":"BulkDataClient","correct":"from pyuspto import BulkDataClient"},{"note":"","wrong":"","symbol":"IFWClient","correct":"from pyuspto import IFWClient"},{"note":"","wrong":"","symbol":"OfficeActionClient","correct":"from pyuspto import OfficeActionClient"},{"note":"","wrong":"","symbol":"EnrichedCitationsClient","correct":"from pyuspto import EnrichedCitationsClient"}],"quickstart":{"code":"from pyuspto import USPTOConfig, PatentClient\n\nconfig = USPTOConfig(api_key='your_api_key_here')\nclient = PatentClient(config)\nresults = client.search(query='tennis ball')\nfor patent in results:\n    print(patent.patent_title)","lang":"python","description":"Initialize a USPTOConfig with your API key, instantiate a PatentClient, and run a simple search query."},"warnings":[{"fix":"Pass a single USPTOConfig instance to all clients.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Use the new explicit request methods (`client.get(...)`, etc.) instead of `_make_request`.","message":"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.","severity":"breaking","affected_versions":">=0.4.5"},{"fix":"If you need archive extraction, add `extract=True` to your `download_file` call.","message":"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.","severity":"deprecated","affected_versions":">=0.4.0"},{"fix":"Register for a free API key at https://developer.uspto.gov/api-catalog.","message":"The USPTO API key is required. Without it, most endpoints will return 403. The library does not mock or generate a key.","severity":"gotcha","affected_versions":"all"},{"fix":"Use the generator pattern for PatentClient search. For BulkDataClient, use the appropriate `paginate_*` methods without post_body.","message":"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).","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Use the client's methods to generate URLs dynamically; do not hardcode download URLs.","message":"In v0.4.0, the bulk download URL changed to include a year subfolder. Old hardcoded URLs will fail.","severity":"breaking","affected_versions":">=0.4.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use 'from pyuspto import USPTOConfig' and then create a client like 'PatentClient(config)'.","cause":"There is no 'USPTOClient' class. The correct base configuration is 'USPTOConfig' and specific clients like 'PatentClient'.","error":"AttributeError: module 'pyuspto' has no attribute 'USPTOClient'"},{"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)'.","cause":"The 'api_key' parameter is passed directly to a client instead of being passed to USPTOConfig.","error":"TypeError: __init__() got an unexpected keyword argument 'api_key'"},{"fix":"Obtain an API key from https://developer.uspto.gov/api-catalog and set it in USPTOConfig.","cause":"Missing or invalid API key. The USPTO API requires a valid key.","error":"requests.exceptions.HTTPError: 403 Client Error: Forbidden"},{"fix":"Use 'for patent in client.search(...):' or 'results = list(client.search(...))'.","cause":"The search method returns a generator, not a list. Iterate over it or convert to list with list() before accessing items by index.","error":"AttributeError: 'Generator' object has no attribute '...'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}