datamule 1.1.6__py3-none-any.whl → 1.1.8__py3-none-any.whl

datamule/sec/submissions/eftsquery.py

@@ -42,6 +42,67 @@ class EFTSQuery:
             await self.session.close()
             self.session = None
 
+    async def search_name(self, name):
+        """
+        Search for companies by name using the EFTS name search endpoint.
+        
+        Parameters:
+        name (str): Company name to search for
+        
+        Returns:
+        list: List of dictionaries containing company information (entity, id, tickers if available)
+        """
+        if not self.session:
+            raise RuntimeError("No active session. This method must be called within an async context.")
+            
+        url = f"{self.base_url}?keysTyped={name}"
+        
+        if not self.quiet:
+            print(f"Searching for company: {name}")
+            
+        async with self.limiter:
+            try:
+                async with self.session.get(url) as response:
+                    if response.status == 429:
+                        raise RetryException(url)
+                    response.raise_for_status()
+                    content = await response.read()
+                    await self.rate_monitor.add_request(len(content))
+                    data = await response.json()
+                    
+                    if 'hits' in data and 'hits' in data['hits']:
+                        hits = data['hits']['hits']
+                        results = []
+                        
+                        for hit in hits:
+                            source = hit.get('_source', {})
+                            result = {
+                                'entity': source.get('entity', ''),
+                                'id': hit.get('_id', ''),
+                                'tickers': source.get('tickers', '')
+                            }
+                            results.append(result)
+                        
+                        if not self.quiet and results:
+                            # Create a compact display of results
+                            display_results = [f"{r['entity']} [{r['id']}]" for r in results]
+                            print(f"Name matches: {', '.join(display_results[:5])}")
+                            if len(results) > 5:
+                                print(f"...and {len(results) - 5} more matches")
+                        
+                        return results
+                    return []
+            except aiohttp.ClientResponseError as e:
+                if e.status == 429:
+                    raise RetryException(url)
+                if not self.quiet:
+                    print(f"Error searching for company: {str(e)}")
+                return []
+            except Exception as e:
+                if not self.quiet:
+                    print(f"Error searching for company: {str(e)}")
+                return []
+
     def _get_form_exclusions(self, form):
         """Dynamically generate form exclusions based on patterns"""
         # Skip already negated forms
@@ -55,7 +116,7 @@ class EFTSQuery:
         # No exclusions for amendment forms
         return []
 
-    def _prepare_params(self, cik=None, submission_type=None, filing_date=None):
+    def _prepare_params(self, cik=None, submission_type=None, filing_date=None, location=None):
         params = {}
         
         # Handle CIK
@@ -111,6 +172,10 @@ class EFTSQuery:
             params['startdt'] = "2001-01-01"
             params['enddt'] = datetime.now().strftime('%Y-%m-%d')
             
+        # Handle location filtering
+        if location:
+            params['filter_location'] = location
+            
         return params
 
     def _get_query_description(self, params):
@@ -125,6 +190,9 @@ class EFTSQuery:
         if 'startdt' in params and 'enddt' in params:
             parts.append(f"dates={params['startdt']} to {params['enddt']}")
             
+        if 'filter_location' in params:
+            parts.append(f"location={params['filter_location']}")
+            
         return ", ".join(parts)
 
     async def _fetch_json(self, url):
@@ -413,12 +481,26 @@ class EFTSQuery:
         for params, from_val, size_val, callback in self.pending_page_requests:
             await self.fetch_queue.put((params, from_val, size_val, callback))
 
-    async def query(self, cik=None, submission_type=None, filing_date=None, callback=None):
-        params = self._prepare_params(cik, submission_type, filing_date)
-        all_hits = []
+    async def query(self, cik=None, submission_type=None, filing_date=None, location=None, callback=None, name=None):
+        """
+        Query SEC filings using the EFTS API.
+        
+        Parameters:
+        cik (str or list): Central Index Key(s) for the company
+        submission_type (str or list): Filing form type(s) to filter by
+        filing_date (str, tuple, or list): Date or date range to filter by
+        location (str): Location code to filter by (e.g., 'CA' for California)
+        callback (function): Async callback function to process results as they arrive
+        name (str): Company name to search for (alternative to providing CIK)
         
-        # Check if this is a primary documents query
-        self.was_primary_docs_query = '-0' in params.get('forms', '').split(',')
+        Returns:
+        list: List of filing documents matching the query criteria
+        """
+        # If both CIK and name are provided, raise an error
+        if cik is not None and name is not None:
+            raise ValueError("Please provide either 'name' or 'cik', not both")
+            
+        all_hits = []
         
         # Collector callback to gather all hits
         async def collect_hits(hits):
