PTAB Trials Example — pyUSPTO 0.2.3.dev1+g2c5d89b38.d20251125 documentation

# PTAB Trials Example

      1"""
      2Example usage of the pyUSPTO module for PTAB Trials API
      3
      4This example demonstrates how to use the PTABTrialsClient to interact with the USPTO PTAB
      5(Patent Trial and Appeal Board) Trials API. It shows how to search for trial proceedings,
      6documents, and decisions using various search criteria.
      7
      8PTAB Trials include:
      9- IPR (Inter Partes Review)
     10- PGR (Post-Grant Review)
     11- CBM (Covered Business Method)
     12- DER (Derivation) proceedings
     13"""
     14
     15import os
     16
     17from pyUSPTO import PTABTrialsClient, USPTOConfig
     18
     19# --- Initialization ---
     20# Choose one method to initialize the client.
     21# For this example, Method 1 is active. Replace "YOUR_API_KEY_HERE" with your actual key.
     22
     23# Method 1: Initialize the client with direct API key
     24print("Method 1: Initialize with direct API key")
     25api_key = os.environ.get("USPTO_API_KEY", "YOUR_API_KEY_HERE")
     26if api_key == "YOUR_API_KEY_HERE":
     27    raise ValueError(
     28        "WARNING: API key is not set. Please replace 'YOUR_API_KEY_HERE' or set USPTO_API_KEY environment variable."
     29    )
     30client = PTABTrialsClient(api_key=api_key)
     31
     32# Method 2: Initialize the client with USPTOConfig (alternative)
     33# print("\nMethod 2: Initialize with USPTOConfig")
     34# config_obj = USPTOConfig(
     35#     api_key="YOUR_API_KEY_HERE",  # Replace with your actual API key
     36#     ptab_base_url="https://api.uspto.gov",  # Optional, uses default if not set
     37# )
     38# client = PTABTrialsClient(config=config_obj)
     39
     40# Method 3: Initialize the client with environment variables (recommended for production)
     41# print("\nMethod 3: Initialize with environment variables")
     42# # Ensure USPTO_API_KEY is set in your environment
     43# try:
     44#     config_from_env = USPTOConfig.from_env()
     45#     client = PTABTrialsClient(config=config_from_env)
     46# except ValueError as e:
     47#     print(f"Error initializing from environment: {e}")
     48#     print("Please ensure USPTO_API_KEY environment variable is set.")
     49
     50print("\nBeginning PTAB Trials API requests with configured client:")
     51
     52# =============================================================================
     53# 1. Search Trial Proceedings
     54# =============================================================================
     55
     56print("\n" + "=" * 80)
     57print("1. Searching for IPR trial proceedings")
     58print("=" * 80)
     59
     60try:
     61    # Search for IPR proceedings filed in 2023
     62    response = client.search_proceedings(
     63        trial_type_code_q="IPR",
     64        petition_filing_date_from_q="2023-01-01",
     65        petition_filing_date_to_q="2023-12-31",
     66        limit=5,
     67    )
     68
     69    print(f"\nFound {response.count} IPR proceedings filed in 2023")
     70    print(f"Displaying first {len(response.patent_trial_proceeding_data_bag)} results:")
     71
     72    for proceeding in response.patent_trial_proceeding_data_bag:
     73        print(f"\n  Trial Number: {proceeding.trial_number}")
     74
     75        if proceeding.trial_meta_data:
     76            meta = proceeding.trial_meta_data
     77            print(f"  Trial Type: {meta.trial_type_code}")
     78            print(f"  Status: {meta.trial_status_category}")
     79            print(f"  Filing Date: {meta.petition_filing_date}")
     80
     81        if proceeding.patent_owner_data:
     82            print(f"  Patent Owner: {proceeding.patent_owner_data.patent_owner_name}")
     83            print(f"  Patent Number: {proceeding.patent_owner_data.patent_number}")
     84
     85        if proceeding.regular_petitioner_data:
     86            print(
     87                f"  Petitioner: {proceeding.regular_petitioner_data.real_party_in_interest_name}"
     88            )
     89
     90except Exception as e:
     91    print(f"Error searching proceedings: {e}")
     92
     93# =============================================================================
     94# 2. Search Trial Documents
     95# =============================================================================
     96
     97print("\n" + "=" * 80)
     98print("2. Searching for trial documents")
     99print("=" * 80)
    100
    101try:
    102    # Search for documents in a specific trial
    103    # Using the new convenience parameters for petitioner and patent owner
    104    response = client.search_documents(
    105        trial_number_q="IPR2023-00001",
    106        document_category_q="Paper",
    107        petitioner_real_party_in_interest_name_q="*",  # Any petitioner
    108        patent_owner_name_q="*",  # Any patent owner
    109        limit=5,
    110    )
    111
    112    print(f"\nFound {response.count} documents")
    113    print(f"Displaying first {len(response.patent_trial_document_data_bag)} results:")
    114
    115    for item in response.patent_trial_document_data_bag:
    116        print(f"\n  Trial Number: {item.trial_number}")
    117
    118        if item.document_data:
    119            doc = item.document_data
    120            print(f"  Document Type: {doc.document_type_description_text}")
    121            print(f"  Filing Date: {doc.document_filing_date}")
    122            print(f"  Document Category: {doc.document_category}")
    123
    124            if doc.download_uri:
    125                print(f"  Download URL: {doc.download_uri}")
    126
    127except Exception as e:
    128    print(f"Error searching documents: {e}")
    129
    130# =============================================================================
    131# 3. Search Trial Decisions with New Convenience Parameters
    132# =============================================================================
    133
    134print("\n" + "=" * 80)
    135print("3. Searching for trial decisions with new parameters")
    136print("=" * 80)
    137
    138try:
    139    # Using all the new convenience parameters
    140    response = client.search_decisions(
    141        trial_type_code_q="IPR",
    142        decision_type_category_q="Final Written Decision",
    143        patent_owner_name_q="*",
    144        trial_status_category_q="Terminated",
    145        decision_date_from_q="2023-01-01",
    146        limit=5,
    147    )
    148
    149    print(f"\nFound {response.count} Final Written Decisions in IPR proceedings")
    150    print(f"Displaying first {len(response.patent_trial_document_data_bag)} results:")
    151
    152    for item in response.patent_trial_document_data_bag:
    153        print(f"\n  Trial Number: {item.trial_number}")
    154
    155        if item.trial_meta_data:
    156            print(f"  Trial Type: {item.trial_meta_data.trial_type_code}")
    157            print(f"  Status: {item.trial_meta_data.trial_status_category}")
    158
    159        if item.decision_data:
    160            decision = item.decision_data
    161            print(f"  Decision Type: {decision.decision_type_category}")
    162            print(f"  Decision Date: {decision.decision_issue_date}")
    163
    164except Exception as e:
    165    print(f"Error searching decisions: {e}")
    166
    167# =============================================================================
    168# 4. Pagination Example
    169# =============================================================================
    170
    171print("\n" + "=" * 80)
    172print("4. Paginating through proceedings")
    173print("=" * 80)
    174
    175try:
    176    print("\nIterating through first 10 IPR proceedings from 2024...")
    177    count = 0
    178    for proceeding in client.paginate_proceedings(
    179        trial_type_code_q="IPR",
    180        petition_filing_date_from_q="2024-01-01",
    181        limit=5,  # Fetch 5 per page
    182    ):
    183        count += 1
    184        print(f"{count}. {proceeding.trial_number}")
    185
    186        if count >= 10:  # Stop after 10 results for this example
    187            break
    188
    189    print(f"\nDisplayed {count} proceedings using pagination")
    190
    191except Exception as e:
    192    print(f"Error paginating proceedings: {e}")
    193
    194# =============================================================================
    195# 5. Advanced Query with Additional Parameters
    196# =============================================================================
    197
    198print("\n" + "=" * 80)
    199print("5. Advanced search with additional query parameters")
    200print("=" * 80)
    201
    202try:
    203    # Search using additional_query_params for custom filters
    204    response = client.search_proceedings(
    205        trial_type_code_q="PGR",
    206        trial_status_category_q="Instituted",
    207        sort="petitionFilingDate desc",
    208        fields="trialNumber,lastModifiedDateTime",
    209        limit=3,
    210    )
    211
    212    print(f"\nFound {response.count} Instituted PGR proceedings")
    213    print(f"Displaying first {len(response.patent_trial_proceeding_data_bag)} results:")
    214
    215    for proceeding in response.patent_trial_proceeding_data_bag:
    216        print(f"\n  Trial Number: {proceeding.trial_number}")
    217        print(f"  Last Modified: {proceeding.last_modified_date_time}")
    218
    219except Exception as e:
    220    print(f"Error with advanced search: {e}")
    221
    222# =============================================================================
    223# 6. Error Handling Example
    224# =============================================================================
    225
    226print("\n" + "=" * 80)
    227print("6. Error handling demonstration")
    228print("=" * 80)
    229
    230try:
    231    # Attempt a search that might fail (invalid date format)
    232    print("\nAttempting search with potentially invalid parameters...")
    233    response = client.search_proceedings(
    234        trial_number_q="INVALID-TRIAL-NUMBER",
    235        limit=1,
    236    )
    237
    238    if response.count == 0:
    239        print("No results found for the given search criteria")
    240    else:
    241        print(f"Found {response.count} results")
    242
    243except Exception as e:
    244    print(f"Expected error occurred: {type(e).__name__}: {e}")
    245
    246print("\n" + "=" * 80)
    247print("PTAB Trials API example completed successfully!")
    248print("=" * 80)