API Documentation

The BotScout API was designed to be simple to understand and easy to use. It's easy to implement in virtually any application and requires only a small amount of code. The values returned by the BotScout API calls can come back as either simple pipe-delimited string or as an XML-formatted structure.

Querying The API

You send requests (queries) to the BotScout API by using a URL with attached parameters. The URL goes to the BotScout API code, is processed, and then returns a simple string of data that tells you what it found. There are five kinds of queries you can send to the API:

EMAIL - Check an email address: 
http://botscout.com/test/?mail=krasnhello@mail.ru

IP - Check an IP Address: 
http://botscout.com/test/?ip=84.16.230.111

NAME - Check the user name 'krasnhello'
http://botscout.com/test/?name=krasnhello

ALL - Check all of the above (check email, name, and IP for 'krasnhello')
http://botscout.com/test/?all=krasnhello

MULTI - Check all parameters at once: 
http://botscout.com/test/?multi&name=krasnhello&mail=krasnhello@mail.ru&ip=84.16.230.111

For most applications all you need to check is the email address- it's the single most reliable indicator of a bot.

The "ALL" test matches a single item against all fields in the database.

The "MULTI" matches three items (IP, Name, and Email) against all fields in the database. This test is both comprehensive and efficient and is often preferred over the "Check an email address" query. It provides the maximum amount of useful data returned for a single query.