@@ -427,6 +509,25 @@ class EFTSQuery:
                 await callback(hits)
                 
         async with self as client:
+            # If name is provided, search for matching companies inside the context manager
+            if name is not None:
+                company_results = await self.search_name(name)
+                if not company_results:
+                    if not self.quiet:
+                        print(f"No companies found matching: {name}")
+                    return []
+                    
+                # Use the first (best) match's CIK
+                cik = company_results[0]['id']
+                if not self.quiet:
+                    print(f"Using CIK {cik} for {company_results[0]['entity']}")
+            
+            # Now prepare parameters with the CIK (either provided directly or from name search)
+            params = self._prepare_params(cik, submission_type, filing_date, location)
+            
+            # Check if this is a primary documents query
+            self.was_primary_docs_query = '-0' in params.get('forms', '').split(',')
+            
             # Reset state for new query
             self.total_results_to_fetch = 0
             self.pending_page_requests = []
@@ -506,12 +607,32 @@ class EFTSQuery:
                 print(f"\n--- Query complete: {len(all_hits):,} submissions retrieved ---")
             return all_hits
 
-def query_efts(cik=None, submission_type=None, filing_date=None, requests_per_second=5.0, callback=None, quiet=False):
+def query_efts(cik=None, submission_type=None, filing_date=None, location=None, requests_per_second=5.0, callback=None, quiet=False, name=None):
     """
     Convenience function to run a query without managing the async context.
+    
+    Parameters:
+    cik (str or list): Central Index Key(s) for the company
+    submission_type (str or list): Filing form type(s) to filter by
+    filing_date (str, tuple, or list): Date or date range to filter by
+    location (str): Location code to filter by (e.g., 'CA' for California)
+    requests_per_second (float): Maximum requests per second to make to the SEC API
+    callback (function): Async callback function to process results as they arrive
+    quiet (bool): Whether to suppress progress output
+    name (str): Company name to search for (alternative to providing CIK)
+    
+    Returns:
+    list: List of filing documents matching the query criteria
+    
+    Example:
+    To search by company name:
+        results = query_efts(name="Tesla", submission_type="10-K")
+        
+    To search by CIK:
+        results = query_efts(cik="1318605", submission_type="10-K")
     """
     async def run_query():
         query = EFTSQuery(requests_per_second=requests_per_second, quiet=quiet)
-        return await query.query(cik, submission_type, filing_date, callback)
+        return await query.query(cik, submission_type, filing_date, location, callback, name)
     
     return asyncio.run(run_query())

datamule/sec/submissions/monitor.py

