.svg){kind=icon}
The Whisper API provides two distinct response formats to suit different application needs: a standard JSON format for complete, batched data, and a real-time Server-Sent Events (SSE) format for streaming.
Choosing the right format depends on whether you need all the data at once or prefer to receive it incrementally for lower latency.
Standard JSON (Batch Mode)
This is the default response format. When you make a request, the API gathers all the available information and returns it in a single, complete JSON object.
When to use it: This mode is perfect for most standard use cases where you need the full dataset before you can begin processing it.
How to request it: To explicitly request this format, include the Accept header in your request.
Accept: application/json
Example cURL Request
curl -X GET "https://api.whisper.security/intelligence/v1/ip/8.8.8.8" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"
Real-time Streaming (Server-Sent Events)
For low-latency applications or processing large datasets, the API supports streaming via Server-Sent Events (SSE). This method keeps the HTTP connection open and pushes data to you in small chunks as it becomes available.
When to use it: Streaming is ideal for populating live user interfaces, powering real-time dashboards, or when you want to start processing data immediately without waiting for the full response.
How to request it: Set the Accept header to text/event-stream.
Accept: text/event-stream
The IP Intelligence and Domain Intelligence endpoints support streaming mode.
Event Structure
Each message sent from the server follows a simple format, including an event type and the data payload. For example, the IP Intelligence stream sends events like geolocation, relationships, ip_score, and routing.
Example: Streaming with Node.js/TypeScript
You can use a library like eventsource to easily connect to a streaming endpoint and listen for specific events.
import EventSource from 'eventsource';
const eventSource = new EventSource(
'https://api.whisper.security/intelligence/v1/domain/example.com',
{
headers: {
'Authorization': 'Bearer your-token-here',
'Accept': 'text/event-stream'
}
}
);
eventSource.addEventListener('whois', (event) => {
const whoisData = JSON.parse(event.data);
console.log('WHOIS data received:', whoisData);
});
eventSource.addEventListener('dns', (event) => {
const dnsData = JSON.parse(event.data);
console.log('DNS records received:', dnsData);
});
eventSource.addEventListener('complete', (event) => {
console.log('All data received, closing connection.');
eventSource.close();
});
Example: Streaming with Python
In Python, you can iterate over the response from a streaming request to process each line of data as it arrives.
import requests
import json
def stream_ip_intelligence(ip_address):
url = f"https://api.whisper.security/intelligence/v1/ip/{ip_address}"
headers_stream = {
"Authorization": f"Bearer YOUR_API_KEY",
"Accept": "text/event-stream"
}
response = requests.get(url, headers=headers_stream, stream=True)
for line in response.iter_lines():
if line:
line = line.decode('utf-8')
if line.startswith('data:'):
data = json.loads(line[5:])
print(f"Received Event Data: {json.dumps(data, indent=2)}")
# Usage
stream_ip_intelligence("8.8.8.8")