Clients

clients.bulk_data - Client for USPTO bulk data API

This module provides a client for interacting with the USPTO Open Data Portal (ODP) Bulk Data API. It allows you to search for and download bulk data products.

class pyUSPTO.clients.bulk_data.BulkDataClient(api_key=None, base_url=None, config=None)[source]

Bases: BaseUSPTOClient[BulkDataResponse]

Client for interacting with the USPTO bulk data API.

ENDPOINTS = {'download_file': '{file_download_uri}', 'product_by_id': 'products/{product_id}', 'products_search': 'products/search'}
__init__(api_key=None, base_url=None, config=None)[source]

Initialize the BulkDataClient.

Parameters:
download_file(file_data, destination)[source]

Download a file from the API.

Parameters:

  • file_data (FileData) – FileData object containing file information

  • destination (str) – Directory where the file should be saved

Return type:

str

Returns:

Path to the downloaded file

get_product_by_id(product_id, file_data_from_date=None, file_data_to_date=None, offset=None, limit=None, include_files=None, latest=None)[source]

Get a specific bulk data product by ID.

Parameters:

  • product_id (str) – The product identifier

  • file_data_from_date (str | None) – Filter files by data from date (YYYY-MM-DD)

  • file_data_to_date (str | None) – Filter files by data to date (YYYY-MM-DD)

  • offset (int | None) – Number of product file records to skip

  • limit (int | None) – Number of product file records to collect

  • include_files (bool | None) – Whether to include product files in the response

  • latest (bool | None) – Whether to return only the latest product file

Return type:

BulkDataProduct

Returns:

BulkDataProduct object containing the product data

get_products(params=None)[source]

Get a list of bulk data products.

This method is deprecated. Use search_products instead.

Parameters:

params (Dict[str, Any] | None) – Optional query parameters

Return type:

BulkDataResponse

Returns:

BulkDataResponse object containing the API response

paginate_products(**kwargs)[source]

Paginate through all products matching the search criteria.

Parameters:

**kwargs (Any) – Keyword arguments to pass to search_products

Yields:

BulkDataProduct objects

Return type:

Iterator[BulkDataProduct]

search_products(query=None, product_title=None, product_description=None, product_short_name=None, from_date=None, to_date=None, categories=None, labels=None, datasets=None, file_types=None, offset=None, limit=None, include_files=None, latest=None, facets=None)[source]

Search for products with various filters.

Parameters:

  • query (str | None) – Search text

  • product_title (str | None) – Filter by product title

  • product_description (str | None) – Filter by product description

  • product_short_name (str | None) – Filter by product identifier (short name)

  • from_date (str | None) – Filter products with data from this date (YYYY-MM-DD)

  • to_date (str | None) – Filter products with data until this date (YYYY-MM-DD)

  • categories (List[str] | None) – Filter by dataset categories

  • labels (List[str] | None) – Filter by product labels

  • datasets (List[str] | None) – Filter by datasets

  • file_types (List[str] | None) – Filter by file types

  • offset (int | None) – Number of product records to skip

  • limit (int | None) – Number of product records to collect

  • include_files (bool | None) – Whether to include product files in the response

  • latest (bool | None) – Whether to return only the latest product file for each product

  • facets (bool | None) – Whether to enable facets in the response

Return type:

BulkDataResponse

Returns:

BulkDataResponse object containing matching products

clients.patent_data - Client for USPTO patent data API

This module provides a client for interacting with the USPTO Patent Data API. It allows you to search for and retrieve patent application data.

class pyUSPTO.clients.patent_data.PatentDataClient(api_key=None, base_url=None, config=None)[source]

Bases: BaseUSPTOClient[PatentDataResponse]

Client for interacting with the USPTO Patent Data API.

ENDPOINTS = {'download_application_document': 'api/v1/download/applications/{application_number}/{document_id}', 'get_application_adjustment': 'api/v1/patent/applications/{application_number}/adjustment', 'get_application_assignment': 'api/v1/patent/applications/{application_number}/assignment', 'get_application_associated_documents': 'api/v1/patent/applications/{application_number}/associated-documents', 'get_application_attorney': 'api/v1/patent/applications/{application_number}/attorney', 'get_application_by_number': 'api/v1/patent/applications/{application_number}', 'get_application_continuity': 'api/v1/patent/applications/{application_number}/continuity', 'get_application_documents': 'api/v1/patent/applications/{application_number}/documents', 'get_application_foreign_priority': 'api/v1/patent/applications/{application_number}/foreign-priority', 'get_application_metadata': 'api/v1/patent/applications/{application_number}/meta-data', 'get_application_transactions': 'api/v1/patent/applications/{application_number}/transactions', 'get_search_results': 'api/v1/patent/applications/search/download', 'search_applications': 'api/v1/patent/applications/search', 'status_codes': 'api/v1/patent/status-codes'}
download_archive(printed_metadata, file_name=None, destination_path=None, overwrite=False)[source]

Downloads Printed Metadata (XML data). These are XML files of the patent as printed.

Note

See also download_publication() for a clearer method name with identical functionality.

Parameters:

  • printed_metadata (PrintedMetaData) – ArchiveMetaData object containing download URL and metadata

  • file_name (str | None) – Optional filename. If not provided, uses xml_file_name from metadata

  • destination_path (str | None) – Optional directory path to save the file

  • overwrite (bool) – Whether to overwrite existing files. Default False

Returns:

Path to the downloaded file

Return type:

str

Raises:
download_document(document_format, file_name=None, destination_path=None, overwrite=False, stream=True)[source]

Downloads a document in the specified format.

Parameters:

  • document_format (DocumentFormat) – DocumentFormat object containing download URL and metadata

  • file_name (str | None) – Optional filename. If not provided, extracted from URL

  • destination_path (str | None) – Optional path - can be a directory OR a complete file path

  • overwrite (bool) – Whether to overwrite existing files. Default False

  • stream (bool) – Whether to stream the download. Default True for large files

Returns:

Path to the downloaded file

