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': 'api/v1/datasets/products/files/{file_download_uri}', 'product_by_id': 'api/v1/datasets/products/{product_id}', 'products_search': 'api/v1/datasets/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 (Optional[str]) – Filter files by data from date (YYYY-MM-DD)

  • file_data_to_date (Optional[str]) – Filter files by data to date (YYYY-MM-DD)

  • offset (Optional[int]) – Number of product file records to skip

  • limit (Optional[int]) – Number of product file records to collect

  • include_files (Optional[bool]) – Whether to include product files in the response

  • latest (Optional[bool]) – 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 (Optional[dict[str, Any]]) – Optional query parameters

Return type:

BulkDataResponse

Returns:

BulkDataResponse object containing the API response

paginate_products(post_body=None, **kwargs)[source]

Paginate through all products matching the search criteria.

Supports both GET and POST requests.

Parameters:

  • post_body (Optional[dict[str, Any]]) – Optional POST body for complex search queries

  • **kwargs (Any) – Keyword arguments for GET-based pagination

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 (Optional[str]) – Search text

  • product_title (Optional[str]) – Filter by product title

  • product_description (Optional[str]) – Filter by product description

  • product_short_name (Optional[str]) – Filter by product identifier (short name)

  • from_date (Optional[str]) – Filter products with data from this date (YYYY-MM-DD)

  • to_date (Optional[str]) – Filter products with data until this date (YYYY-MM-DD)

  • categories (Optional[list[str]]) – Filter by dataset categories

  • labels (Optional[list[str]]) – Filter by product labels

  • datasets (Optional[list[str]]) – Filter by datasets

  • file_types (Optional[list[str]]) – Filter by file types

  • offset (Optional[int]) – Number of product records to skip

  • limit (Optional[int]) – Number of product records to collect

  • include_files (Optional[bool]) – Whether to include product files in the response

  • latest (Optional[bool]) – Whether to return only the latest product file for each product

  • facets (Optional[bool]) – 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'}
__init__(api_key=None, base_url=None, config=None)[source]

Initialize the PatentDataClient.

Parameters:

  • api_key (Optional[str]) – USPTO API key. If not provided, uses key from config or environment.

  • base_url (Optional[str]) – Base URL for the USPTO Patent Data API. Defaults to https://api.uspto.gov.

  • config (Optional[USPTOConfig]) – USPTOConfig instance. If not provided, creates one with the given api_key.

download_archive(printed_metadata, destination=None, file_name=None, overwrite=False)[source]

Download Printed Metadata (XML data).

These are XML files of the patent as printed. Auto-extracts if the server sends a TAR/ZIP archive.

Note

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

Parameters:

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

  • destination (Optional[str]) – Optional directory path to save the file

  • file_name (Optional[str]) – Optional filename. If not provided, uses Content-Disposition header

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

Returns:

Path to the downloaded file (extracted if was in archive)

Return type:

str

Raises:
download_document(document, format=DocumentMimeType.PDF, destination=None, file_name=None, overwrite=False)[source]

Download document in specified format.

Automatically extracts if USPTO sends TAR/ZIP.

Parameters:

  • document (Document) – Document with document_formats list

  • format (str | DocumentMimeType) – Which format (PDF, XML, MS_WORD). Can be string or DocumentMimeType enum. Defaults to PDF.

  • destination (Optional[str]) – Directory to save to (default: current directory)

  • file_name (Optional[str]) – Override filename (default: from Content-Disposition)

  • overwrite (bool) – Overwrite existing file

Return type:

str

Returns:

Path to downloaded file (extracted if was in archive)

Raises:

FormatNotAvailableError – If format not available for this document. The exception includes requested_format, available_formats, and document attributes for programmatic error handling.

Example

>>> docs = client.get_application_documents("19312841", document_codes=["CTNF"])
>>> path = client.download_document(docs[0], format="XML")
>>> # Or using enum:
>>> path = client.download_document(docs[0], format=DocumentMimeType.XML)
download_publication(printed_metadata, destination=None, file_name=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). Auto-extracts if the server sends a TAR/ZIP archive.

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.

  • destination (Optional[str]) – 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.

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

  • 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 (extracted if was in archive).

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="./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="./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]

Retrieve 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]

Retrieve 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]

Retrieve 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]

Retrieve 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]

Retrieve 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]

Retrieve 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]

Retrieve 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]

Retrieve 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]

Retrieve 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]

Retrieve 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]

Retrieve 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]

Fetch 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]

Retrieve 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(post_body=None, **kwargs)[source]

