The Whatoblock.com API has been discontinued. Threat intelligence is now available through the web dashboard and our subscription plans.
This API documentation is kept for reference only. The endpoints below are no longer available. Visit the pricing page to subscribe.
Search across all Whatoblock threat intelligence data from a single interface. No API key required.
Global Search is available at search.whatoblock.com. It searches four data sources simultaneously. A captcha verification is required before each new search. Once verified, you can paginate, sort, and filter results freely.
Global Search queries all four data sources and merges the results into a single view:
Scanners
Port scan activity
Botnets
C2 servers & malware
Open Data
Internet-wide scans
Heartbeat
Live threat signals
You can search by entering a value directly or by using prefix:value syntax for targeted searches.
These formats are recognized automatically without a prefix:
192.168.1.1
Searches all IP fields across all sources
d41d8cd98f00b204...
32 hex character hash — searches Botnet and Open Data
550e8400-e29b-41d4-...
Unique Botnet ID — searches Botnet source only
Use a prefix to search a specific field. Only data sources that support the field will be queried.
| Prefix | Description | Example |
|---|---|---|
ip: |
IPv4 address | ip:1.2.3.4 |
port: |
Port number (1–65535) | port:443 |
md5: |
MD5 hash | md5:d41d8cd9... |
country: |
Origin country (code or name) | country:US |
target: |
Targeted country (code or name) | target:US |
org: |
Organization name | org:Cloudflare |
service: |
Service name | service:ssh |
asn: |
AS Number | asn:AS13335 |
protocol: |
TCP or UDP | protocol:tcp |
ubid: |
Unique Botnet ID (UUID) | ubid:550e8400... |
Separate two or more prefixes with a space to combine them. All conditions must match (AND logic). Results are limited to data sources that support every prefix used.
port:53 protocol:udp
Matches Scanner and Open Data sources
ip:1.2.3.4 target:US
Find activity from a specific IP targeting the United States
country:CN target:JP org:Chinanet
Find Chinanet-originated activity from China targeting Japan
If no data source supports all the prefixes in your query, no results will be returned. For example, ubid:... port:443 will return nothing because ubid: is Botnet-only and port: does not apply to Botnet data.
After a search completes, you can refine your results using the controls on the results page:
Date (newest first) — most recent results firstDate (oldest first) — earliest results firstRelevance — best matches firstThe results page shows breakdowns by data type, top ports, countries, and organizations. Click any item to filter the results.
country: prefix searches both the origin and targeted country fields. Use target: to search only the targeted country.US) are automatically converted to full country names for matching.A real-time global visualization of threat activity. Watch live attack lines and threat events unfold on an interactive map.
The Threat Map is available at threatmap.whatoblock.com. It is completely free, requires no account, and works on any device.
The map ingests data from three threat intelligence sources. Each source is rendered with a distinct color:
Switch between two rendering modes from the settings panel:
The settings panel (top-left on desktop, hamburger menu on mobile) provides:
The stats panel (top-right) updates in real time with:
Total events and per-source breakdowns (Botnet, Scanner, Heartbeat) with a country count.
The five countries receiving the most attacks, ranked by event count with relative bar charts.
The five countries generating the most threat activity.
The news panel (bottom-left on desktop, swipe-up sheet on mobile) shows a scrollable feed of the latest threat events as they appear on the map, including origin, target, source type, and masked IP addresses.
192.168.xxx.xxx) for privacy.Access comprehensive threat intelligence through our RESTful API with flexible filtering, real-time data retrieval, and direct file downloads.
Base URL: https://whatoblock.com/apiv3/ Authentication: ?apiKey=7eae00f2-d740-4756-9658-ca2d62b05c73
API keys must be valid UUIDv4 format: 7eae00f2-d740-4756-9658-ca2d62b05c73
Check your account status, token balance, and API costs. This endpoint does not consume any tokens.
GET https://whatoblock.com/apiv3/status?apiKey=7eae00f2-d740-4756-9658-ca2d62b05c73
{
"success": true,
"timestamp": "January 15, 2024, 10:30:00 AM",
"account": {
"username": "your_username",
"available_tokens": 87585.8,
"used_tokens": 12414.2,
"total_tokens_ever": 100000,
"last_api_reset": "January 1, 2024, 12:00:00 AM",
"api_key_reset_tries": 0
},
"token_costs": {
"HEARTBEAT_API": 0.1,
"BOTNET_API": 1,
"SCANNER_API": 1,
"OPENDATA_API": 10
}
}
All API endpoints use token-based billing. See the Token-Based Billing section for detailed pricing information, including cost per record and minimum costs for each endpoint.
The Heartbeat, Botnet, and Scanner endpoints support flexible response formats:
format=json - Returns JSON responseformat=text - Returns plain text, one IP per lineformat=csv - Returns CSV format, one IP per lineformat=xml - Returns XML format for system integrationsinfo=false (default) - Returns IPs onlyinfo=true - Includes metadata (tokens charged, filters, etc.)# comments/apiv3/heartbeat?apiKey=KEY&time=24h&format=json - JSON with IPs only (info=false)/apiv3/heartbeat?apiKey=KEY&time=24h&format=json&info=true - JSON with full metadata/apiv3/heartbeat?apiKey=KEY&time=24h&format=text - Plain text, IPs only/apiv3/heartbeat?apiKey=KEY&time=24h&format=text&info=true - Plain text with metadata comments/apiv3/heartbeat?apiKey=KEY&time=24h&format=csv - CSV format, one IP per line/apiv3/heartbeat?apiKey=KEY&time=24h&format=xml - XML format for system integrations/apiv3/heartbeat?apiKey=KEY&time=24h&format=xml&info=true - XML with full metadataAll endpoints support cost preview mode to preview costs and results without consuming tokens. Use cost=true:
Add &cost=true to any endpoint to preview the operation
{
"success": true,
"cost_preview": true,
"query_details": {
"endpoint": "/apiv3/heartbeat",
"records_found": 150,
"filters_applied": {
"time": "24h",
"country": "US"
},
"operation_type": "HEARTBEAT_API",
"response_format": "IP addresses only",
"pricing_info": {
"OpenProxy": "0.1 tokens per unique IP",
"Tor Exit Node": "0.1 tokens per unique IP",
"ResidentialProxy": "0.1 tokens per unique IP",
"DatacenterProxy": "0.1 tokens per unique IP",
"DDoS": "0.1 tokens per unique IP"
}
},
"account_impact": {
"current_balance": 1000.0,
"tokens_to_charge": 15,
"balance_after_query": 985,
"sufficient_balance": true
},
"timestamp": "January 15, 2024, 10:30:00 AM",
"note": "This is a cost preview query. No tokens have been charged and no data has been returned.",
"category_breakdown": {
"ResidentialProxy": {"count": 50, "cost": 5},
"OpenProxy": {"count": 75, "cost": 7.5},
"DDoS": {"count": 25, "cost": 2.5}
}
}
Note: category_breakdown is only included for Heartbeat API responses.
time parameter is required for Heartbeat, Scanner, and Botnet endpoints. Not required for Open Data endpoint.md5 filter together with service, protocol, or port filters. Choose ONE filtering mode:
md5 alone to get a specific file by hash (e.g., ?md5=9f3a7b2c4d1e8a0b6c5f2d9e3a1b0c4d)service, protocol, and port together (e.g., ?service=DNS&protocol=tcp&port=53)service, protocol, and port are all required together:
?service=DNS&protocol=tcp&port=53?service=DNS&protocol=tcp (missing port)?service=DNS&port=53 (missing protocol)?protocol=tcp&port=53 (missing service)The API returns standardized error responses with appropriate HTTP status codes:
{
"success": false,
"error": "API key is required. Please include ?apiKey=YOUR_API_KEY in your request.",
"note": "Make sure to include the ? before apiKey= in your URL"
}
// Invalid API key format
{
"success": false,
"error": "Invalid API key format. API key must be a valid UUIDv4.",
"format": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (where x is any hexadecimal digit and y is one of 8, 9, A, or B)"
}
// Invalid API key
{
"success": false,
"error": "Invalid API key. Please check your API key and try again."
}
// Preliminary validation (before processing)
{
"success": false,
"error": "Insufficient token balance for this operation.",
"required_operation": "HEARTBEAT_API",
"cost_per_record": "0.1 tokens per record",
"available_tokens": 5.2,
"message": "Please top up your account to use this endpoint."
}
// Final validation (after processing)
{
"success": false,
"error": "Insufficient token balance. Please top up your account.",
"required_tokens": 125.5,
"available_tokens": 100.0
}
{
"success": false,
"error": "Your account has been banned. Please contact support at [email protected] for assistance."
}
// Missing time filter
{
"success": false,
"error": "Missing required parameter",
"message": "The \"time\" parameter is required.",
"required_parameters": ["time", "format"],
"optional_parameters": ["country", "category", "asn", "ip", "hideUnknown", "info", "cost"],
"supported_time_values": ["24h", "30d"],
"examples": {
"minimal": "/apiv3/heartbeat?apiKey=KEY&time=24h&format=json",
"with_filters": "/apiv3/heartbeat?apiKey=KEY&time=24h&format=json&country=US&category=OpenProxy,DatacenterProxy,DDoS",
"text_format": "/apiv3/heartbeat?apiKey=KEY&time=24h&format=text&info=false"
}
}
// Invalid filter parameter
{
"success": false,
"error": "Invalid filter parameter",
"message": "Invalid country code: \"XX\". Please use valid 2-letter ISO country codes (e.g., US, DE, GB).",
"required_parameters": ["time", "format"],
"optional_parameters": ["country", "category", "asn", "ip", "hideUnknown", "info", "cost"],
"example": "/apiv3/heartbeat?apiKey=KEY&time=24h&format=json&country=US"
}
// Unknown query parameters
{
"success": false,
"error": "Invalid query parameters",
"message": "Unknown parameter provided by the user.",
"required_parameters": ["time", "format"],
"optional_parameters": ["country", "category", "asn", "ip", "hideUnknown", "info", "cost"],
"example": "/apiv3/heartbeat?apiKey=KEY&time=24h&format=json&country=US"
}
{
"success": false,
"error": "Data is being generated.",
"message": "Data not yet available. Please wait a few seconds and retry."
}
// Maintenance mode
{
"success": false,
"error": "System is under maintenance. Please check back later.",
"maintenance": true
}
{
"success": false,
"error": "Failed to retrieve heartbeat data. Please try again later."
}
The Scanner API provides access to IP addresses from network scanning activity data.
Access IP addresses from network scanning activity through the API v3 endpoint:
GET https://whatoblock.com/apiv3/scanner?apiKey=7eae00f2-d740-4756-9658-ca2d62b05c73&time=24h&hideBots=true
The Scanner API supports four response formats: JSON, plain text, CSV, and XML. The format parameter is required. Use format=json, format=text, format=csv, or format=xml to control the output format. Use info=true to include metadata in the response.
JSON response with IPs only when info=false (minimal format - just the array):
["203.0.113.45", "198.51.100.10"]
JSON response with full metadata when info=true:
{
"success": true,
"ips": ["203.0.113.45", "198.51.100.10"],
"records": 2,
"tokens_charged": 2,
"filters_applied": {
"time": "24h",
"hideBots": "true"
}
}
JSON response with IPs only when info=false (minimal format - just the array):
["203.0.113.45", "198.51.100.10"]
Plain text response with one IP per line - perfect for importing into other programs:
203.0.113.45 198.51.100.10
Plain text response with metadata as comments:
# Records: 2 # Tokens Charged: 2 # Filters: time=24h, hideBots=true 203.0.113.45 198.51.100.10
CSV response with one IP per line - perfect for importing into spreadsheet applications:
203.0.113.45 198.51.100.10
XML response for easy integration with enterprise systems and SIEM platforms:
<?xml version="1.0" encoding="UTF-8"?>
<scanner>
<ips>
<ip>203.0.113.45</ip>
<ip>198.51.100.10</ip>
</ips>
</scanner>
XML response with full metadata:
<?xml version="1.0" encoding="UTF-8"?>
<scanner>
<success>true</success>
<records>2</records>
<tokens_charged>2</tokens_charged>
<ips>
<ip>203.0.113.45</ip>
<ip>198.51.100.10</ip>
</ips>
</scanner>
When no data matches your filters, the API returns an empty array:
{
"success": true,
"ips": [],
"records": 0,
"tokens_charged": 0,
"filters_applied": {
"time": "24h",
"country": "US"
},
"message": "No data found for your query.",
"suggestion": "Try adjusting your filters (time period, country, protocol, ASN) to get results. You can use time=30d for a broader range, or remove some filters to see more data.",
"supported_filters": {
"time": ["24h", "30d"],
"country": "Use 2-letter codes like US, DE, GB",
"protocol": "Use exact protocol names like TCP, UDP",
"asn": "Use format like AS1234 or AS1234,AS5678"
}
}
Use cost=true to preview costs without consuming tokens:
GET https://whatoblock.com/apiv3/scanner?apiKey=KEY&time=24h&country=US&cost=true
{
"success": true,
"cost_preview": true,
"query_details": {
"endpoint": "/apiv3/scanner",
"records_found": 150,
"filters_applied": {
"time": "24h",
"country": "US"
},
"operation_type": "SCANNER_API",
"response_format": "IP addresses only"
},
"account_impact": {
"current_balance": 1000.0,
"tokens_to_charge": 150,
"balance_after_query": 850.0,
"sufficient_balance": true
},
"timestamp": "January 15, 2024, 10:30:00 AM",
"note": "This is a cost preview query. No tokens have been charged and no data has been returned."
}
time: Required - 24h, 30dcountry: 2-letter ISO codes (US, UK, DE, etc.) - comma-separated for multipleprotocol: tcp or udp (case-insensitive)asn: AS1234 format (comma-separated for multiple, e.g., AS1234,AS5678)hideUnknown: true/false (exclude unknown locations)hideBots: Scanner endpoint only - true/false (exclude automated bot traffic)format: Required - json, text, csv, or xml - controls response formatinfo: true/false (default: false) - include metadata in responsecost: true/false (cost preview mode - no tokens charged)See the Token-Based Billing section for detailed pricing information.
{
"success": false,
"error": "Missing required parameter",
"message": "The \"time\" parameter is required.",
"required_parameters": ["time", "format"],
"optional_parameters": ["country", "protocol", "asn", "hideUnknown", "hideBots", "info", "cost"],
"supported_time_values": ["24h", "30d"],
"examples": {
"minimal": "/apiv3/scanner?apiKey=KEY&time=24h&format=json",
"with_filters": "/apiv3/scanner?apiKey=KEY&time=24h&format=json&protocol=tcp&country=US",
"text_format": "/apiv3/scanner?apiKey=KEY&time=24h&format=text&info=false"
}
}
{
"success": false,
"error": "Invalid filter parameter",
"message": "Invalid country code: \"XYZ\". Please use valid 2-letter ISO country codes (e.g., US, DE, GB).",
"example": "/apiv3/scanner?apiKey=KEY&time=24h&country=US"
}
{
"success": false,
"error": "Invalid query parameters",
"message": "Unknown parameter provided by the user.",
"required_parameters": ["time", "format"],
"optional_parameters": ["country", "protocol", "asn", "hideUnknown", "hideBots", "info", "cost"],
"example": "/apiv3/scanner?apiKey=KEY&time=24h&format=json&country=US"
}
{
"success": false,
"error": "Insufficient token balance. Please top up your account.",
"required_tokens": 150,
"available_tokens": 50
}
/apiv3/scanner?apiKey=KEY&time=24h&hideBots=true&hideUnknown=true
Get IP addresses of human-operated scanners to block in your firewall
/apiv3/scanner?apiKey=KEY&time=24h&country=CN
Track scanning activity from China over 24 hours
/apiv3/scanner?apiKey=KEY&time=30d&asn=AS13335,AS15169
Monitor scanning activity from major cloud providers (Cloudflare, Google)
/apiv3/scanner?apiKey=KEY&time=24h&format=text
Get IP addresses in plain text format for easy import into firewall rules
/apiv3/scanner?apiKey=KEY&time=24h&format=text&info=true
Get IP addresses in text format with metadata comments for documentation
The Heartbeat API provides access to IP threat intelligence data, categorizing IP addresses by threat type.
Access Heartbeat data through the API v3 endpoint:
GET https://whatoblock.com/apiv3/heartbeat?apiKey=7eae00f2-d740-4756-9658-ca2d62b05c73&time=24h&format=json&country=US
The Heartbeat API supports four response formats: JSON, plain text, CSV, and XML. The format parameter is required. Use format=json, format=text, format=csv, or format=xml to control the output format. Use info=true to include metadata in the response.
JSON response with IPs only when info=false (minimal format - just the array):
["185.220.101.45", "198.51.100.23"]
JSON response with full metadata when info=true:
{
"success": true,
"ips": ["185.220.101.45", "198.51.100.23"],
"records": 2,
"tokens_charged": 0.2,
"category_breakdown": {
"ResidentialProxy": {"count": 1, "cost": 0.1},
"OpenProxy": {"count": 1, "cost": 0.1}
},
"filters_applied": {
"time": "24h",
"country": "US"
}
}
JSON response with IPs only when info=false (minimal format - just the array):
["185.220.101.45", "198.51.100.23"]
Plain text response with one IP per line - perfect for importing into firewall rules:
185.220.101.45 198.51.100.23
Plain text response with metadata as comments:
# Records: 2 # Tokens Charged: 0.2 # Filters: time=24h, country=US # Category Breakdown: # ResidentialProxy: 1 (0.1 tokens) # OpenProxy: 1 (0.1 tokens) 185.220.101.45 198.51.100.23
CSV response with one IP per line - perfect for importing into spreadsheet applications:
185.220.101.45 198.51.100.23
XML response for easy integration with enterprise systems and SIEM platforms:
<?xml version="1.0" encoding="UTF-8"?>
<heartbeat>
<ips>
<ip>185.220.101.45</ip>
<ip>198.51.100.23</ip>
</ips>
</heartbeat>
XML response with full metadata including category breakdown:
<?xml version="1.0" encoding="UTF-8"?>
<heartbeat>
<success>true</success>
<records>2</records>
<tokens_charged>0.2</tokens_charged>
<category_breakdown>
<ResidentialProxy><count>1</count><cost>0.1</cost></ResidentialProxy>
<OpenProxy><count>1</count><cost>0.1</cost></OpenProxy>
</category_breakdown>
<ips>
<ip>185.220.101.45</ip>
<ip>198.51.100.23</ip>
</ips>
</heartbeat>
time: Required - 24h, 30dcountry: 2-letter ISO codes (US, UK, DE, etc.) - comma-separated for multipleasn: AS1234 format (comma-separated for multiple, e.g., AS1234,AS5678)ip: Heartbeat endpoint only - Specific IP or prefix (e.g., 185.220.101 or 185.220.101.45)category: Heartbeat endpoint only - OpenProxy, Tor Exit Node, ResidentialProxy, DatacenterProxy, DDoS (comma-separated; Tor_Exit_Node, Residential_Proxy, Datacenter_Proxy, and ddos aliases are also accepted)hideUnknown: true/false (exclude unknown locations)format: Required - json, text, csv, or xml - controls response formatinfo: true/false (default: false) - include metadata in responsecost: true/false (cost preview mode - no tokens charged)See the Token-Based Billing section for detailed pricing information.
/apiv3/heartbeat?apiKey=KEY&time=24h&format=json&category=OpenProxy,ResidentialProxy,DatacenterProxy,DDoS
Get OpenProxy, Residential Proxy, Datacenter Proxy, and DDoS-related IP addresses to block in your firewall
/apiv3/heartbeat?apiKey=KEY&time=30d&format=json&country=RU,CN,IR
Track threat activity from specific countries over 30 days
/apiv3/heartbeat?apiKey=KEY&time=30d&format=json&ip=185.220.101.45
Check if a specific IP address appears in threat intelligence data
/apiv3/heartbeat?apiKey=KEY&time=30d&format=json&asn=AS13335,AS15169
Filter threats originating from specific autonomous systems
/apiv3/heartbeat?apiKey=KEY&time=24h&format=text
Get IP addresses in plain text format for easy import into firewall rules
/apiv3/heartbeat?apiKey=KEY&time=24h&format=text&info=true
Get IP addresses in text format with metadata comments for documentation
The Botnet API provides access to Command & Control (C2) server intelligence and downloadable malware samples for security research.
Access Botnet data through the API v3 endpoint:
GET https://whatoblock.com/apiv3/botnet?apiKey=7eae00f2-d740-4756-9658-ca2d62b05c73&time=24h&downloadableOnly=true
The Botnet API supports four response formats: JSON, plain text, CSV, and XML. The format parameter is required. Use format=json, format=text, format=csv, or format=xml to control the output format. Use info=true to include metadata in the response.
JSON response with C2 IPs only when info=false (minimal format - just the array):
["185.220.101.45", "198.51.100.23"]
JSON response with full metadata when info=true:
{
"success": true,
"c2_ips": ["185.220.101.45", "198.51.100.23"],
"records": 2,
"tokens_charged": 2,
"filters_applied": {
"time": "24h",
"downloadableOnly": "true"
}
}
JSON response with IPs only when info=false (minimal format - just the array):
["185.220.101.45", "198.51.100.23"]
Plain text response with one IP per line - perfect for importing into firewall rules:
185.220.101.45 198.51.100.23
Plain text response with metadata as comments:
# Records: 2 # Tokens Charged: 2 # Filters: time=24h, downloadableOnly=true 185.220.101.45 198.51.100.23
CSV response with one IP per line - perfect for importing into spreadsheet applications:
185.220.101.45 198.51.100.23
XML response for easy integration with enterprise systems and SIEM platforms:
<?xml version="1.0" encoding="UTF-8"?>
<botnet>
<c2_ips>
<ip>185.220.101.45</ip>
<ip>198.51.100.23</ip>
</c2_ips>
</botnet>
XML response with full metadata:
<?xml version="1.0" encoding="UTF-8"?>
<botnet>
<success>true</success>
<records>2</records>
<tokens_charged>2</tokens_charged>
<c2_ips>
<ip>185.220.101.45</ip>
<ip>198.51.100.23</ip>
</c2_ips>
</botnet>
time: Required - 24h, 30dcountry: 2-letter ISO codes (US, UK, DE, etc.) - comma-separated for multipleasn: AS1234 format (comma-separated for multiple, e.g., AS1234,AS5678)downloadableOnly: Botnet endpoint only - true/false (only samples with downloadable malware files)hideUnknown: true/false (exclude unknown locations)format: Required - json, text, csv, or xml - controls response formatinfo: true/false (default: false) - include metadata in responsecost: true/false (cost preview mode - no tokens charged)Download malware samples directly from botnet C2 servers. Each downloadable sample is identified by a unique botnet ID.
Botnet IDs are obtained from the web interface. Visit the Botnet page to view C2 servers and their associated botnet ID values. Only botnets with downloadable samples will have available files. Botnet IDs must contain only alphanumeric characters, hyphens, and underscores.
GET https://whatoblock.com/apiv3/botnet/download/YOUR_BOTNET_ID?apiKey=YOUR_API_KEY
The Botnet download endpoint returns a binary ZIP file containing the malware sample. The filename is automatically constructed as {botnet_id}-binaries.zip. Tokens are consumed after successful download (5 tokens per file).
Content-Type: application/zip Content-Disposition: attachment; filename="YOUR_BOTNET_ID-binaries.zip" Content-Length: [file_size] [Binary ZIP file content]
{
"success": false,
"error": "Botnet ID is required"
}
{
"success": false,
"error": "Download failed - authentication error"
}
{
"success": false,
"error": "Payload file not found for ID: YOUR_BOTNET_ID",
"id": "YOUR_BOTNET_ID"
}
{
"success": false,
"error": "Insufficient token balance. Please top up your account.",
"required_tokens": 5,
"available_tokens": 2.5
}
{
"success": false,
"error": "Download failed - connection timeout. Please try again later."
}
{
"success": false,
"error": "Download failed: [error message]"
}
Malware samples are live and dangerous! Only download if you have proper isolation, analysis tools, and security expertise. These files can damage systems and compromise networks.
See the Token-Based Billing section for detailed pricing information, including costs for C2 IP addresses and malware sample downloads.
/apiv3/botnet?apiKey=KEY&time=24h&country=US
Get C2 server IP addresses from the US to block in your firewall
/apiv3/botnet?apiKey=KEY&time=30d&downloadableOnly=true
Get botnet IDs with downloadable malware samples for analysis
/apiv3/botnet/download/YOUR_BOTNET_ID?apiKey=KEY
Download a specific malware sample for security research (requires proper isolation)
/apiv3/botnet?apiKey=KEY&time=24h&format=text
Get C2 server IP addresses in plain text format for easy import into firewall rules
/apiv3/botnet?apiKey=KEY&time=24h&format=text&info=true
Get C2 server IP addresses in text format with metadata comments for documentation
The Open Data API provides access to binary file downloads from scanner result files. Returns binary file streams, not IP addresses or JSON.
Access Open Data files through the API v3 endpoint:
GET https://whatoblock.com/apiv3/opendata?apiKey=YOUR_API_KEY&service=DNS&protocol=tcp&port=53
The Open Data API returns direct file downloads (binary stream) for single file matches:
Content-Type: application/octet-stream Content-Disposition: attachment; filename="dns-tcp-53-20240101.tar.gz" X-API-Success: File download initiated successfully X-API-Message: Downloading file: dns-tcp-53-20240101.tar.gz X-API-Tokens-Charged: 10 X-API-Filter-Type: service+protocol+port X-API-Service-Protocol: DNS (tcp:53) [Binary file content]
Open Data API always returns a single file as a binary stream. The API returns the most recent file for the specified service, protocol, and port combination, or the file matching the MD5 hash. Multiple files are not supported - each query returns exactly one file. One active download per user at a time.
Open Data API supports two mutually exclusive filtering modes. You must choose ONE mode per request:
md5 filter alone to get a specific file by hashservice, protocol, and port together (all three required)md5 with service/protocol/port filtersservice: Required - DNS, NTP, SSH, HTTPS_ALT, etc. (both hyphens and underscores accepted)protocol: Required - Must be tcp or udp (case-insensitive)port: Required - Port number (1-65535)md5: Required - 32 hexadecimal characters (0-9, a-f, A-F)md5 filter alone (no other filters allowed)Complete list of supported services organized by protocol:
DNS
53
FTP
21
HTTP
80
HTTP_ALT
8080
(HTTP-ALT)
HTTPS
443
HTTPS_ALT
8443
(HTTPS-ALT)
IMAP
143
IMAPS
993
MSSQL
1433
MYSQL
3306
POP3
110
POP3S
995
POSTGRESQL
5432
RDP
3389
SMB
445
SMTP
25, 587
SMTPS
465
SSH
22
TELNET
23
ARD
3283
CHARGEN
19
DNS
53
IPMI
623
LDAP
389
MDNS
5353
MEMCACHED
11211
MSSQL
1434
NAT_PMP
5351
(NAT-PMP)
NETBIOS_NS
137
(NETBIOS-NS)
NTP
123
QOTD
17
RIP
520
SIP
5060
SSDP
1900
STUN
3478
UBIQUITI
10001
WSD
3702
Services with hyphens in their names (HTTP-ALT, HTTPS-ALT, NAT-PMP, NETBIOS-NS) must use underscores in the API query parameter (HTTP_ALT, HTTPS_ALT, NAT_PMP, NETBIOS_NS).
Example: Use service=HTTP_ALT to access HTTP-ALT service data.
{
"success": false,
"error": "Invalid filter combination",
"message": "You cannot use MD5 filter together with service/protocol/port filters. Choose ONE filtering mode.",
"provided_filters": {
"md5": "9f3a7b2c4d1e8a0b6c5f2d9e3a1b0c4d",
"conflicting_filters": ["service", "protocol", "port"]
},
"supported_modes": {
"md5_mode": "Use MD5 hash only: ?md5=hash",
"service_mode": "Use service+protocol+port: ?service=DNS&protocol=tcp&port=53"
},
"examples": {
"md5_single": "/apiv3/opendata?apiKey=KEY&md5=9f3a7b2c4d1e8a0b6c5f2d9e3a1b0c4d",
"service_mode": "/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53"
}
}
{
"success": false,
"error": "Missing required filter parameter",
"message": "You must specify service, protocol, and port parameters.",
"supported_filters": {
"service": "Service name (e.g., DNS, NTP, SSH, HTTPS_ALT)",
"protocol": "Required: tcp or udp (case-insensitive)",
"port": "Required: port number (1-65535)"
},
"examples": {
"dns_tcp": "/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53",
"ntp_udp": "/apiv3/opendata?apiKey=KEY&service=NTP&protocol=udp&port=123"
},
"alternative": {
"md5_mode": "Or use MD5 hash: /apiv3/opendata?apiKey=KEY&md5=9f3a7b2c4d1e8a0b6c5f2d9e3a1b0c4d"
}
}
{
"success": false,
"error": "Missing required protocol parameter",
"message": "You must specify a protocol parameter when using service filter.",
"provided_service": "DNS",
"supported_protocols": ["tcp", "udp"],
"examples": {
"with_tcp": "/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53",
"with_udp": "/apiv3/opendata?apiKey=KEY&service=NTP&protocol=udp&port=123"
}
}
{
"success": false,
"error": "Invalid protocol parameter",
"message": "Protocol must be either \"tcp\" or \"udp\" (case-insensitive).",
"provided_protocol": "http",
"supported_protocols": ["tcp", "udp"],
"examples": {
"tcp_example": "/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53",
"udp_example": "/apiv3/opendata?apiKey=KEY&service=NTP&protocol=udp&port=123"
}
}
{
"success": false,
"error": "Invalid MD5 hash format",
"message": "MD5 hash must be exactly 32 hexadecimal characters.",
"provided_hash": "abc123",
"valid_format": "32 hexadecimal characters (0-9, a-f, A-F)",
"examples": {
"valid": "/apiv3/opendata?apiKey=KEY&md5=a1b2c3d4e5f6789012345678901234ab"
}
}
{
"success": false,
"error": "You already have a download in progress. Please wait for it to complete."
}
{
"success": true,
"files": [],
"records": 0,
"tokens_charged": 0,
"filters_applied": {
"service": "DNS",
"protocol": "tcp",
"port": 53
},
"message": "No data found for your service+protocol+port query.",
"suggestion": "No files found for service \"DNS\" with protocol \"tcp\" on port 53. Verify the combination is correct.",
"supported_filters": {
"service": "Service name (e.g., DNS, NTP, SSH, HTTPS_ALT)",
"protocol": "Required: tcp or udp (case-insensitive)",
"port": "Required: port number (1-65535)",
"md5": "Single MD5 hash - alternative to service mode"
},
"examples": {
"dns_tcp": "/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53",
"ntp_udp": "/apiv3/opendata?apiKey=KEY&service=NTP&protocol=udp&port=123",
"https_alt": "/apiv3/opendata?apiKey=KEY&service=HTTPS_ALT&protocol=tcp&port=8443",
"md5_hash": "/apiv3/opendata?apiKey=KEY&md5=9f3a7b2c4d1e8a0b6c5f2d9e3a1b0c4d"
}
}
See the Token-Based Billing section for detailed pricing information.
/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53
Download the most recent DNS TCP port 53 scanning result file
/apiv3/opendata?apiKey=KEY&md5=a1b2c3d4e5f6789012345678901234ab
Download a specific file by its MD5 hash
/apiv3/opendata?apiKey=KEY&service=NTP&protocol=udp&port=123
Download the most recent NTP UDP port 123 scanning result file
Pay-per-use access to API endpoints with transparent pricing based on data volume.
/apiv3/heartbeat
0.1 token
/apiv3/scanner
1.0 token
/apiv3/botnet
1.0 token
/apiv3/botnet/download/:id
5.0 tokens
/apiv3/opendata
10.0 tokens
/apiv3/status
Free
/apiv3/status endpoint
cost=true parameter