Return type:

str

Raises:
download_publication(printed_metadata, file_name=None, destination_path=None, overwrite=False)[source]

Download a publication XML file (grant or pre-grant publication).

This method downloads publication XML files from PrintedMetaData objects, such as grant documents or pre-grant publications (pgpub). The filename is automatically extracted from the metadata if not provided.

Parameters:

  • printed_metadata (PrintedMetaData) – PrintedMetaData object containing the publication download URL and filename information. Typically obtained from get_application_associated_documents() or from PatentFileWrapper’s grant_document_meta_data or pg_publication_document_meta_data.

  • file_name (str | None) – Optional custom filename. If not provided, uses the xml_file_name from the metadata (e.g., “18915708_12307527.xml”).

  • destination_path (str | None) – Optional directory path where the file should be saved. If not provided, saves to the current directory. The directory will be created if it doesn’t exist.

  • overwrite (bool) – Whether to overwrite an existing file at the destination. Default is False, which raises FileExistsError if file exists.

Returns:

Absolute path to the downloaded publication file.

Return type:

str

Raises:

  • ValueError – If printed_metadata has no file_location_uri (download URL).

  • FileExistsError – If the file already exists and overwrite=False.

Examples

Download grant XML to a specific directory (auto-filename):

>>> response = client.get_application_by_number("18/915,708")
>>> ifw = response
>>> grant_metadata = ifw.grant_document_meta_data
>>> path = client.download_publication(grant_metadata, destination_path="./downloads")
>>> print(path)
'./downloads/18915708_12307527.xml'

Download pgpub XML with custom filename:

>>> pgpub_metadata = ifw.pg_publication_document_meta_data
>>> path = client.download_publication(
...     pgpub_metadata,
...     file_name="my_publication.xml",
...     destination_path="./downloads"
... )
>>> print(path)
'./downloads/my_publication.xml'

Download to current directory:

>>> path = client.download_publication(grant_metadata)
>>> print(path)
'./18915708_12307527.xml'
get_IFW_metadata(application_number=None, publication_number=None, patent_number=None, PCT_app_number=None, PCT_pub_number=None)[source]

Retrieves complete patent file wrapper data using common identifiers.

This utility fetches the PatentFileWrapper, which contains comprehensive IFW metadata, application details, and more. Provide only one identifier if possible. If multiple are given, they are processed in the order listed in the arguments, and the first successful match is returned.

