Developer APIs

Each BlockScript installation comes equipped with a powerful suite of APIs (Application Programming Interfaces). The APIs enable developers to integrate BlockScript with external systems.

Security Savvy

Access to the BlockScript API is protected by a randomly generated "API Key" which is 38-42 characters in length. Your API Key can be found in your BlockScript control panel. Failed attempts to access the API are rate limited. Rate limit exceeders are automatically prevented from accessing the API.

API Design

The BlockScript API is an HTTP based API. Interactions take place over standard HTTP using GET or POST requests. The API sends return values in XML format so that it is easy to parse and use. Errors return a "400 Bad Request" HTTP header as well.


The API is accessed from the BlockScript installation on your website. Specific methods are accessed by using the "action" query string parameter. For example, the simplest API request possible (to display the current version number) is:

http://www.example.com/blockscript/detector.php?blockscript=api&api_key=YOURAPIKEYHERE&action=version

Which results in:
<?xml version="1.0" encoding="UTF-8"?> <response>   <status>SUCCESS</status>   <msg>BlockScript v2.1295</msg> </response>

Lookup an IP Address

This API enables you to query BlockScript for information about an IP address. For each query, BlockScript will perform all relevant tests against the target IP address as per the preferences set in your BlockScript control panel. Please see our Example IP Lookup Script for PHP and our Example IP Lookup Script for Perl. A query to lookup an IP takes the form of:

http://www.example.com/blockscript/detector.php?blockscript=api&api_key=YOURAPIKEYHERE&action=test_ipv4&ip=10.11.12.13

Resulting in a hit:
<?xml version="1.0" encoding="UTF-8"?> <response>   <status>SUCCESS</status>   <queries_used>25</queries_used>   <queries_remaining>9975</queries_remaining>   <msg>IP banned</msg>   <ip>     <blocked>YES</blocked>     <option>hosting_provider_blacklist</option>     <reason>Hosting provider IP address (10.11.12.13) is blacklisted.</reason>     <country>US</country>   </ip> </response>

Resulting in a miss:
<?xml version="1.0" encoding="UTF-8"?> <response>   <status>SUCCESS</status>   <queries_used>25</queries_used>   <queries_remaining>9975</queries_remaining>   <msg>IP OK</msg>   <ip>     <blocked>NO</blocked>     <option></option>     <reason>Passed</reason>     <country>US</country>   </ip> </response>

Show Queries Remaining

BlockScript limits the number of queries that can be sent to the API in a 24 hour period. This API displays the total number of queries allowed by your license key and the total number of queries remaining in the current 24 hour period. A query to lookup an IP takes the form of:

http://www.example.com/blockscript/detector.php?blockscript=api&api_key=YOURAPIKEYHERE&action=queries

Add/Remove To/From Whitelist/Blacklist

This API enables you to programmatically:

• Add IP addresses and IP address ranges to the blacklist.
• Add IP addresses and IP address ranges to the whitelist.
• Remove IP addresses and IP address ranges from the blacklist.
• Remove IP addresses and IP address ranges from the whitelist.

These actions correspond to the following "action" parameters: blacklist_add, whitelist_add, blacklist_remove, whitelist_remove. Multiple IP addresses (up to 100) may be separated with a comma. IP address ranges may be specified in a variety of formats ("127.0.0.1", "127.0.0.0-127.0.0.15", "127.0.0.0/255.255.255.254", "127.0.0.0/23"). A request to add two entries to the blacklist takes the form of:

http://www.example.com/blockscript/detector.php?blockscript=api&api_key=YOURAPIKEYHERE&action=blacklist_add&ips=10.11.12.13,192.168.0.0/24

Which results in:
<?xml version="1.0" encoding="UTF-8"?> <response>   <status>SUCCESS</status>   <msg>Added to blacklist</msg> </response>

Transparent Mode

When BlockScript's Transparent Mode is enabled, no blocking will be performed, and alternatively, information about the user is provided by BlockScript within the $_SERVER global variable for use with other systems. The information provided by BlockScript is as follows:

$_SERVER['blockscript_blocked'] ("YES", "NO", or "ERROR")
$_SERVER['blockscript_country'] (user's country code)
$_SERVER['blockscript_option'] (name of option resulting in block)
$_SERVER['blockscript_reason'] (description of block)