Use client-side query validation to catch syntax errors before making API calls
The Newscatcher Python SDK includes client-side query validation that mirrors
the API’s server-side validation. This feature helps you catch invalid query
syntax before making API calls.
Use the validate_query() method to check query syntax before you make API
calls:
Basic query validation
Copy
Ask AI
from newscatcher import NewscatcherApiclient = NewscatcherApi(api_key="YOUR_API_KEY")# Validate a query before using itis_valid, error_message = client.validate_query("machine learning")if is_valid: print("Query is valid!")else: print(f"Invalid query: {error_message}")
The method returns a tuple:
is_valid (bool): Whether the query passes validation
error_message (str): Detailed error description if validation fails, or
empty string if valid
"machine[learning]" # Square brackets not allowed"AI/ML" # Forward slashes not allowed"machine:learning" # Colons not allowed"data^science" # Caret symbols not allowed
The API automatically inserts AND operators between standalone terms, which can
create validation conflicts with mixed operator levels.Problem
Common AND insertion conflicts
Copy
Ask AI
# ❌ This fails because of automatic AND insertion:"AI OR artificial intelligence"# Becomes: "AI OR artificial AND intelligence" (mixed operator levels)# ❌ Another example:"startup OR venture capital"# Becomes: "startup OR venture AND capital" (mixed operator levels)
Solutions
Fix AND insertion conflicts
Copy
Ask AI
# ✅ Fix by using exact phrase matching:"AI OR \"artificial intelligence\""# Stays as: "AI OR \"artificial intelligence\"" (same level)# ✅ Or use proper grouping:"startup OR (venture AND capital)"# Becomes: "startup OR (venture AND capital)" (properly grouped)
Always use double quotes for multi-word terms when combining with OR operators
to prevent automatic AND insertion conflicts.
For applications that process multiple queries (like LLM-generated queries), you
can validate them in bulk:
Hide Bulk validation code example
Bulk query validation
Copy
Ask AI
def validate_queries_bulk(client, queries): """Validate multiple queries and return results with details.""" results = [] for i, query in enumerate(queries): is_valid, error_message = client.validate_query(query) results.append({ 'index': i, 'query': query, 'is_valid': is_valid, 'error': error_message if not is_valid else None }) return results# Example usage with multiple queriesqueries = [ "machine learning", # Valid "AI OR artificial intelligence", # Invalid (mixed levels) "\"artificial intelligence\"", # Valid (exact phrase) "technology[invalid]", # Invalid (forbidden chars) "(python AND ML) OR (data AND science)" # Valid (proper grouping)]client = NewscatcherApi(api_key="YOUR_API_KEY")validation_results = validate_queries_bulk(client, queries)# Process resultsvalid_queries = [r['query'] for r in validation_results if r['is_valid']]invalid_queries = [r for r in validation_results if not r['is_valid']]print(f"Valid queries: {len(valid_queries)}")print(f"Invalid queries: {len(invalid_queries)}")# Show invalid queries with errorsfor result in invalid_queries: print(f"Query: {result['query']}") print(f"Error: {result['error']}\n")
This approach works well when you work with:
LLM-generated queries that may have syntax issues.
User input that needs validation before processing.
Batch processing scenarios where you want to filter valid queries first.
Bulk validation is especially valuable for production applications processing
thousands of queries, as it prevents costly API calls for invalid queries.