Parameters:

  • application_number (Optional[str], optional) – USPTO application number (e.g., “16123456”). Checked first (direct lookup).

  • patent_number (Optional[str], optional) – USPTO patent number (e.g., “11000000”). Checked second (uses search).

  • publication_number (Optional[str], optional) – USPTO pre-grant publication number (e.g., “20230123456”). Checked third (uses search).

  • PCT_app_number (Optional[str], optional) – PCT application number. Checked fourth (direct lookup, treated as USPTO app#).

  • PCT_pub_number (Optional[str], optional) – PCT publication number (e.g., “2023012345”). Checked fifth (uses search).

Returns:

A PatentFileWrapper object with

comprehensive data if found using one of the identifiers, otherwise None.

Return type:

Optional[PatentFileWrapper]

get_application_adjustment(application_number)[source]

Retrieves patent term adjustment (PTA) data for a specific application.

This method fetches the PatentTermAdjustmentData component from the full patent file wrapper. This data includes details on various delay quantities (e.g., A, B, C delays, applicant delays), the total calculated adjustment, and a history of PTA events that influenced the term.

Parameters:

application_number (str) – The USPTO application number for which PTA data is being requested (e.g., “16123456”).

Returns:

A PatentTermAdjustmentData

object containing the PTA details if the application is found and has such data. Returns None if the application cannot be found or if PTA data is not available in the response.

Return type:

Optional[PatentTermAdjustmentData]

get_application_assignment(application_number)[source]

Retrieves a list of patent assignments for a specific application.

This method fetches the assignment_bag from the patent file wrapper, which contains a list of Assignment objects. Each Assignment object details an assignment including information such as reel and frame numbers, recording dates, conveyance text, and details about the assignors and assignees.

Parameters:

application_number (str) – The USPTO application number for which assignment data is being requested (e.g., “16123456”).

Returns:

A list of Assignment objects, each

representing a recorded assignment for the application. Returns None if the application cannot be found, or if no assignment data is available in the response. An empty list may be returned if the application is found but has no recorded assignments.

Return type:

Optional[List[Assignment]]

get_application_associated_documents(application_number)[source]

Retrieves metadata for Pre-Grant Publication and Grant documents.

This method fetches metadata specifically for published documents associated with the patent application, such as Pre-Grant Publications (PGPUBs) and granted patent documents. It does not retrieve the prosecution history documents (see get_application_documents for that). The result is a PrintedPublication object, which holds PrintedMetaData including file URIs and names. Download with download_archive.

Parameters:

application_number (str) – The USPTO application number for which associated PGPUB/Grant document metadata is being requested (e.g., “16123456”).

Returns:

A PrintedPublication object

containing PrintedMetaData for the Pre-Grant Publication and/or the Grant document, if available. Returns None if the application cannot be found or if no such associated document metadata is available. The fields within the returned object (pgpub_document_meta_data, grant_document_meta_data) may themselves be None if a particular type of document (e.g., PGPUB) does not exist for the application.

Return type:

Optional[PrintedPublication]

get_application_attorney(application_number)[source]

Retrieves data for the attorney(s) of record for a specific application.

This method fetches the RecordAttorney object associated with the patent application. This object contains details about the attorney(s) of record, including customer number correspondence data, power of attorney information, and a list of listed attorneys.

Parameters:

application_number (str) – The USPTO application number for which attorney data is being requested (e.g., “16123456”).

Returns:

A RecordAttorney object with details

about the attorney(s) of record if the application is found and such data exists. Returns None if the application cannot be found or if no attorney data is available in the response.

Return type:

Optional[RecordAttorney]

get_application_by_number(application_number)[source]

Retrieves the full details for a specific patent application by its number.

This method fetches comprehensive information for a single patent application identified by its unique application number.

Parameters:

application_number (str) – The USPTO application number for the patent application (e.g., “16123456” or “18/915,708”). The application number will be automatically sanitized to remove commas and spaces.

Returns:

A PatentFileWrapper object representing

the complete file wrapper for the application if found. This object contains all data sections related to the application, such as metadata, addresses, assignments, attorney/agent data, continuity data, PTA/PTE data, transactions, and associated documents. Returns None if the application cannot be found or if the response does not contain the expected data.

Return type:

Optional[PatentFileWrapper]

get_application_continuity(application_number)[source]

Retrieves continuity data (parent/child applications) for a specific application.

This method fetches the lineage of the specified application, returning an ApplicationContinuityData object. This object consolidates lists of ParentContinuity (applications to which the current one claims priority) and ChildContinuity (applications claiming priority to the current one) objects, each detailing the related application’s key identifiers and status.

Parameters:

application_number (str) – The USPTO application number for which continuity data is being requested (e.g., “16123456”).

Returns:

An ApplicationContinuityData

object containing lists of parent and child continuity relationships. Returns None if the application cannot be found or if the underlying data to construct continuity is not available. The lists within the returned object may be empty if no parent or child continuity links exist.

Return type:

Optional[ApplicationContinuityData]

get_application_documents(application_number, document_codes=None, official_date_from=None, official_date_to=None)[source]

Retrieves metadata for documents associated with a specific application.

This method fetches a collection of document metadata related to the given patent application. The result is a DocumentBag object, which is an iterable collection of Document instances. Each Document object contains metadata such as its identifier, official date, document code and description, direction (incoming/outgoing), and available download formats.

Parameters:

  • application_number (str) – The USPTO application number for which document metadata is being requested (e.g., “16123456”).

  • document_codes (Optional[List[str]]) – Filter by specific document type codes. If provided, only documents with these codes will be returned. Examples: [‘ABST’, ‘CLM’, ‘SPEC’, ‘DRWD’].

  • official_date_from (Optional[str]) – Filter documents from this date (inclusive). Date format: YYYY-MM-DD (e.g., “2020-01-15”).

  • official_date_to (Optional[str]) – Filter documents to this date (inclusive). Date format: YYYY-MM-DD (e.g., “2023-12-31”).

Returns:

A DocumentBag object containing metadata for all

publicly available documents associated with the application that match the provided filters. The bag will be empty if no documents are found or if the API response indicates no documents. It does not return None for “not found” cases; an empty collection is returned instead.

Return type:

DocumentBag

get_application_foreign_priority(application_number)[source]

Retrieves a list of foreign priority claims for a specific application.

This method fetches the foreign_priority_bag from the patent file wrapper. This bag contains a list of ForeignPriority objects, each representing a claim to a foreign patent application’s priority date. Details include the IP office name, filing date, and application number of the foreign priority application.

Parameters:

application_number (str) – The USPTO application number for which foreign priority data is being requested (e.g., “16123456”).

Returns:

A list of ForeignPriority objects,

each detailing a claimed foreign priority. Returns None if the application cannot be found or if no foreign priority data is available. An empty list may be returned if the application is found but has no foreign priority claims.

Return type:

Optional[List[ForeignPriority]]

get_application_metadata(application_number)[source]

Retrieves key metadata for a specific patent application.

This method fetches the ApplicationMetaData component from the full patent file wrapper. The metadata includes a wide range of information such as application status, important dates (filing, grant, publication), applicant and inventor details, classification data, and other core identifying information for the application.

Parameters:

application_number (str) – The USPTO application number for which metadata is being requested (e.g., “16123456” or “18/915,708”). The application number will be automatically sanitized.

Returns:

An ApplicationMetaData object

containing the core details of the patent application if found. Returns None if the application cannot be found or if metadata is not available in the response.

Return type:

Optional[ApplicationMetaData]

get_application_transactions(application_number)[source]

Retrieves the transaction history (events) for a specific application.

This method fetches the event_data_bag from the patent file wrapper. This bag contains a list of EventData objects, each representing a single recorded event in the prosecution history of the patent application. Events include details like an event code, a textual description, and the date the event was recorded.

Parameters:

application_number (str) – The USPTO application number for which transaction history is being requested (e.g., “16123456”).

Returns:

A list of EventData objects, each

detailing a transaction or event in the application’s history. Returns None if the application cannot be found or if no transaction data is available. An empty list may be returned if the application is found but has no recorded transaction events.

Return type:

Optional[List[EventData]]

get_search_results(query=None, sort=None, offset=0, limit=25, fields_param=None, filters_param=None, range_filters_param=None, post_body=None, application_number_q=None, patent_number_q=None, inventor_name_q=None, applicant_name_q=None, assignee_name_q=None, filing_date_from_q=None, filing_date_to_q=None, grant_date_from_q=None, grant_date_to_q=None, classification_q=None, additional_query_params=None)[source]

Fetches a dataset of patent applications based on search criteria, always requesting JSON format. For GET, parameters align with OpenAPI for /api/v1/patent/applications/search/download. For POST, post_body should conform to PatentDownloadRequest schema.

Return type:

list[ApplicationMetaData]

get_status_codes(params=None)[source]

Retrieves USPTO patent application status codes and their descriptions.

This method fetches a list of defined USPTO patent application status codes (e.g., codes for “Pending,” “Abandoned,” “Issued”) using a GET request. The request can be customized with query parameters to filter or paginate the results if supported by the API endpoint.

Parameters:

params (Optional[Dict[str, Any]], optional) – A dictionary of query parameters to be sent with the GET request. These parameters can be used to filter or control the output of the status codes list. Defaults to None, which typically retrieves all available status codes or the API’s default set.

Returns:

An object containing a count of matching

status codes, a StatusCodeCollection of the StatusCode objects (code and description), and a request identifier.

Return type:

StatusCodeSearchResponse

paginate_applications(**kwargs)[source]

Provides an iterator to easily paginate through patent application search results.

This method simplifies the process of fetching all patent applications that match a given search query by automatically handling pagination. It internally calls the search_applications method for GET requests, batching results and yielding them one by one.

All keyword arguments provided to this method (**kwargs) are passed directly to the search_applications method to define the search criteria. See the search_applications method for more details on available parameters. The offset and limit parameters are managed by the pagination logic; setting them directly in kwargs might lead to unexpected behavior.

Parameters:

**kwargs (Any) – Keyword arguments to be passed to the search_applications method for constructing the search query. These define the criteria for the patent applications to be retrieved. Do not include post_body.

Returns:

An iterator that yields PatentFileWrapper

objects, allowing iteration over all matching patent applications across multiple pages of results.

Return type:

Iterator[PatentFileWrapper]

Raises:

ValueError – If post_body is included in kwargs, as this method only supports GET request parameters for pagination.

sanitize_application_number(input_number)[source]

Sanitize and validate a USPTO application number.

Application numbers are either: - 8 digits (e.g., “16123456”) - Series code format: 2 digits + “/” + 6 digits (e.g., “08/123456”) - PCT format: “PCT/US2024/012345” → “PCTUS2412345”

This method removes common separators (commas, spaces) while preserving the “/” in series code format.

Parameters:

input_number (str) – Raw application number input. May include commas, spaces, or other formatting.

Returns:

Sanitized application number (either “NNNNNNNN” or “NN/NNNNNN”).

Return type:

str

Raises:

ValueError – If the format is invalid.

Examples

>>> client.sanitize_application_number("16123456")
"16123456"
>>> client.sanitize_application_number("16,123,456")
"16123456"
>>> client.sanitize_application_number("08/123456")
"08/123456"
>>> client.sanitize_application_number("08/123,456")
"08/123456"
search_applications(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, application_number_q=None, patent_number_q=None, inventor_name_q=None, applicant_name_q=None, assignee_name_q=None, filing_date_from_q=None, filing_date_to_q=None, grant_date_from_q=None, grant_date_to_q=None, classification_q=None, earliestPublicationNumber_q=None, pctPublicationNumber_q=None, additional_query_params=None)[source]

Searches for patent applications. Can perform a GET request based on OpenAPI query parameters or a POST request if post_body is specified.

Return type:

PatentDataResponse

search_status_codes(search_request)[source]

Searches USPTO patent application status codes using POST criteria.

Performs targeted searches for USPTO patent application status codes (e.g., for “Pending,” “Abandoned,” “Issued”) by sending a POST request with a JSON body containing the search_request criteria. This method is suited for more complex queries than the GET-based get_status_codes.

Parameters:

search_request (Dict[str, Any]) – A dictionary with search criteria, sent as the JSON POST body. The structure must conform to USPTO API requirements for this endpoint (e.g., for searching by code or description keywords).

Returns:

An object containing a count of matching

status codes, a StatusCodeCollection of the StatusCode objects (code and description), and a request identifier.

Return type:

StatusCodeSearchResponse

clients.petition_decisions - Client for USPTO Final Petition Decisions API

This module provides a client for interacting with the USPTO Final Petition Decisions API. It allows you to search for and retrieve final agency petition decisions in publicly available patent applications and patents filed in 2001 or later.

class pyUSPTO.clients.petition_decisions.FinalPetitionDecisionsClient(api_key=None, base_url=None, config=None)[source]

Bases: BaseUSPTOClient[PetitionDecisionResponse]

Client for interacting with the USPTO Final Petition Decisions API.

This client provides methods to search for petition decisions, retrieve specific decisions by ID, download decision data, and download associated documents.

Final petition decisions data are incrementally added to the USPTO Open Data Portal on a monthly basis starting with data from 2022 and later.

ENDPOINTS = {'download_decisions': 'api/v1/petition/decisions/search/download', 'get_decision_by_id': 'api/v1/petition/decisions/{petitionDecisionRecordIdentifier}', 'search_decisions': 'api/v1/petition/decisions/search'}
__init__(api_key=None, base_url=None, config=None)[source]

Initialize the FinalPetitionDecisionsClient.

Parameters:

  • api_key (str | None) – Optional API key for authentication.

  • base_url (str | None) – Optional base URL override for the API.

  • config (USPTOConfig | None) – Optional USPTOConfig instance for configuration.

download_decisions(format='json', query=None, sort=None, offset=None, limit=None, fields=None, filters=None, range_filters=None, application_number_q=None, patent_number_q=None, inventor_name_q=None, applicant_name_q=None, decision_date_from_q=None, decision_date_to_q=None, additional_query_params=None, file_name=None, destination_path=None, overwrite=False)[source]

Downloads petition decisions data in the specified format.

This endpoint is designed for bulk downloads of petition decisions data. It supports JSON and CSV formats.

Parameters:

  • format (str) – Download format, either “json” or “csv”. Defaults to “json”.

  • query (str | None) – Direct query string in USPTO search syntax.

  • sort (str | None) – Sort order for results.

  • offset (int | None) – Number of records to skip (pagination).

  • limit (int | None) – Maximum number of records to return.

  • fields (str | None) – Specific fields to return.

  • filters (str | None) – Filter configuration string.

  • range_filters (str | None) – Range filter configuration string.

  • application_number_q (str | None) – Filter by application number.

  • patent_number_q (str | None) – Filter by patent number.

  • inventor_name_q (str | None) – Filter by inventor name.

  • applicant_name_q (str | None) – Filter by applicant name.

  • decision_date_from_q (str | None) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (str | None) – Filter decisions to this date (YYYY-MM-DD).

  • additional_query_params (Dict[str, Any] | None) – Additional custom query parameters.

  • file_name (str | None) – Optional filename for CSV downloads. Defaults to “petition_decisions.csv”.

  • destination_path (str | None) – Optional directory path to save CSV file. If None, returns Response.

  • overwrite (bool) – Whether to overwrite existing files. Default False.

Returns:

  • If format=”json”: Returns PetitionDecisionDownloadResponse

  • If format=”csv” and destination_path is None: Returns streaming Response

  • If format=”csv” and destination_path is set: Returns str path to saved file

Return type:

Union[PetitionDecisionDownloadResponse, requests.Response, str]

Raises:

FileExistsError – If CSV file exists and overwrite=False

Examples

# Download as JSON >>> download = client.download_decisions( … format=”json”, … technology_center_q=”1700”, … limit=1000 … ) >>> for decision in download.petition_decision_data: … print(decision.application_number_text)

# Download CSV and save to file >>> file_path = client.download_decisions( … format=”csv”, … decision_date_from_q=”2023-01-01”, … destination_path=”./downloads” … ) >>> print(f”Saved to: {file_path}”)

# Download CSV as streaming response (advanced usage) >>> response = client.download_decisions(format=”csv”) >>> with open(“decisions.csv”, “wb”) as f: … for chunk in response.iter_content(chunk_size=8192): … f.write(chunk)

download_petition_document(download_option, file_name=None, destination_path=None, overwrite=False)[source]

Downloads a petition decision document in the specified format.

Parameters:

  • download_option (DocumentDownloadOption) – DocumentDownloadOption object containing the download URL and metadata.

  • file_name (str | None) – Optional filename for the downloaded file. If not provided, it will be extracted from the URL or generated based on the MIME type.

  • destination_path (str | None) – Optional directory path where the file should be saved. If not provided, saves to the current directory.

  • overwrite (bool) – Whether to overwrite an existing file. Defaults to False.

Returns:

The absolute path to the downloaded file.

Return type:

str

Raises:

Examples

# Download first document from a decision >>> decision = client.get_decision_by_id( … “34044333-4b40-515f-a684-2515325c57c5”, … include_documents=True … ) >>> if decision.document_bag: … doc = decision.document_bag[0] … if doc.download_option_bag: … # Download PDF version … pdf_option = next( … opt for opt in doc.download_option_bag … if opt.mime_type_identifier == “PDF” … ) … path = client.download_petition_document( … pdf_option, … destination_path=”./downloads” … ) … print(f”Downloaded to: {path}”)

get_decision_by_id(petition_decision_record_identifier, include_documents=None)[source]

Retrieves a specific petition decision by its record identifier.

Parameters:

  • petition_decision_record_identifier (str) – The unique identifier for the petition decision record (UUID format).

  • include_documents (bool | None) – Whether to include associated documents in the response. If True, adds includeDocuments=true query parameter.

Returns:

The petition decision if found, None otherwise.

Return type:

Optional[PetitionDecision]

Examples

# Get decision without documents >>> decision = client.get_decision_by_id( … “9f1a4a2b-eee1-58ec-a3aa-167c4075aed4” … )

# Get decision with documents >>> decision = client.get_decision_by_id( … “34044333-4b40-515f-a684-2515325c57c5”, … include_documents=True … )

paginate_decisions(**kwargs)[source]

Provides an iterator to paginate through petition decision search results.

This method simplifies fetching all petition decisions matching a search query by automatically handling pagination. It internally calls the search_decisions method for GET requests, batching results and yielding them one by one.

All keyword arguments are passed directly to search_decisions to define the search criteria. The offset and limit parameters are managed by the pagination logic; setting them directly in kwargs might lead to unexpected behavior.

Parameters:

**kwargs (Any) – Keyword arguments passed to search_decisions for constructing the search query. Do not include post_body.

Returns:

An iterator yielding PetitionDecision objects,

allowing iteration over all matching petition decisions across multiple pages of results.

Return type:

Iterator[PetitionDecision]

Raises:

ValueError – If post_body is included in kwargs, as this method only supports GET request parameters for pagination.

Examples

# Paginate through all decisions for a technology center >>> for decision in client.paginate_decisions(technology_center_q=”1700”): … print(f”{decision.application_number_text}: {decision.decision_type_code}”)

# Paginate with date range >>> for decision in client.paginate_decisions( … decision_date_from_q=”2023-01-01”, … decision_date_to_q=”2023-12-31” … ): … process_decision(decision)

search_decisions(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, application_number_q=None, patent_number_q=None, inventor_name_q=None, applicant_name_q=None, invention_title_q=None, decision_type_code_q=None, decision_date_from_q=None, decision_date_to_q=None, petition_mail_date_from_q=None, petition_mail_date_to_q=None, technology_center_q=None, final_deciding_office_name_q=None, additional_query_params=None)[source]

Searches for final petition decisions.

This method can perform either a GET request using query parameters or a POST request if post_body is specified. When using GET, you can provide either a direct query string or use convenience parameters that will be automatically combined into a query.

Parameters:

  • query (str | None) – Direct query string in USPTO search syntax.

  • sort (str | None) – Sort order for results.

  • offset (int | None) – Number of records to skip (pagination).

  • limit (int | None) – Maximum number of records to return.

  • facets (str | None) – Facet configuration string.

  • fields (str | None) – Specific fields to return.

  • filters (str | None) – Filter configuration string.

  • range_filters (str | None) – Range filter configuration string.

  • post_body (Dict[str, Any] | None) – Optional POST body for complex queries.

  • application_number_q (str | None) – Filter by application number.

  • patent_number_q (str | None) – Filter by patent number.

  • inventor_name_q (str | None) – Filter by inventor name.

  • applicant_name_q (str | None) – Filter by applicant name.

  • invention_title_q (str | None) – Filter by invention title.

  • decision_type_code_q (str | None) – Filter by decision type code.

  • decision_date_from_q (str | None) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (str | None) – Filter decisions to this date (YYYY-MM-DD).

  • petition_mail_date_from_q (str | None) – Filter petition mail dates from (YYYY-MM-DD).

  • petition_mail_date_to_q (str | None) – Filter petition mail dates to (YYYY-MM-DD).

  • technology_center_q (str | None) – Filter by technology center.

  • final_deciding_office_name_q (str | None) – Filter by deciding office name.

  • additional_query_params (Dict[str, Any] | None) – Additional custom query parameters.

Returns:

Response containing matching petition decisions.

Return type:

PetitionDecisionResponse

Examples

# Search with direct query >>> response = client.search_decisions(query=”applicationNumberText:17765301”)

# Search with convenience parameters >>> response = client.search_decisions( … applicant_name_q=”ACME Corp”, … decision_date_from_q=”2022-01-01”, … limit=50 … )

# Search with POST body >>> response = client.search_decisions( … post_body={“q”: “technologyCenter:1700”, “limit”: 100} … )

clients.ptab_appeals - Client for USPTO PTAB Appeals API

This module provides a client for interacting with the USPTO PTAB (Patent Trial and Appeal Board) Appeals API. It allows you to search for ex parte appeal decisions.

class pyUSPTO.clients.ptab_appeals.PTABAppealsClient(api_key=None, base_url=None, config=None)[source]

Bases: BaseUSPTOClient[PTABAppealResponse]

Client for interacting with the USPTO PTAB Appeals API.

This client provides methods to search for ex parte appeal decisions from the Patent Trial and Appeal Board.

Appeals data includes decisions on patent application appeals from the examiner to the PTAB.

ENDPOINTS = {'search_decisions': 'api/v1/patent/appeals/decisions/search'}
__init__(api_key=None, base_url=None, config=None)[source]

Initialize the PTABAppealsClient.

Parameters:

  • api_key (str | None) – Optional API key for authentication.

  • base_url (str | None) – Optional base URL override for the API.

  • config (USPTOConfig | None) – Optional USPTOConfig instance for configuration.

paginate_decisions(**kwargs)[source]

Provides an iterator to paginate through appeal decision search results.

This method simplifies fetching all appeal decisions matching a search query by automatically handling pagination. It internally calls the search_decisions method for GET requests, batching results and yielding them one by one.

All keyword arguments are passed directly to search_decisions to define the search criteria. The offset and limit parameters are managed by the pagination logic; setting them directly in kwargs might lead to unexpected behavior.

Parameters:

**kwargs (Any) – Keyword arguments passed to search_decisions for constructing the search query. Do not include post_body.

Returns:

An iterator yielding PTABAppealDecision objects,

allowing iteration over all matching decisions across multiple pages of results.

Return type:

Iterator[PTABAppealDecision]

Raises:

ValueError – If post_body is included in kwargs, as this method only supports GET request parameters for pagination.

Examples

# Paginate through all decisions for a technology center >>> for decision in client.paginate_decisions(technology_center_number_q=”3600”): … print(f”{decision.appeal_meta_data.appeal_number}: ” … f”{decision.decision_data.decision_type_category}”)

# Paginate with date range >>> for decision in client.paginate_decisions( … decision_date_from_q=”2023-01-01”, … decision_date_to_q=”2023-12-31” … ): … process_decision(decision)

search_decisions(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, appeal_number_q=None, application_number_text_q=None, appellant_name_q=None, requestor_name_q=None, decision_type_category_q=None, decision_date_from_q=None, decision_date_to_q=None, technology_center_number_q=None, additional_query_params=None)[source]

Searches for PTAB appeal decisions.

This method can perform either a GET request using query parameters or a POST request if post_body is specified. When using GET, you can provide either a direct query string or use convenience parameters that will be automatically combined into a query.

Parameters:

  • query (str | None) – Direct query string in USPTO search syntax.

  • sort (str | None) – Sort order for results.

  • offset (int | None) – Number of records to skip (pagination).

  • limit (int | None) – Maximum number of records to return.

  • facets (str | None) – Facet configuration string.

  • fields (str | None) – Specific fields to return.

  • filters (str | None) – Filter configuration string.

  • range_filters (str | None) – Range filter configuration string.

  • post_body (Dict[str, Any] | None) – Optional POST body for complex queries.

  • appeal_number_q (str | None) – Filter by appeal number.

  • application_number_text_q (str | None) – Filter by application number.

  • appellant_name_q (str | None) – Filter by appellant name.

  • requestor_name_q (str | None) – Filter by requestor name.

  • decision_type_category_q (str | None) – Filter by decision type category.

  • decision_date_from_q (str | None) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (str | None) – Filter decisions to this date (YYYY-MM-DD).

  • technology_center_number_q (str | None) – Filter by technology center number.

  • additional_query_params (Dict[str, Any] | None) – Additional custom query parameters.

Returns:

Response containing matching appeal decisions.

Return type:

PTABAppealResponse

Examples

# Search with direct query >>> response = client.search_decisions(query=”appealNumber:2023-001234”)

# Search with convenience parameters >>> response = client.search_decisions( … technology_center_number_q=”3600”, … decision_date_from_q=”2023-01-01”, … limit=50 … )

# Search with POST body >>> response = client.search_decisions( … post_body={“q”: “decisionTypeCategory:Affirmed”, “limit”: 100} … )

clients.ptab_interferences - Client for USPTO PTAB Interferences API

This module provides a client for interacting with the USPTO PTAB (Patent Trial and Appeal Board) Interferences API. It allows you to search for patent interference decisions.

class pyUSPTO.clients.ptab_interferences.PTABInterferencesClient(api_key=None, base_url=None, config=None)[source]

Bases: BaseUSPTOClient[PTABInterferenceResponse]

Client for interacting with the USPTO PTAB Interferences API.

This client provides methods to search for patent interference decisions from the Patent Trial and Appeal Board.

Interference proceedings are used to determine priority of invention when two or more parties claim the same patentable invention.

ENDPOINTS = {'search_decisions': 'api/v1/patent/interferences/decisions/search'}
__init__(api_key=None, base_url=None, config=None)[source]

Initialize the PTABInterferencesClient.

Parameters:

  • api_key (str | None) – Optional API key for authentication.

  • base_url (str | None) – Optional base URL override for the API.

  • config (USPTOConfig | None) – Optional USPTOConfig instance for configuration.

paginate_decisions(**kwargs)[source]

Provides an iterator to paginate through interference decision search results.

This method simplifies fetching all interference decisions matching a search query by automatically handling pagination. It internally calls the search_decisions method for GET requests, batching results and yielding them one by one.

All keyword arguments are passed directly to search_decisions to define the search criteria. The offset and limit parameters are managed by the pagination logic; setting them directly in kwargs might lead to unexpected behavior.

Parameters:

**kwargs (Any) – Keyword arguments passed to search_decisions for constructing the search query. Do not include post_body.

Returns:

An iterator yielding PTABInterferenceDecision

objects, allowing iteration over all matching decisions across multiple pages of results.

Return type:

Iterator[PTABInterferenceDecision]

Raises:

ValueError – If post_body is included in kwargs, as this method only supports GET request parameters for pagination.

Examples

# Paginate through all interference decisions >>> for decision in client.paginate_decisions(): … print(f”{decision.interference_meta_data.interference_number}: ” … f”{decision.document_data.interference_outcome_category}”)

# Paginate with date range >>> for decision in client.paginate_decisions( … decision_date_from_q=”2020-01-01”, … decision_date_to_q=”2023-12-31” … ): … process_decision(decision)

search_decisions(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, interference_number_q=None, senior_party_application_number_q=None, junior_party_application_number_q=None, senior_party_name_q=None, junior_party_name_q=None, real_party_in_interest_q=None, interference_outcome_category_q=None, decision_type_category_q=None, decision_date_from_q=None, decision_date_to_q=None, additional_query_params=None)[source]

Searches for PTAB interference decisions.

This method can perform either a GET request using query parameters or a POST request if post_body is specified. When using GET, you can provide either a direct query string or use convenience parameters that will be automatically combined into a query.

Parameters:

  • query (str | None) – Direct query string in USPTO search syntax.

  • sort (str | None) – Sort order for results.

  • offset (int | None) – Number of records to skip (pagination).

  • limit (int | None) – Maximum number of records to return.

  • facets (str | None) – Facet configuration string.

  • fields (str | None) – Specific fields to return.

  • filters (str | None) – Filter configuration string.

  • range_filters (str | None) – Range filter configuration string.

  • post_body (Dict[str, Any] | None) – Optional POST body for complex queries.

  • interference_number_q (str | None) – Filter by interference number.

  • senior_party_application_number_q (str | None) – Filter by senior party application number.

  • junior_party_application_number_q (str | None) – Filter by junior party application number.

  • senior_party_name_q (str | None) – Filter by senior party name.

  • junior_party_name_q (str | None) – Filter by junior party name.

  • real_party_in_interest_q (str | None) – Filter by Real Party in Interest.

  • interference_outcome_category_q (str | None) – Filter by interference outcome category.

  • decision_type_category_q (str | None) – Filter by decision type category.

  • decision_date_from_q (str | None) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (str | None) – Filter decisions to this date (YYYY-MM-DD).

  • additional_query_params (Dict[str, Any] | None) – Additional custom query parameters.

Returns:

Response containing matching interference decisions.

Return type:

PTABInterferenceResponse

Examples

# Search with direct query >>> response = client.search_decisions(query=”interferenceNumber:106123”)

# Search with convenience parameters >>> response = client.search_decisions( … interference_outcome_category_q=”Priority to Senior Party”, … decision_date_from_q=”2020-01-01”, … limit=50 … )

# Search with POST body >>> response = client.search_decisions( … post_body={“q”: “decisionTypeCategory:Final Decision”, “limit”: 100} … )

clients.ptab_trials - Client for USPTO PTAB Trials API

This module provides a client for interacting with the USPTO PTAB (Patent Trial and Appeal Board) Trials API. It allows you to search for trial proceedings, documents, and decisions.

class pyUSPTO.clients.ptab_trials.PTABTrialsClient(api_key=None, base_url=None, config=None)[source]

Bases: BaseUSPTOClient[PTABTrialProceedingResponse | PTABTrialDocumentResponse]

Client for interacting with the USPTO PTAB Trials API.

This client provides methods to search for trial proceedings, trial documents, and trial decisions from the Patent Trial and Appeal Board.

Trial proceedings data includes IPR (Inter Partes Review), PGR (Post-Grant Review), CBM (Covered Business Method), and DER (Derivation) proceedings.

ENDPOINTS = {'search_decisions': 'api/v1/patent/trials/decisions/search', 'search_documents': 'api/v1/patent/trials/documents/search', 'search_proceedings': 'api/v1/patent/trials/proceedings/search'}
__init__(api_key=None, base_url=None, config=None)[source]

Initialize the PTABTrialsClient.

Parameters:

  • api_key (str | None) – Optional API key for authentication.

  • base_url (str | None) – Optional base URL override for the API.

  • config (USPTOConfig | None) – Optional USPTOConfig instance for configuration.

paginate_proceedings(**kwargs)[source]

Provides an iterator to paginate through trial proceeding search results.

Return type:

Iterator[PTABTrialProceeding]

search_decisions(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, trial_number_q=None, decision_type_category_q=None, document_type_description_q=None, decision_date_from_q=None, decision_date_to_q=None, trial_type_code_q=None, patent_number_q=None, application_number_q=None, patent_owner_name_q=None, trial_status_category_q=None, real_party_in_interest_name_q=None, document_category_q=None, additional_query_params=None)[source]

Searches for PTAB trial decisions.

This method can perform either a GET request using query parameters or a POST request if post_body is specified. When using GET, you can provide either a direct query string or use convenience parameters that will be automatically combined into a query.

Parameters:

  • query (str | None) – Direct query string in USPTO search syntax.

  • sort (str | None) – Sort order for results.

  • offset (int | None) – Number of records to skip (pagination).

  • limit (int | None) – Maximum number of records to return.

  • facets (str | None) – Facet configuration string.

  • fields (str | None) – Specific fields to return.

  • filters (str | None) – Filter configuration string.

  • range_filters (str | None) – Range filter configuration string.

  • post_body (Dict[str, Any] | None) – Optional POST body for complex queries.

  • trial_number_q (str | None) – Filter by trial number.

  • decision_type_category_q (str | None) – Filter by decision type category.

  • document_type_description_q (str | None) – Filter by “[description]”.

  • decision_date_from_q (str | None) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (str | None) – Filter decisions to this date (YYYY-MM-DD).

  • trial_type_code_q (str | None) – Filter by trial type code (e.g., “IPR”, “PGR”, “CBM”, “DER”).

  • patent_number_q (str | None) – Filter by patent number.

  • application_number_q (str | None) – Filter by application number.

  • patent_owner_name_q (str | None) – Filter by patent owner name.

  • trial_status_category_q (str | None) – Filter by trial status category.

  • real_party_in_interest_name_q (str | None) – Filter by real party in interest name.

  • document_category_q (str | None) – Filter by document category.

  • additional_query_params (Dict[str, Any] | None) – Additional custom query parameters.

Returns:

Response containing matching trial decisions.

Return type:

PTABTrialDocumentResponse

Examples

# Search with direct query >>> response = client.search_decisions(query=”trialNumber:IPR2023-00001”)

# Search with convenience parameters >>> response = client.search_decisions( … decision_type_category_q=”Final Written Decision”, … decision_date_from_q=”2023-01-01”, … limit=50 … )

search_documents(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, trial_number_q=None, document_category_q=None, document_type_name_q=None, filing_date_from_q=None, filing_date_to_q=None, petitioner_real_party_in_interest_name_q=None, inventor_name_q=None, real_party_in_interest_name_q=None, patent_number_q=None, patent_owner_name_q=None, additional_query_params=None)[source]

Searches for PTAB trial documents.

This method can perform either a GET request using query parameters or a POST request if post_body is specified. When using GET, you can provide either a direct query string or use convenience parameters that will be automatically combined into a query.

Parameters:

  • query (str | None) – Direct query string in USPTO search syntax.

  • sort (str | None) – Sort order for results.

  • offset (int | None) – Number of records to skip (pagination).

  • limit (int | None) – Maximum number of records to return.

  • facets (str | None) – Facet configuration string.

  • fields (str | None) – Specific fields to return.

  • filters (str | None) – Filter configuration string.

  • range_filters (str | None) – Range filter configuration string.

  • post_body (Dict[str, Any] | None) – Optional POST body for complex queries.

  • trial_number_q (str | None) – Filter by trial number.

  • document_category_q (str | None) – Filter by document category (e.g., “Petition”) DOCUMENTED BUT NOT IN API.

  • document_type_name_q (str | None) – Filter by document type name (description).

  • filing_date_from_q (str | None) – Filter documents from this date (YYYY-MM-DD).

  • filing_date_to_q (str | None) – Filter documents to this date (YYYY-MM-DD).

  • petitioner_real_party_in_interest_name_q (str | None) – Filter by petitioner real party in interest.

  • inventor_name_q (str | None) – Filter by inventor name.

  • real_party_in_interest_name_q (str | None) – Filter by real party in interest (generic).

  • patent_number_q (str | None) – Filter by patent number.

  • patent_owner_name_q (str | None) – Filter by patent owner name.

  • additional_query_params (Dict[str, Any] | None) – Additional custom query parameters.

Returns:

Response containing matching trial documents.

Return type:

PTABTrialDocumentResponse

Examples

# Search with direct query >>> response = client.search_documents(query=”trialNumber:IPR2023-00001”)

# Search with convenience parameters >>> response = client.search_documents( … document_category_q=”Paper”, … filing_date_from_q=”2023-01-01”, … limit=50 … )

search_proceedings(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, trial_number_q=None, patent_owner_name_q=None, petitioner_real_party_in_interest_name_q=None, respondent_name_q=None, trial_type_code_q=None, trial_status_category_q=None, petition_filing_date_from_q=None, petition_filing_date_to_q=None, additional_query_params=None)[source]

Searches for PTAB trial proceedings.

This method can perform either a GET request using query parameters or a POST request if post_body is specified. When using GET, you can provide either a direct query string or use convenience parameters that will be automatically combined into a query.

Parameters:

  • query (str | None) – Direct query string in USPTO search syntax.

  • sort (str | None) – Sort order for results.

  • offset (int | None) – Number of records to skip (pagination).

  • limit (int | None) – Maximum number of records to return.

  • facets (str | None) – Facet configuration string.

  • fields (str | None) – Specific fields to return.

  • filters (str | None) – Filter configuration string.

  • range_filters (str | None) – Range filter configuration string.

  • post_body (Dict[str, Any] | None) – Optional POST body for complex queries.

  • trial_number_q (str | None) – Filter by trial number (e.g., “IPR2023-00001”).

  • patent_owner_name_q (str | None) – Filter by patent owner name.

  • petitioner_real_party_in_interest_name_q (str | None) – Filter by petitioner real party in interest.

  • respondent_name_q (str | None) – Filter by respondent name.

  • trial_type_code_q (str | None) – Filter by trial type code (e.g., “IPR”, “PGR”, “CBM”, “DER”).

  • trial_status_category_q (str | None) – Filter by trial status category.

  • petition_filing_date_from_q (str | None) – Filter proceedings from this date (YYYY-MM-DD).

  • petition_filing_date_to_q (str | None) – Filter proceedings to this date (YYYY-MM-DD).

  • additional_query_params (Dict[str, Any] | None) – Additional custom query parameters.

Returns:

Response containing matching trial proceedings.

Return type:

PTABTrialProceedingResponse

Examples

# Search with direct query >>> response = client.search_proceedings(query=”trialNumber:IPR2023-00001”)

# Search with convenience parameters >>> response = client.search_proceedings( … trial_type_code_q=”IPR”, … petition_filing_date_from_q=”2023-01-01”, … limit=50 … )