Provide 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. Supports both GET and POST requests.

For GET requests, provide search parameters as keyword arguments. For POST requests, provide the search criteria in post_body.

The offset and limit parameters are managed by the pagination logic; setting them directly in kwargs or post_body might lead to unexpected behavior.

Parameters:

  • post_body (Optional[dict[str, Any]]) – Optional POST body for complex search queries. If provided, performs POST-based pagination.

  • **kwargs (Any) – Keyword arguments for GET-based pagination or additional query parameters for POST requests.

Returns:

An iterator that yields PatentFileWrapper

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

Return type:

Iterator[PatentFileWrapper]

Examples

# GET-based pagination for wrapper in client.paginate_applications(

query=”applicationNumberText:16*”, limit=50

):

print(wrapper.application_number_text)

# POST-based pagination for wrapper in client.paginate_applications(

post_body={

“q”: “applicationNumberText:16*”, “facets”: “true”, “fields”: “applicationNumberText,applicationMetaData”

}

):

print(wrapper.application_number_text)

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]

Search 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]

Search 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 (Optional[str]) – Optional API key for authentication.

  • base_url (Optional[str]) – Optional base URL override for the API.

  • config (Optional[USPTOConfig]) – 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=None, overwrite=False)[source]

Download 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 (Optional[str]) – Direct query string in USPTO search syntax.

  • sort (Optional[str]) – Sort order for results.

  • offset (Optional[int]) – Number of records to skip (pagination).

  • limit (Optional[int]) – Maximum number of records to return.

  • fields (Optional[str]) – Specific fields to return.

  • filters (Optional[str]) – Filter configuration string.

  • range_filters (Optional[str]) – Range filter configuration string.

  • application_number_q (Optional[str]) – Filter by application number.

  • patent_number_q (Optional[str]) – Filter by patent number.

  • inventor_name_q (Optional[str]) – Filter by inventor name.

  • applicant_name_q (Optional[str]) – Filter by applicant name.

  • decision_date_from_q (Optional[str]) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (Optional[str]) – Filter decisions to this date (YYYY-MM-DD).

  • additional_query_params (Optional[dict[str, Any]]) – Additional custom query parameters.

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

  • destination (Optional[str]) – 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 is None: Returns streaming Response

  • If format=”csv” and destination 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=”./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, destination=None, file_name=None, overwrite=False)[source]

Download petition document (auto-extracts if in archive).

Parameters:

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

  • destination (Optional[str]) – Optional directory path where the file should be saved. If not provided, saves to the current directory.

  • file_name (Optional[str]) – Optional filename for the downloaded file. If not provided, it will be extracted from Content-Disposition header or URL.

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

Returns:

The absolute path to the downloaded file (extracted if was in archive).

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=”./downloads” … ) … print(f”Downloaded to: {path}”)

get_decision_by_id(petition_decision_record_identifier, include_documents=None)[source]

Retrieve 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 (Optional[bool]) – 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(post_body=None, **kwargs)[source]

Provide an iterator to paginate through petition decision search results.

This method simplifies fetching all petition decisions matching a search query by automatically handling pagination. Supports both GET and POST requests.

The offset and limit parameters are managed by the pagination logic; setting them directly in kwargs or post_body might lead to unexpected behavior.

Parameters:

  • post_body (Optional[dict[str, Any]]) – Optional POST body for complex search queries

  • **kwargs (Any) – Keyword arguments for GET-based pagination

Returns:

An iterator yielding PetitionDecision objects,

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

Return type:

Iterator[PetitionDecision]

Examples

# GET pagination 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}”)

# POST pagination with date range >>> for decision in client.paginate_decisions( … post_body={ … “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]

Return final petition decisions matching the given criteria.

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 (Optional[str]) – Direct query string in USPTO search syntax.

  • sort (Optional[str]) – Sort order for results.

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

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

  • facets (Optional[str]) – Facet configuration string.

  • fields (Optional[str]) – Specific fields to return.

  • filters (Optional[str]) – Filter configuration string.

  • range_filters (Optional[str]) – Range filter configuration string.

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

  • application_number_q (Optional[str]) – Filter by application number.

  • patent_number_q (Optional[str]) – Filter by patent number.

  • inventor_name_q (Optional[str]) – Filter by inventor name.

  • applicant_name_q (Optional[str]) – Filter by applicant name.

  • invention_title_q (Optional[str]) – Filter by invention title.

  • decision_type_code_q (Optional[str]) – Filter by decision type code.

  • decision_date_from_q (Optional[str]) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (Optional[str]) – Filter decisions to this date (YYYY-MM-DD).

  • petition_mail_date_from_q (Optional[str]) – Filter petition mail dates from (YYYY-MM-DD).

  • petition_mail_date_to_q (Optional[str]) – Filter petition mail dates to (YYYY-MM-DD).

  • technology_center_q (Optional[str]) – Filter by technology center.

  • final_deciding_office_name_q (Optional[str]) – Filter by deciding office name.

  • additional_query_params (Optional[dict[str, Any]]) – 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 (Optional[str]) – Optional API key for authentication.

  • base_url (Optional[str]) – Optional base URL override for the API.

  • config (Optional[USPTOConfig]) – Optional USPTOConfig instance for configuration.