Currently you can do 400 bot lookup tests from any IP per day. If you need more than that we suggest you get an API key (it's free). Using an API key allows you to make a much larger number of tests each day. To make requests using an API key, just append the key to the test request as shown below.

EMAIL - Check an email address: 
http://botscout.com/test/?mail=krasnhello@mail.ru&key=xxxxxxxx

IP - Check an IP Address: 
http://botscout.com/test/?ip=84.16.230.111&key=xxxxxxxx

NAME - Check a user name: 
http://botscout.com/test/?name=krasnhello&key=xxxxxxxx

ALL - Check all of the above: 
http://botscout.com/test/?all=krasnhello&key=xxxxxxxx

MULTI - Check all parameters at once: 
http://botscout.com/test/?multi&name=krasnhello&mail=krasnhello@mail.ru&ip=84.16.230.111&key=xxxxxxxx




API Error Handling

In the event of an API error or query limit, the API will return an exclamation mark (!) followed by a single space, and then the text of the error message. For example:

! Sorry, but that doesn't appear to be a valid API key.

Code that uses the API should always explicitly test the return value- do NOT assume that the absence of a 'Y' means an 'N' was returned. If your code tests for an exclamation mark as the first character and finds one, then it can expect an error message to follow. Error messages could (should) be processed further; for example, the error message could be emailed to an admin as an alert.



API Return Values (Standard Format)

Pipe-delimited data is used for the Standard Format returned data string because it's compact, simple, and easy to parse. The API normally returns three (3) pipe-delimited values, but a fourth value is returned if the 'ALL' query is used. For example, if you sent "http://botscout.com/test/?mail=krasnhello@mail.ru", a typical return string might look like this:

Y|MAIL|1

The 'Y' indicates a match was found, the 'MAIL' shows that you were testing an email address, and the '3' means that the tested item (the email address) was found 3 times in the database.


If you used the 'ALL' test and sent "http://botscout.com/test/?all=krasnhello@mail.ru", the return string might look like this:

Y|ALL|2|MAIL

The 'Y' indicates a match was found, the 'ALL' shows that you weren't explicitly specifying what kind of data you were sending, and the '3' means that the tested item was found 3 times in the database. The last item, 'MAIL' is the API's best guess at what kind of data item the API thinks you sent.

This last value can be used as a "sanity test" to make sure that the item was interpreted correctly. For example, if you're using 'ALL' to test a user name but the API thinks it's an email address, you may want to resend the data and force the API to check only user names by using a 'NAME' query. This kind of "false match" can occur because some bots will use an email address for the user name (and may use a different address for the actual email field).

Using the MULTI Query
When using the API in the Standard format with the 'multi' parameter the API will return a string which will look similar to this:

Y|MULTI|IP|3|MAIL|1|NAME|2

If any of the elements match then the first field will be a 'Y', followed by the test type indicator 'MULTI', and then each of the tested values are sent with a pipe followed by the number of matches for that item. The sample string above shows that a match was found, and that the IP matched three times, the email matched once, and the name matched twice.

If none of the items matched then first element returned as 'N' (but with the rest of the fields still present showing zero matches).

  1. The 'multi' parameter must be present to trigger the 'MULTI' type test
  2. Notice that there is no value after the 'multi' parameter in the GET string. Any value assigned to the 'multi' parameter will be ignored.
  3. There must be at least one (1) of the field items (name, ip, or email) present as a "name=value" pair. The system will ignore up to two (2) missing parameters, so you can (for example) send just the email, or the IP and an email, an IP and a name, etc etc.
  4. The order of the field items doesn't matter, but at least one (1) be present or the system will send back the following error: Missing or Malformed Data for MULTI test.

API Returned Data (Standard Format)
#DATA ITEMPOSSIBLE VALUESWHEN IS IT RETURNED?MEANING
1DATA MATCHED?'Y' or 'N'ALWAYSA 'Y' or 'N' indicating "yes" or "no" as to whether or not the data you sent matched anything in the database.
(In other words, is it a bot?)
2API TEST TYPE'MAIL', 'IP', 'NAME', or 'ALL'ALWAYSA string indicating the type of data you tested for.
3NUMBER OF MATCHES'1', '23', '475', etcALWAYSAn integer number indicating how many times the tested item was found in the database, for example, '5'.
4API EVALUATION'MAIL', 'IP', or 'NAME'OPTIONALThis value is only returned when using the 'ALL' query. It represents the API's "best guess" at what kind of data you sent (that is, an email address, an IP address, or a user name).




API Return Values (XML Format)

The returned data can also be sent back as XML by using the "format" parameter in the query as shown here:

http://botscout.com/test/?all=krasnhello@mail.ru&format=xml

When XML is requested, the return values for the query above would look similar to this:

<response>
   <matched>Y</matched>
   <test>ALL</test>
   <count>2</count>
   <itemtest>NAME</itemtest>
</response>

For the 'multi' type test, the XML returned will look similar to this:

    <response>
       <type test="IP">
          <matched>Y</matched>
          <count>3</count>
       </type>
       <type test="MAIL">
          <matched>Y</matched>
          <count>0</count>
       </type>
       <type test="NAME">
          <matched>Y</matched>
          <count>2</count>
       </type>
    </response>

  1. The 'multi' parameter must be present to trigger the 'MULTI' type test
  2. Notice that there is no value after the 'multi' parameter in the GET string. Any value assigned to the 'multi' parameter will be ignored.
  3. There must be at least one (1) of the field items (name, ip, or email) present as a "name=value" pair. The system will ignore up to two (2) missing parameters, so you can (for example) send just the email, or the IP and an email, an IP and a name, etc etc.
  4. The order of the field items doesn't matter, but at least one (1) be present or the system will send back the following error: Missing or Malformed Data for MULTI test.

The field order (IP, MAIL, NAME) will not vary; all of the the top-level elements will be returned each time with a secondary 'match' and 'count' element .

API Returned Data (XML Format)
#DATA ITEMPOSSIBLE VALUESWHEN IS IT RETURNED?MEANING
1DATA MATCHED? <matched>Y</matched>
or
<matched>N</matched>
ALWAYSA 'Y' or 'N' indicating "yes" or "no" as to whether or not the data you sent matched anything in the database.
(In other words, is it a bot?)
2API TEST TYPE <test>MAIL</test>
<test>IP</test>
<test>NAME</test>
or
<test>ALL</test>
ALWAYSA string indicating the type of data you tested for.
3NUMBER OF MATCHES Example values:
<count>2</count>
<count>38</count>
<count>15</count>
ALWAYSAn integer number indicating how many times the tested item was found in the database, for example, '5'.
4API EVALUATION <itemtest>MAIL</itemtest>
<itemtest>IP</itemtest>
<itemtest>NAME</itemtest>
OPTIONALThis value is only returned when using the 'ALL' query. It represents the API's "best guess" at what kind of data you sent (that is, an email address, an IP address, or a user name).

Sample code for parsing XML output is available on the Sample Code page.

You may also want to use the SimpleXML extension for PHP. The SimpleXML extension provides a simple toolset to convert XML into objects that can be processed with normal property selectors and array iterators.

The tutorial from DeveloperTorials.com is also very good and provides some example code as well. It can be found here: http://www.developertutorials.com/tutorials/php/parsing-xml-using-php4-050816/page1.html