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)

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)

Initialize the BulkDataClient.

Parameters:

• api_key (Optional[str]) – Optional API key for authentication

• base_url (Optional[str]) – The base URL of the API, defaults to config.bulk_data_base_url or “https://api.uspto.gov/api/v1/datasets”

• config (Optional[USPTOConfig]) – Optional USPTOConfig instance

download_file(file_data, destination)

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)

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)

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(**kwargs)

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)

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)

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)

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

Parameters:

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

• file_name (Optional[str]) – Optional filename. If not provided, uses zip_file_name from metadata

• destination_path (Optional[str]) – Optional directory path to save the archive

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

Returns:

Path to the downloaded archive file

Return type:

str

Raises:

• ValueError – If archive_metadata has no download URL

• FileExistsError – If file exists and overwrite=False

download_document(document_format, file_name=None, destination_path=None, overwrite=False, stream=True)

Downloads a document in the specified format.

Parameters:

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

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

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

• ValueError – If document_format has no download URL

• FileExistsError – If file exists and overwrite=False

get_IFW_metadata(application_number=None, publication_number=None, patent_number=None, PCT_app_number=None, PCT_pub_number=None)

Return type:

Optional[PatentFileWrapper]

get_application_adjustment(application_number)

Retrieves patent term adjustment data for a specific application.

Return type:

Optional[PatentTermAdjustmentData]

get_application_assignment(application_number)

Retrieves assignment data for a specific application.

Return type:

Optional[List[Assignment]]

get_application_associated_documents(application_number)

Retrieves associated documents data for a specific application.

Return type:

Optional[PrintedPublication]

get_application_attorney(application_number)

Retrieves attorney data for a specific application.

Return type:

Optional[RecordAttorney]

get_application_by_number(application_number)

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

Return type:

Optional[PatentFileWrapper]

get_application_continuity(application_number)

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

Return type:

Optional[ApplicationContinuityData]

get_application_documents(application_number)

Retrieves a list of documents associated with a specific application.

Return type:

DocumentBag

get_application_foreign_priority(application_number)

Retrieves foreign priority data for a specific application.

Return type:

Optional[List[ForeignPriority]]

get_application_metadata(application_number)

Retrieves metadata for a specific patent application.

Return type:

Optional[ApplicationMetaData]

get_application_transactions(application_number)

Retrieves transaction history (events) for a specific application.

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)

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. Legacy _q parameters are used to construct the ‘q’ query parameter for GET if ‘query’ is not directly provided.

Return type:

PatentDataResponse

get_status_codes(params=None)

Retrieves patent status codes using a GET request.

Return type:

StatusCodeSearchResponse

paginate_applications(**kwargs)

Paginates through application search results using GET requests. Passes keyword arguments to search_applications for query construction.

Return type:

Iterator[PatentFileWrapper]

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)

Searches for patent applications. Can perform a GET request based on OpenAPI query parameters or a POST request if post_body is specified. Legacy _q parameters are used to construct the ‘q’ query parameter if ‘query’ is not directly provided.

Return type:

PatentDataResponse

search_status_codes(search_request)

Searches patent status codes using a POST request.

Return type:

StatusCodeSearchResponse