download_appeal_archive(appeal_meta_data, destination=None, file_name=None, overwrite=False)[source]

Download appeal archive (ZIP/TAR) without extraction.

Parameters:

  • appeal_meta_data (AppealMetaData) – AppealMetaData with file_download_uri

  • destination (Optional[str]) – Directory to save to

  • file_name (Optional[str]) – Override filename

  • overwrite (bool) – Overwrite existing file

Return type:

str

Returns:

Path to downloaded archive file

Raises:

ValueError – If appeal_meta_data has no file_download_uri

download_appeal_document(document_data, destination=None, file_name=None, overwrite=False)[source]

Download individual appeal document (auto-extracts if needed).

Parameters:

  • document_data (AppealDocumentData) – AppealDocumentData with file_download_uri

  • destination (Optional[str]) – Directory to save to

  • file_name (Optional[str]) – Override filename

  • overwrite (bool) – Overwrite existing file

Return type:

str

Returns:

Path to downloaded file

Raises:

ValueError – If document_data has no file_download_uri

download_appeal_documents(appeal_meta_data, destination=None, overwrite=False)[source]

Download and extract all appeal documents.

Parameters:

  • appeal_meta_data (AppealMetaData) – AppealMetaData with file_download_uri

  • destination (Optional[str]) – Directory to save/extract to

  • overwrite (bool) – Overwrite existing files

Return type:

str

Returns:

Path to extraction directory

Raises:

ValueError – If appeal_meta_data has no file_download_uri

paginate_decisions(post_body=None, **kwargs)[source]

Provide 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, batching results and yielding them one by one.

Supports both GET and POST requests. For POST requests, provide the search criteria in post_body. For GET requests, use keyword arguments.

The offset parameter is managed by the pagination logic and should not be provided by the user. The limit parameter can be customized.

Parameters:

  • post_body (Optional[dict[str, Any]]) – Optional POST body for complex search queries.

  • **kwargs (Any) – Keyword arguments passed to search_decisions for constructing the search query (for GET-based pagination).

Returns:

An iterator yielding PTABAppealDecision objects,

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

Return type:

Iterator[PTABAppealDecision]

Examples

# GET-based pagination with convenience parameters >>> 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}”)

# GET-based pagination with date range and custom limit >>> for decision in client.paginate_decisions( … decision_date_from_q=”2023-01-01”, … decision_date_to_q=”2023-12-31”, … limit=50 … ): … process_decision(decision)

# POST-based pagination >>> for decision in client.paginate_decisions( … post_body={“q”: “decisionTypeCategory:Affirmed”, “limit”: 100} … ): … 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]

Search 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 (Optional[str]) – Direct query string in USPTO search syntax.

  • sort (Optional[str]) – Sort order for results.

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

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

  • facets (Optional[str]) – Facet configuration string.

  • fields (Optional[str]) – Specific fields to return.

  • filters (Optional[str]) – Filter configuration string.

  • range_filters (Optional[str]) – Range filter configuration string.

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

  • appeal_number_q (Optional[str]) – Filter by appeal number.

  • application_number_text_q (Optional[str]) – Filter by application number.

  • appellant_name_q (Optional[str]) – Filter by appellant name.

  • requestor_name_q (Optional[str]) – Filter by requestor name.

  • decision_type_category_q (Optional[str]) – Filter by decision type category.

  • decision_date_from_q (Optional[str]) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (Optional[str]) – Filter decisions to this date (YYYY-MM-DD).

  • technology_center_number_q (Optional[str]) – Filter by technology center number.

  • additional_query_params (Optional[dict[str, Any]]) – 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 (Optional[str]) – Optional API key for authentication.

  • base_url (Optional[str]) – Optional base URL override for the API.

  • config (Optional[USPTOConfig]) – Optional USPTOConfig instance for configuration.