@@ -20,12 +20,16 @@ async def _process_efts_hits(hits, collected_accession_numbers, data_callback=No
             submission_type = source.get('form')
             ciks = source.get('ciks', [])
             ciks = [str(int(cik)) for cik in ciks]
+
+            filing_date = source.get('file_date')
                 
             # Create standardized filing record
             filing = {
                 'accession_number': accession_number,
                 'submission_type': submission_type,
-                'ciks': ciks
+                'ciks': ciks,
+                'filing_date': filing_date,
+
             }
             
             processed_hits.append(filing)

datamule/sec/submissions/streamer.py

@@ -21,8 +21,8 @@ def fix_filing_url(url):
     return url
 
 class Streamer(EFTSQuery):
-    def __init__(self, requests_per_second=5.0, document_callback=None, accession_numbers=None):
-        super().__init__(requests_per_second=requests_per_second)
+    def __init__(self, requests_per_second=5.0, document_callback=None, accession_numbers=None, quiet=False):
+        super().__init__(requests_per_second=requests_per_second, quiet=quiet)
         self.document_callback = document_callback
         self.document_queue = asyncio.Queue()
         self.download_in_progress = asyncio.Event()
@@ -57,12 +57,14 @@ class Streamer(EFTSQuery):
                             await callback(hits)
                     self.fetch_queue.task_done()
                 except Exception as e:
-                    print(f"\nError fetching {url}: {str(e)}")
+                    if not self.quiet:
+                        print(f"\nError fetching {url}: {str(e)}")
                     self.fetch_queue.task_done()
             except asyncio.CancelledError:
                 break
             except Exception as e:
-                print(f"\nWorker error: {str(e)}")
+                if not self.quiet:
+                    print(f"\nWorker error: {str(e)}")
                 self.fetch_queue.task_done()
 
     def _construct_submission_url(self, hit):
@@ -85,7 +87,8 @@ class Streamer(EFTSQuery):
             
             return url, cik, accno_w_dash
         except (KeyError, IndexError) as e:
-            print(f"Error constructing URL for hit: {hit}. Error: {str(e)}")
+            if not self.quiet:
+                print(f"Error constructing URL for hit: {hit}. Error: {str(e)}")
             return None, None, None
 
     async def _document_download_worker(self):
@@ -115,13 +118,15 @@ class Streamer(EFTSQuery):
                             
                     self.document_queue.task_done()
                 except Exception as e:
-                    print(f"\nError streaming document {doc_url}: {str(e)}")
+                    if not self.quiet:
+                        print(f"\nError streaming document {doc_url}: {str(e)}")
                     self.document_queue.task_done()
                     
             except asyncio.CancelledError:
                 break
             except Exception as e:
-                print(f"\nDocument worker error: {str(e)}")
+                if not self.quiet:
+                    print(f"\nDocument worker error: {str(e)}")
                 self.document_queue.task_done()
 
     async def document_download_callback(self, hits):
@@ -133,7 +138,7 @@ class Streamer(EFTSQuery):
         self.download_in_progress.set()
         
         # Create progress bar for documents if not exists
-        if not self.document_pbar:
+        if not self.document_pbar and not self.quiet:
             self.document_pbar = tqdm(total=0, desc="Streaming submissions")
         
         # Queue up the documents for download
@@ -141,7 +146,8 @@ class Streamer(EFTSQuery):
             doc_url, cik, accno = self._construct_submission_url(hit)
             if doc_url:
                 # Update document progress bar total
-                self.document_pbar.total += 1
+                if self.document_pbar:
+                    self.document_pbar.total += 1
                 self.total_documents += 1
                 
                 # Add to download queue
@@ -159,8 +165,20 @@ class Streamer(EFTSQuery):
         # Signal that document download is complete
         self.download_in_progress.clear()
 
-    async def stream(self, cik=None, submission_type=None, filing_date=None):
-        """Main method to stream EFTS results and download documents"""
+    async def stream(self, cik=None, submission_type=None, filing_date=None, location=None, name=None):
+        """
+        Main method to stream EFTS results and download documents
+        
+        Parameters:
+        cik (str or list): Central Index Key(s) for the company
+        submission_type (str or list): Filing form type(s) to filter by
+        filing_date (str, tuple, or list): Date or date range to filter by
+        location (str): Location code to filter by (e.g., 'CA' for California)
+        name (str): Company name to search for (alternative to providing CIK)
+        
+        Returns:
+        list: List of all EFTS hits processed
+        """
         # Create document worker tasks
         self.document_workers = [
             asyncio.create_task(self._document_download_worker()) 
@@ -173,11 +191,12 @@ class Streamer(EFTSQuery):
         self.skipped_documents = 0
         
         # Run the main query with our document download callback
-        results = await self.query(cik, submission_type, filing_date, self.document_download_callback)
+        results = await self.query(cik, submission_type, filing_date, location, self.document_download_callback, name)
         
         # Make sure all document downloads are complete
         if self.download_in_progress.is_set():
-            print("Waiting for remaining document downloads to complete...")
+            if not self.quiet:
+                print("Waiting for remaining document downloads to complete...")
             await self.document_queue.join()
         
         # Clean up document workers
@@ -190,14 +209,17 @@ class Streamer(EFTSQuery):
         if self.document_pbar:
             self.document_pbar.close()
             self.document_pbar = None  # Set to None to prevent reuse
-            
-        print(f"\n--- Streaming complete: {len(results)} EFTS results processed ---")
-        if self.accession_numbers is not None:
-            print(f"--- {self.documents_processed} documents downloaded, {self.skipped_documents} skipped due to accession number filter ---")
+        
+        if not self.quiet:
+            print(f"\n--- Streaming complete: {len(results)} EFTS results processed ---")
+            if self.accession_numbers is not None:
+                print(f"--- {self.documents_processed} documents downloaded, {self.skipped_documents} skipped due to accession number filter ---")
+        
         return results
 
-def stream(cik=None, submission_type=None, filing_date=None, 
-                requests_per_second=5.0, document_callback=None, accession_numbers=None):
+def stream(cik=None, submission_type=None, filing_date=None, location=None, 
+           requests_per_second=5.0, document_callback=None, accession_numbers=None,
+           quiet=False, name=None):
     """
     Stream EFTS results and download documents into memory.
     
@@ -205,15 +227,28 @@ def stream(cik=None, submission_type=None, filing_date=None,
     - cik: CIK number(s) to query for
     - submission_type: Filing type(s) to query for
     - filing_date: Date or date range to query for
+    - location: Location code to filter by (e.g., 'CA' for California)
     - requests_per_second: Rate limit for SEC requests (combined EFTS and document downloads)
     - document_callback: Callback function that receives (hit, content, cik, accno, url)
     - accession_numbers: Optional list of accession numbers to filter by
+    - quiet: Whether to suppress progress output
+    - name: Company name to search for (alternative to providing CIK)
     
     Returns:
     - List of all EFTS hits processed
+    
+    Example:
+    To search by company name:
+        results = stream(name="Tesla", submission_type="10-K")
+        
+    To search by CIK:
+        results = stream(cik="1318605", submission_type="10-K")
+        
+    To search with location filter:
+        results = stream(name="Tesla", location="CA", submission_type="10-K")
     """
-
-    # check if acc no is empty list
+    
+    # Check if acc no is empty list
     if accession_numbers == []:
         raise ValueError("Applied filter resulted in empty accession numbers list")
     
@@ -221,8 +256,9 @@ def stream(cik=None, submission_type=None, filing_date=None,
         streamer = Streamer(
             requests_per_second=requests_per_second, 
             document_callback=document_callback,
-            accession_numbers=accession_numbers
+            accession_numbers=accession_numbers,
+            quiet=quiet
         )
-        return await streamer.stream(cik, submission_type, filing_date)
+        return await streamer.stream(cik, submission_type, filing_date, location, name)
     
     return asyncio.run(run_stream())

datamule/sec/submissions/textsearch.py

@@ -13,9 +13,9 @@ class TextSearchEFTSQuery(EFTSQuery):
         super().__init__(requests_per_second=requests_per_second, quiet=quiet)
         self.text_query = text_query
         
-    def _prepare_params(self, cik=None, submission_type=None, filing_date=None):
+    def _prepare_params(self, cik=None, submission_type=None, filing_date=None, location=None):
         # Get base parameters from parent class
-        params = super()._prepare_params(cik, submission_type, filing_date)
+        params = super()._prepare_params(cik, submission_type, filing_date, location)
         
         # Add text query parameter
         params['q'] = self.text_query
@@ -46,7 +46,8 @@ async def extract_accession_numbers(hits):
                 accession_numbers.append(acc_no)
     return accession_numbers
 
-def query(text_query, cik=None, submission_type=None, filing_date=None, requests_per_second=5.0, quiet=False):
+def query(text_query, cik=None, submission_type=None, filing_date=None, location=None, 
+          name=None, requests_per_second=5.0, quiet=False):
     """
     Search SEC filings for text and return the full search results.
     
@@ -63,6 +64,10 @@ def query(text_query, cik=None, submission_type=None, filing_date=None, requests
     filing_date : str, tuple, list, optional
         Date or date range to filter by. Can be a single date string ('YYYY-MM-DD'),
         a tuple of (start_date, end_date), or a list of dates.
+    location : str, optional
+        Location code to filter by (e.g., 'CA' for California).
+    name : str, optional
+        Company name to search for (alternative to providing CIK).
     requests_per_second : float, optional
         Maximum number of requests per second to make to the SEC API.
         Default is 5.0.
@@ -73,14 +78,23 @@ def query(text_query, cik=None, submission_type=None, filing_date=None, requests
     --------
     list
         Complete search results with all hit data.
+        
+    Examples:
+    ---------
+    # Search for 'climate risk' in Tesla's 10-K filings using company name
+    results = query('"climate risk"', name='Tesla', submission_type='10-K')
+    
+    # Search for 'pandemic' in California companies' filings
+    results = query('pandemic', location='CA', submission_type='8-K')
     """
     async def run_query():
         query = TextSearchEFTSQuery(text_query, requests_per_second=requests_per_second, quiet=quiet)
-        return await query.query(cik, submission_type, filing_date)
+        return await query.query(cik, submission_type, filing_date, location, None, name)
     
     return asyncio.run(run_query())
 
-def filter_text(text_query, cik=None, submission_type=None, filing_date=None, requests_per_second=5.0, quiet=False):
+def filter_text(text_query, cik=None, submission_type=None, filing_date=None, location=None, 
+                name=None, requests_per_second=5.0, quiet=False):
     """
     Search SEC filings for text and return matching accession numbers.
     
@@ -97,6 +111,10 @@ def filter_text(text_query, cik=None, submission_type=None, filing_date=None, re
     filing_date : str, tuple, list, optional
         Date or date range to filter by. Can be a single date string ('YYYY-MM-DD'),
         a tuple of (start_date, end_date), or a list of dates.
+    location : str, optional
+        Location code to filter by (e.g., 'CA' for California).
+    name : str, optional
+        Company name to search for (alternative to providing CIK).
     requests_per_second : float, optional
         Maximum number of requests per second to make to the SEC API.
         Default is 5.0.
@@ -107,6 +125,15 @@ def filter_text(text_query, cik=None, submission_type=None, filing_date=None, re
     --------
     list
         List of accession numbers (as strings) for filings that match the text query.
+        
+    Examples:
+    ---------
+    # Get accession numbers of Apple filings mentioning 'supply chain'
+    acc_numbers = filter_text('"supply chain"', name='Apple')
+    
+    # Use the accession numbers as a filter in another API
+    from .downloader import download
+    download(name='Apple', accession_numbers=acc_numbers)
     """
     async def run_query():
         query_obj = TextSearchEFTSQuery(text_query, requests_per_second=requests_per_second, quiet=quiet)
@@ -119,7 +146,7 @@ def filter_text(text_query, cik=None, submission_type=None, filing_date=None, re
             all_acc_nos.extend(acc_nos)
         
         # Run the query with our callback
-        await query_obj.query(cik, submission_type, filing_date, collect_acc_nos)
+        await query_obj.query(cik, submission_type, filing_date, location, collect_acc_nos, name)
         
         return all_acc_nos
     

datamule/seclibrary/bq.py

@@ -0,0 +1,191 @@
+import os
+import requests
+import json
+
+def get_information_table(
+    # Required parameters
+    table_type="INFORMATION_TABLE",
+    
+    # Optional filtering parameters
+    columns=None,
+    name_of_issuer=None,
+    title_of_class=None,
+    cusip=None,
+    value=None,
+    ssh_prnamt=None,
+    ssh_prnamt_type=None,
+    investment_discretion=None,
+    voting_authority_sole=None,
+    voting_authority_shared=None,
+    voting_authority_none=None,
+    reporting_owner_cik=None,
+    put_call=None,
+    other_manager=None,
+    figi=None,
+    accession=None,
+    filing_date=None,
+    
+    # API key handling
+    api_key=None,
+    
+    # Additional options
+    print_cost=True,
+    verbose=False
+):
+    """
+    Query the SEC BigQuery API for 13F-HR information table data.
+    
+    Parameters:
+    -----------
+    table_type : str
+        The table to query (default is "INFORMATION_TABLE")
+    columns : List[str], optional
+        Specific columns to return. If None, all columns are returned.
+    
+    # Filter parameters
+    name_of_issuer, title_of_class, etc. : Various filters that can be:
+        - str: Exact match
+        - List[str]: Match any in list
+        - tuple: (min, max) range for numeric/date fields
+    
+    api_key : str, optional
+        SEC BigQuery API key. If None, looks for DATAMULE_API_KEY env variable.
+    print_cost : bool
+        Whether to print the query cost information
+    verbose : bool
+        Whether to print additional information about the query
+        
+    Returns:
+    --------
+    List[Dict]
+        A list of dictionaries containing the query results
+        
+    Raises:
+    -------
+    ValueError
+        If API key is missing or invalid
+    Exception
+        For API errors or other issues
+    """
+    
+    # 1. Handle API key
+    if api_key is None:
+        api_key = os.getenv('DATAMULE_API_KEY')
+    
+    if not api_key:
+        raise ValueError("No API key found. Please set DATAMULE_API_KEY environment variable or provide api_key parameter")
+    
+    # 2. Build query parameters
+    params = {'table_type': table_type}
+    
+    # Add columns parameter if provided
+    if columns:
+        if isinstance(columns, list):
+            params['columns'] = ','.join(columns)
+        else:
+            params['columns'] = columns
+    
+    # Map Python parameter names to API parameter names
+    param_mapping = {
+        'name_of_issuer': 'nameOfIssuer',
+        'title_of_class': 'titleOfClass',
+        'cusip': 'cusip',
+        'value': 'value',
+        'ssh_prnamt': 'sshPrnamt',
+        'ssh_prnamt_type': 'sshPrnamtType',
+        'investment_discretion': 'investmentDiscretion',
+        'voting_authority_sole': 'votingAuthoritySole',
+        'voting_authority_shared': 'votingAuthorityShared',
+        'voting_authority_none': 'votingAuthorityNone',
+        'reporting_owner_cik': 'reportingOwnerCIK',
+        'put_call': 'putCall',
+        'other_manager': 'otherManager',
+        'figi': 'figi',
+        'accession': 'accession',
+        'filing_date': 'filingDate'
+    }
+    
+    # Process all possible filter parameters
+    for param_name, api_param_name in param_mapping.items():
+        value = locals()[param_name]
+        if value is not None:
+            # Handle different filter types
+            if isinstance(value, list):
+                # List filter
+                params[api_param_name] = f"[{','.join(str(v) for v in value)}]"
+            elif isinstance(value, tuple):
+                # Range filter
+                if len(value) == 2:
+                    min_val, max_val = value
+                    # Handle date range specially
+                    if param_name == 'filing_date':
+                        # Dates need to be in quotes within the parentheses
+                        if min_val is None:
+                            min_val = ''
+                        else:
+                            min_val = f"'{min_val}'"
+                        
+                        if max_val is None:
+                            max_val = ''
+                        else:
+                            max_val = f"'{max_val}'"
+                    
+                    range_str = f"({min_val},{max_val})"
+                    params[api_param_name] = range_str
+                else:
+                    raise ValueError(f"Range filter for {param_name} must be a tuple of (min, max)")
+            else:
+                # Exact match
+                params[api_param_name] = value
+    
+    # 3. Make the API request
+    BASE_URL = "https://sec-bq.jgfriedman99.workers.dev/"
+    
+    headers = {
+        'Authorization': f'Bearer {api_key}',
+        'Accept': 'application/json'
+    }
+    
+    if verbose:
+        print(f"Making request to {BASE_URL} with params: {params}")
+    
+    try:
+        response = requests.get(BASE_URL, params=params, headers=headers)
+        
+        # Check for HTTP errors
+        response.raise_for_status()
+        
+        # Parse response
+        result = response.json()
+        
+        # Check for API-level errors
+        if not result.get('success', False):
+            error_msg = result.get('error', 'Unknown API error')
+            raise Exception(f"API Error: {error_msg}")
+        
+        # Extract metadata for cost reporting
+        metadata = result.get('metadata', {})
+        
+        # 5. Print cost information if requested
+        if print_cost and 'billing' in metadata:
+            billing = metadata['billing']
+            query_info = metadata.get('query_info', {})
+            
+            print("\n=== Query Cost Information ===")
+            print(f"Bytes Processed: {query_info.get('bytes_processed', 0):,} bytes")
+            print(f"Data Processed: {billing.get('tb_processed', 0):.10f} TB")
+            print(f"Cost Rate: ${billing.get('cost_per_tb', 0):.2f}/TB")
+            print(f"Query Cost: ${billing.get('total_charge', 0):.6f}")
+            print(f"Remaining Balance: ${billing.get('remaining_balance', 0):.2f}")
+            print(f"Execution Time: {query_info.get('execution_time_ms', 0)} ms")
+            print(f"Cache Hit: {query_info.get('cache_hit', False)}")
+            print("==============================\n")
+        
+        # 6. Return data
+        return result.get('data', [])
+        
+    except requests.exceptions.RequestException as e:
+        if response.status_code == 401:
+            raise ValueError("Authentication failed: Invalid API key")
+        else:
+            raise Exception(f"Request failed: {str(e)}")