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
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_path=DEST_PATH,
182 )
183 print(f"Downloaded CSV to: {csv_path}")
184
185except Exception as e:
186 print(f"Error downloading decisions: {e}")
187
188# Pagination example
189try:
190 print("\n" + "=" * 60)
191 print("Example 6: Paginating Through Results")
192 print("=" * 60)
193
194 page_size = 10
195 max_pages = 3 # Limit to 3 pages for example
196
197 print(
198 f"Paginating through results ({page_size} per page, max {max_pages} pages)..."
199 )
200
201 total_decisions = 0
202
203 for decision in client.paginate_decisions(
204 limit=page_size, query="decisionDate:[2023-01-01 TO 2023-12-31]"
205 ):
206 total_decisions += 1
207
208 if total_decisions % page_size == 0:
209 print(f" Retrieved {total_decisions} decisions so far...")
210
211 if total_decisions >= (page_size * max_pages):
212 print(f" (Stopping after {max_pages} pages for example)")
213 break
214
215 print(f"\nTotal decisions retrieved: {total_decisions}")
216
217except Exception as e:
218 print(f"Error during pagination: {e}")
219
220# Download a petition document
221try:
222 print("\n" + "=" * 60)
223 print("Example 7: Download Petition Decision Document")
224 print("=" * 60)
225
226 # Find a decision with downloadable documents
227 response = client.search_decisions(limit=20)
228
229 document_found = False
230 for decision in response.petition_decision_data_bag:
231 d = client.get_decision_by_id(
232 decision.petition_decision_record_identifier, include_documents=True
233 )
234 print(f"Getting docs for patent: {d.invention_title} with id: {d.petition_decision_record_identifier}") # type: ignore
235 if d and d.document_bag:
236 for doc in d.document_bag:
237 if doc.download_option_bag and len(doc.download_option_bag) > 0:
238 download_option = doc.download_option_bag[0]
239
240 print("Found downloadable document:")
241 print(f" Document ID: {doc.document_identifier}")
242 print(f" MIME Type: {download_option.mime_type_identifier}")
243 print(f" Pages: {download_option.page_total_quantity}")
244 print(f" URL: {download_option.download_url}")
245
246 print("\nDownloading document...")
247 file_path = client.download_petition_document(
248 download_option, destination_path=DEST_PATH
249 )
250 print(f"Downloaded to: {file_path}")
251
252 document_found = True
253 break
254
255 if document_found:
256 break
257
258 if not document_found:
259 print("No downloadable documents found in the first 20 results")
260
261except Exception as e:
262 print(f"Error downloading document: {e}")
263
264# Advanced search example
265try:
266 print("\n" + "=" * 60)
267 print("Example 8: Advanced Search with Multiple Criteria")
268 print("=" * 60)
269
270 # Search with multiple parameters
271 response = client.search_decisions(
272 application_number_q="16*", # Applications starting with 16
273 decision_date_from_q="2020-01-01",
274 technology_center_q="2600",
275 limit=10,
276 )
277
278 print("Search criteria:")
279 print(" - Application numbers starting with '16'")
280 print(" - Decision date from 2020-01-01")
281 print(" - Technology Center 2600")
282 print(f"\nFound {response.count} matching decisions")
283
284 if response.count > 0:
285 print(f"Showing first {len(response.petition_decision_data_bag)} results:")
286 for decision in response.petition_decision_data_bag:
287 print(
288 f" - App: {decision.application_number_text}, "
289 f"TC: {decision.technology_center}, "
290 f"Date: {decision.decision_date}"
291 )
292
293except Exception as e:
294 print(f"Error in advanced search: {e}")
295
296print("\n" + "=" * 60)
297print("Examples completed!")
298print("=" * 60)