download_interference_archive(interference_meta_data, destination=None, file_name=None, overwrite=False)[source]

Download interference archive (ZIP/TAR) without extraction.

Parameters:

  • interference_meta_data (InterferenceMetaData) – InterferenceMetaData with file_download_uri

  • destination (Optional[str]) – Directory to save to

  • file_name (Optional[str]) – Override filename

  • overwrite (bool) – Overwrite existing file

Return type:

str

Returns:

Path to downloaded archive file

Raises:

ValueError – If interference_meta_data has no file_download_uri

download_interference_document(document_data, destination=None, file_name=None, overwrite=False)[source]

Download individual interference document (auto-extracts if needed).

Parameters:
Return type:

str

Returns:

Path to downloaded file

Raises:

ValueError – If document_data has no file_download_uri

download_interference_documents(interference_meta_data, destination=None, overwrite=False)[source]

Download and extract all interference documents.

Parameters:

  • interference_meta_data (InterferenceMetaData) – InterferenceMetaData with file_download_uri

  • destination (Optional[str]) – Directory to save/extract to

  • overwrite (bool) – Overwrite existing files

Return type:

str

Returns:

Path to extraction directory

Raises:

ValueError – If interference_meta_data has no file_download_uri

paginate_decisions(post_body=None, **kwargs)[source]

Provide 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, batching results and yielding them one by one.

Supports both GET and POST requests. For POST requests, provide the search criteria in post_body. For GET requests, use keyword arguments.

The offset parameter is managed by the pagination logic and should not be provided by the user. The limit parameter can be customized.

Parameters:

  • post_body (Optional[dict[str, Any]]) – Optional POST body for complex search queries.

  • **kwargs (Any) – Keyword arguments passed to search_decisions for constructing the search query (for GET-based pagination).

Returns:

An iterator yielding PTABInterferenceDecision

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

Return type:

Iterator[PTABInterferenceDecision]

Examples

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

# GET-based pagination with date range and custom limit >>> for decision in client.paginate_decisions( … decision_date_from_q=”2020-01-01”, … decision_date_to_q=”2023-12-31”, … limit=50 … ): … process_decision(decision)

# POST-based pagination >>> for decision in client.paginate_decisions( … post_body={“q”: “interferenceOutcomeCategory:Priority to Senior Party”} … ): … 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]

Search 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 (Optional[str]) – Direct query string in USPTO search syntax.

  • sort (Optional[str]) – Sort order for results.

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

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

  • facets (Optional[str]) – Facet configuration string.

  • fields (Optional[str]) – Specific fields to return.

  • filters (Optional[str]) – Filter configuration string.

  • range_filters (Optional[str]) – Range filter configuration string.

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

  • interference_number_q (Optional[str]) – Filter by interference number.

  • senior_party_application_number_q (Optional[str]) – Filter by senior party application number.

  • junior_party_application_number_q (Optional[str]) – Filter by junior party application number.

  • senior_party_name_q (Optional[str]) – Filter by senior party name.

  • junior_party_name_q (Optional[str]) – Filter by junior party name.

  • real_party_in_interest_q (Optional[str]) – Filter by Real Party in Interest.

  • interference_outcome_category_q (Optional[str]) – Filter by interference outcome category.

  • decision_type_category_q (Optional[str]) – Filter by decision type category.

  • decision_date_from_q (Optional[str]) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (Optional[str]) – Filter decisions to this date (YYYY-MM-DD).

  • additional_query_params (Optional[dict[str, Any]]) – 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 (Optional[str]) – Optional API key for authentication.

  • base_url (Optional[str]) – Optional base URL override for the API.

  • config (Optional[USPTOConfig]) – Optional USPTOConfig instance for configuration.

download_trial_archive(trial_meta_data, destination=None, file_name=None, overwrite=False)[source]

Download trial archive (ZIP/TAR) without extraction.

Parameters:

  • trial_meta_data (TrialMetaData) – TrialMetaData with file_download_uri

  • destination (Optional[str]) – Directory to save to

  • file_name (Optional[str]) – Override filename

  • overwrite (bool) – Overwrite existing file

Return type:

str

Returns:

Path to downloaded archive file

Raises:

ValueError – If trial_meta_data has no file_download_uri

download_trial_document(document_data, destination=None, file_name=None, overwrite=False)[source]

Download individual trial document (auto-extracts if needed).

