1"""Example usage of the pyUSPTO module for Final Petition Decisions.
2
3This example demonstrates how to use the FinalPetitionDecisionsClient to interact with the
4USPTO Final Petition Decisions API. It shows how to search for petition decisions, retrieve
5specific decisions by ID, download decision data, and access detailed information about
6petitions and their associated documents.
7"""
8
9import json
10import os
11
12from pyUSPTO.clients import FinalPetitionDecisionsClient
13from pyUSPTO.models.petition_decisions import PetitionDecisionDownloadResponse
14
15# --- Initialization ---
16# Initialize the client with direct API key
17print("Initialize with direct API key")
18api_key = os.environ.get("USPTO_API_KEY", "YOUR_API_KEY_HERE")
19if api_key == "YOUR_API_KEY_HERE":
20 raise ValueError(
21 "WARNING: API key is not set. Please replace 'YOUR_API_KEY_HERE' or set USPTO_API_KEY environment variable."
22 )
23client = FinalPetitionDecisionsClient(api_key=api_key)
24
25DEST_PATH = "./download-example"
26
27print("\nBeginning API requests with configured client:")
28
29# Basic search for petition decisions
30try:
31 print("\n" + "=" * 60)
32 print("Example 1: Basic Search for Petition Decisions")
33 print("=" * 60)
34
35 response = client.search_decisions(limit=5)
36 print(f"Found {response.count} total petition decisions.")
37 print(f"Displaying first {len(response.petition_decision_data_bag)} decisions:")
38
39 for decision in response.petition_decision_data_bag:
40 print(f"\n Decision ID: {decision.petition_decision_record_identifier}")
41 print(f" Application Number: {decision.application_number_text}")
42 print(f" Decision Type: {decision.decision_type_code}")
43 print(f" Decision Date: {decision.decision_date}")
44 print(f" Technology Center: {decision.technology_center}")
45
46 if decision.first_applicant_name:
47 print(f" Applicant: {decision.first_applicant_name}")
48
49 if decision.patent_number:
50 print(f" Patent Number: {decision.patent_number}")
51
52 if decision.inventor_bag:
53 print(f" Inventors ({len(decision.inventor_bag)}):")
54 for inventor in decision.inventor_bag[:3]: # Show first 3
55 print(f" - {inventor}")
56
57 if decision.document_bag:
58 print(f" Documents: {len(decision.document_bag)}")
59
60 print("-" * 40)
61
62except Exception as e:
63 print(f"Error in basic search: {e}")
64
65# Search with query parameter
66try:
67 print("\n" + "=" * 60)
68 print("Example 2: Search with Custom Query")
69 print("=" * 60)
70
71 # Search for decisions mentioning specific terms
72 response = client.search_decisions(query="decisionTypeCode:C", limit=3)
73 print(f"Found {response.count} decisions with C type.")
74 print(f"Showing {len(response.petition_decision_data_bag)} results:")
75
76 for decision in response.petition_decision_data_bag:
77 print(
78 f" - {decision.petition_decision_record_identifier}: {decision.decision_type_code}"
79 )
80
81except Exception as e:
82 print(f"Error searching with query: {e}")
83
84# Search using convenience parameters
85try:
86 print("\n" + "=" * 60)
87 print("Example 3: Search Using Convenience Parameters")
88 print("=" * 60)
89
90 # Search by application number (if you have a specific one)
91 print("\nSearching by date range...")
92 response = client.search_decisions(
93 decision_date_from_q="2023-01-01", decision_date_to_q="2023-12-31", limit=5
94 )
95 print(f"Found {response.count} decisions from 2023.")
96
97 # Search by technology center
98 print("\nSearching by technology center...")
99 response = client.search_decisions(technology_center_q="2600", limit=3)
100 print(f"Found {response.count} decisions from Technology Center 2600.")
101
102except Exception as e:
103 print(f"Error with convenience parameters: {e}")
104
105# Get a specific decision by ID
106try:
107 print("\n" + "=" * 60)
108 print("Example 4: Get Specific Decision by ID")
109 print("=" * 60)
110
111 # First, get a decision ID from search results
112 response = client.search_decisions(limit=1)
113 if response.count > 0:
114 decision_id = response.petition_decision_data_bag[
115 0
116 ].petition_decision_record_identifier
117 if decision_id:
118 print(f"Retrieving decision: {decision_id}")
119 decision = client.get_decision_by_id(decision_id)
120 if decision:
121 print("\nDecision Details:")
122 print(f" ID: {decision.petition_decision_record_identifier}")
123 print(f" Application: {decision.application_number_text}")
124 print(f" Patent: {decision.patent_number}")
125 print(f" Decision Type: {decision.decision_type_code}")
126 print(f" Decision Date: {decision.decision_date}")
127 print(f" Technology Center: {decision.technology_center}")
128 print(f" Group Art Unit: {decision.group_art_unit_number}")
129
130 if decision.rule_bag:
131 print(f"\n Rules Cited ({len(decision.rule_bag)}):")
132 for rule in decision.rule_bag[:5]: # Show first 5
133 print(f" - {rule}")
134
135 if decision.statute_bag:
136 print(f"\n Statutes Cited ({len(decision.statute_bag)}):")
137 for statute in decision.statute_bag[:5]: # Show first 5
138 print(f" - {statute}")
139
140 if decision.document_bag:
141 print(f"\n Associated Documents ({len(decision.document_bag)}):")
142 for doc in decision.document_bag[:3]: # Show first 3
143 print(f" - Doc ID: {doc.document_identifier}")
144 print(f" Date: {doc.official_date}")
145 print(f" Doc. Code: {doc.document_code_description_text}")
146 print(f" Direction: {doc.direction_category}")
147 if doc.download_option_bag:
148 print(
149 f" Download Options: {len(doc.download_option_bag)}"
150 )
151 for mime in doc.download_option_bag:
152 print(f" >Mime Type: {mime.mime_type_identifier}")
153 print(f" >>Pages: {mime.page_total_quantity}")
154
155except Exception as e:
156 print(f"Error retrieving decision by ID: {e}")
157
158# Download petition decisions data
159try:
160 print("\n" + "=" * 60)
161 print("Example 5: Download Petition Decisions Data")
162 print("=" * 60)
163
164 # Download as JSON (returns response object)
165 print("\nDownloading decisions as JSON...")
166 response = client.download_decisions(
167 format="json", decision_date_from_q="2023-01-01", limit=5, overwrite=True
168 )
169 if isinstance(response, PetitionDecisionDownloadResponse):
170 print(
171 f"Downloaded JSON with {len(response.petition_decision_data)} decision records"
172 )
173 print(json.dumps(response.to_dict(), indent=2))
174
175 # Download as CSV (automatically saves to file)
176 print("\nDownloading decisions as CSV...")
177 csv_path = client.download_decisions(
178 format="csv",
179 decision_date_from_q="2023-01-01",
180 limit=10,
181 destination=DEST_PATH,
182 overwrite=True,
183 )
184 print(f"Downloaded CSV to: {csv_path}")
185
186except Exception as e:
187 print(f"Error downloading decisions: {e}")
188
189# Pagination example
190try:
191 print("\n" + "=" * 60)
192 print("Example 6: Paginating Through Results")
193 print("=" * 60)
194
195 page_size = 10
196 max_pages = 3 # Limit to 3 pages for example
197
198 print(
199 f"Paginating through results ({page_size} per page, max {max_pages} pages)..."
200 )
201
202 total_decisions = 0
203
204 for decision in client.paginate_decisions(
205 limit=page_size, query="decisionDate:[2023-01-01 TO 2023-12-31]"
206 ):
207 total_decisions += 1
208
209 if total_decisions % page_size == 0:
210 print(f" Retrieved {total_decisions} decisions so far...")
211
212 if total_decisions >= (page_size * max_pages):
213 print(f" (Stopping after {max_pages} pages for example)")
214 break
215
216 print(f"\nTotal decisions retrieved: {total_decisions}")
217
218except Exception as e:
219 print(f"Error during pagination: {e}")
220
221# Download a petition document
222try:
223 print("\n" + "=" * 60)
224 print("Example 7: Download Petition Decision Document")
225 print("=" * 60)
226
227 # Find a decision with downloadable documents
228 response = client.search_decisions(limit=20)
229
230 document_found = False
231 for decision in response.petition_decision_data_bag:
232 d = client.get_decision_by_id(
233 decision.petition_decision_record_identifier, include_documents=True
234 )
235 print(f"Getting docs for patent: {d.invention_title} with id: {d.petition_decision_record_identifier}") # type: ignore
236 if d and d.document_bag:
237 for doc in d.document_bag:
238 if doc.download_option_bag and len(doc.download_option_bag) > 0:
239 download_option = doc.download_option_bag[0]
240
241 print("Found downloadable document:")
242 print(f" Document ID: {doc.document_identifier}")
243 print(f" MIME Type: {download_option.mime_type_identifier}")
244 print(f" Pages: {download_option.page_total_quantity}")
245 print(f" URL: {download_option.download_url}")
246
247 print("\nDownloading document...")
248 file_path = client.download_petition_document(
249 download_option=download_option,
250 destination=DEST_PATH,
251 )
252 print(f"Downloaded to: {file_path}")
253
254 document_found = True
255 break
256
257 if document_found:
258 break
259
260 if not document_found:
261 print("No downloadable documents found in the first 20 results")
262
263except Exception as e:
264 print(f"Error downloading document: {e}")
265
266# Advanced search example
267try:
268 print("\n" + "=" * 60)
269 print("Example 8: Advanced Search with Multiple Criteria")
270 print("=" * 60)
271
272 # Search with multiple parameters
273 response = client.search_decisions(
274 application_number_q="16*", # Applications starting with 16
275 decision_date_from_q="2020-01-01",
276 technology_center_q="2600",
277 limit=10,
278 )
279
280 print("Search criteria:")
281 print(" - Application numbers starting with '16'")
282 print(" - Decision date from 2020-01-01")
283 print(" - Technology Center 2600")
284 print(f"\nFound {response.count} matching decisions")
285
286 if response.count > 0:
287 print(f"Showing first {len(response.petition_decision_data_bag)} results:")
288 for decision in response.petition_decision_data_bag:
289 print(
290 f" - App: {decision.application_number_text}, "
291 f"TC: {decision.technology_center}, "
292 f"Date: {decision.decision_date}"
293 )
294
295except Exception as e:
296 print(f"Error in advanced search: {e}")
297
298print("\n" + "=" * 60)
299print("Examples completed!")
300print("=" * 60)