Parameters:

  • document_data (TrialDocumentData) – TrialDocumentData with file_download_uri

  • destination (Optional[str]) – Directory to save to

  • file_name (Optional[str]) – Override filename

  • overwrite (bool) – Overwrite existing file

Return type:

str

Returns:

Path to downloaded file

Raises:

ValueError – If document_data has no file_download_uri

download_trial_documents(trial_meta_data, destination=None, overwrite=False)[source]

Download and extract all trial documents.

Parameters:

  • trial_meta_data (TrialMetaData) – TrialMetaData with file_download_uri

  • destination (Optional[str]) – Directory to save/extract to

  • overwrite (bool) – Overwrite existing files

Return type:

str

Returns:

Path to extraction directory

Raises:

ValueError – If trial_meta_data has no file_download_uri

paginate_proceedings(post_body=None, **kwargs)[source]

Provide an iterator to paginate through trial proceeding search results.

Supports both GET and POST requests.

Parameters:

  • post_body (Optional[dict[str, Any]]) – Optional POST body for complex search queries

  • **kwargs (Any) – Keyword arguments for GET-based pagination

Yields:

PTABTrialProceeding objects

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]

Search 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 (Optional[str]) – Direct query string in USPTO search syntax.

  • sort (Optional[str]) – Sort order for results.

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

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

  • facets (Optional[str]) – Facet configuration string.

  • fields (Optional[str]) – Specific fields to return.

  • filters (Optional[str]) – Filter configuration string.

  • range_filters (Optional[str]) – Range filter configuration string.

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

  • trial_number_q (Optional[str]) – Filter by trial number.

  • decision_type_category_q (Optional[str]) – Filter by decision type category.

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

  • decision_date_from_q (Optional[str]) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (Optional[str]) – Filter decisions to this date (YYYY-MM-DD).

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

  • patent_number_q (Optional[str]) – Filter by patent number.

  • application_number_q (Optional[str]) – Filter by application number.

  • patent_owner_name_q (Optional[str]) – Filter by patent owner name.

  • trial_status_category_q (Optional[str]) – Filter by trial status category.

  • real_party_in_interest_name_q (Optional[str]) – Filter by real party in interest name.

  • document_category_q (Optional[str]) – Filter by document category.

  • additional_query_params (Optional[dict[str, Any]]) – 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]

Search 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 (Optional[str]) – Direct query string in USPTO search syntax.

  • sort (Optional[str]) – Sort order for results.

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

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

  • facets (Optional[str]) – Facet configuration string.

  • fields (Optional[str]) – Specific fields to return.

  • filters (Optional[str]) – Filter configuration string.

  • range_filters (Optional[str]) – Range filter configuration string.

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

  • trial_number_q (Optional[str]) – Filter by trial number.

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

  • document_type_name_q (Optional[str]) – Filter by document type name (description).

  • filing_date_from_q (Optional[str]) – Filter documents from this date (YYYY-MM-DD).

  • filing_date_to_q (Optional[str]) – Filter documents to this date (YYYY-MM-DD).

  • petitioner_real_party_in_interest_name_q (Optional[str]) – Filter by petitioner real party in interest.

  • inventor_name_q (Optional[str]) – Filter by inventor name.

  • real_party_in_interest_name_q (Optional[str]) – Filter by real party in interest (generic).

  • patent_number_q (Optional[str]) – Filter by patent number.

  • patent_owner_name_q (Optional[str]) – Filter by patent owner name.

  • additional_query_params (Optional[dict[str, Any]]) – 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]

Search 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 (Optional[str]) – Direct query string in USPTO search syntax.

  • sort (Optional[str]) – Sort order for results.

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

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

  • facets (Optional[str]) – Facet configuration string.

  • fields (Optional[str]) – Specific fields to return.

  • filters (Optional[str]) – Filter configuration string.

  • range_filters (Optional[str]) – Range filter configuration string.

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

  • trial_number_q (Optional[str]) – Filter by trial number (e.g., “IPR2023-00001”).

  • patent_owner_name_q (Optional[str]) – Filter by patent owner name.

  • petitioner_real_party_in_interest_name_q (Optional[str]) – Filter by petitioner real party in interest.

  • respondent_name_q (Optional[str]) – Filter by respondent name.

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

  • trial_status_category_q (Optional[str]) – Filter by trial status category.

  • petition_filing_date_from_q (Optional[str]) – Filter proceedings from this date (YYYY-MM-DD).

  • petition_filing_date_to_q (Optional[str]) – Filter proceedings to this date (YYYY-MM-DD).

  • additional_query_params (Optional[dict[str, Any]]) – 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 … )