BotSmasher API allows site owners a means of automatically checking IP addresses, email addresses, and names to determine if those pieces of information match the information of alleged bots or otherwise fraudulent users of web systems. This can be used to protect against comment spam, forum spam, fraudulent registrations and other illegitimate actions - particularly in cases where forms are in use.
Common Use Cases for the BotSmasher API
Checking For Bots or other Fraudulent usage
BotSmasher can be used at the time of form submission to check whether the email address or name submitted are fraudulent or whether the IP address of the submitter is associated with fraudulent submissions. In this scenario we check our database, which is an aggregate of our own data as well as other, similar services, to see if any of these pieces of information have been found.
Submitting Bots (we call them bad guys)
API Users can also submit IPs, names, and emails to be included into our database. Note, however, that your submission will only cause that information to be 'true' for you. In order to be included in our listings, those same pieces of information must come from peer submissions as well. This helps thwart abusive or overzealous submissions while giving you real-time ability to block abuse. In other words, you can use BotSmasher as your own personal blacklist.
"Clearing" Bad Guys
API users can also clear IP addresses, names, and emails. The intended purpose for this is to act as an "Undo" for accidentally submitting new bad guys.
Using the API
All requests against the API must come from registered users with a valid API key. To obtain a key, register at http://www.botsmasher.com/register.php.
Steps to Register
- Go to http://www.botsmasher.com/register.php
- Enter your email address - note: a valid email address is required to confirm your registration and get your API key. If you submit the form with a fake email you won't be able to confirm your registration.
- Enter your email address (again)
- Enter your name
- Enter your website
- Activate the 'OK' button. The system will send you an email with a confirmation link.
- Activate the confirmation link that you receive in the email and we will display your API key and also send it to you in an email.
- You can now use the API
- You can API to submit up to 100 'check' requests per day. If you require the ability to submit more than that, contact us to discuss your needs.
- All requests are sent to https://www.botsmasher.com/api/ Note the use of the https protocol.
- Requests can come as GET or POST. We prefer POST.
- Possible parameters are:
- 'key': Required, your API key we give you upon successful registration
- 'action': Required, the action to perform. The value supplied must be one of the following:
- 'check' - this action will check our records for existence of one (or more) of the parameters below
- 'submit' - this action will submit the information to the database, "blacklisting" the information on 'ip', 'name', or 'email' that you also submit.
- 'clear' - this action will undo the submission process above for the information on 'ip', 'name', or 'email' that you also submit. This will not remove those records from the general database.
- 'email': the email address to act upon
- 'ip': the IP address to act upon
- 'name': the name to act upon
- All requests must contain at least one of the following parameters:
- 'ip' - this must be a valid IP address in the form of AAA.BBB.CCC.DDD
- 'email' - this must be a valid email address
- 'name' - this can be any arbitrary string
- Requests may have multiple of the above parameters. In such cases, our reponse will return individual responses for all supplied parameters as if it was a boolean 'OR' search. For example:
- 'ip' gets only ip
- 'ip' and 'name' gets ip OR name
- 'ip', 'name', and 'email' gets ip OR name OR email
All responses come in the form of JSON. The following is a sample response from BotSmasher showing all possible values.
"lastseen": "0000-00-00 00:00:00",
"lastseen": "0000-00-00 00:00:00",
"submitted": "joe schmoe",
"lastseen": "0000-00-00 00:00:00",
A success response is returned whenever you submit a well-formed request. The information returned will include whether we have a match for your query and, for each match, how many times it was found.
A failure response is returned whenever some condition exists which causes the process to halt prematurely.
|Missing Parameter||A required parameter was missing. All requests must contain the 'key' parameter and one or more of the following: 'ip', 'name', or 'email' (up to and including all of them)|
|Invalid User||This message is returned whenever the API key supplied is either not found or has been banned.|
|Over Limit||This message is returned whenever you have exceeded the total # of requests you're allowed in a day. If you repeatedly get this error, contact us to upgrade you.|
|Unknown Error||This message is returned whenever the API is unable to return any data at all.|
This example would check email, ip, and name
The BotSmasher API also accepts submissions for new bots. This is performed using the 'submit' value in the action parameter.
This example would submit email, ip, and name
Submission responses will come in the same format as 'check' responses, with obvious differences being that the relevant values for a 'check' are missing. Here's a sample:
What happens when you submit a new bot
As soon as you submit a new bot, it will be added to our database. Future queries against the API will return that fact in the results. That does not, however, mean that all other users will see this. We must see multiple other users submitting the same information before we flag that info for all.
Note: Abuse - or even suspected abuse - of this feature will cause immediate and permandent revokation of your API access.
The clearing action essentially un-submits a previous submission you've made. For instance, if you submit an email address and later decide that you don't want to block that email, you can clear it.
Note: This will only clear your submission. For instance, if that same email has been added to the main BotSmasher database, it will still return 'true' for bad guys.
This example would clear an email
Clearing responses will come in the same format as 'submit' responses. Here's a sample:
Acceptance of Terms
Rights To Change Terms
BOTSMASHER AND/OR ITS RESPECTIVE SUPPLIERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE INFORMATION CONTAINED IN THE DOCUMENTS AND RELATED GRAPHICS PUBLISHED AS PART OF THE SERVICES FOR ANY PURPOSE. ALL SUCH DOCUMENTS AND RELATED GRAPHICS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. BOTSMASHER AND/OR ITS RESPECTIVE SUPPLIERS HEREBY DISCLAIM ALL WARRANTIES AND CONDITIONS WITH REGARD TO THIS INFORMATION, INCLUDING ALL WARRANTIES AND CONDITIONS OF MERCHANTABILITY, WHETHER EXPRESS, IMPLIED OR STATUTORY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL BotSmasher AND/OR ITS RESPECTIVE SUPPLIERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF INFORMATION AVAILABLE FROM THE SERVICES.
THE DOCUMENTS AND RELATED GRAPHICS PUBLISHED ON THE SITE COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN. BOTSMASHER AND/OR ITS RESPECTIVE SUPPLIERS MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED HEREIN AT ANY TIME.
Personal and Non-Commercial Use Limitation
Unless otherwise specified, you may not modify, copy, distribute, transmit, display, perform, reproduce, publish, license, create derivative works from, transfer, or sell any information, software, products or services obtained from the Services.
Use of Copyrighted Materials and Logos
You may not reproduce, copy or redistribute the design or layout of any BotSmasher Web page, individual elements of the Web site design, or BotSmasher logos without the express written permission of BotSmasher. Copyright, trademark, and other proprietary notices may not be removed.
BotSmasher retains all ownership and other rights in our RSS Content. You must provide attribution to the appropriate BotSmasher website in connection with your use of our RSS feeds. If you provide this attribution using a graphic, you must use the appropriate BotSmasher website's logo that we have incorporated into the RSS feed.
Although BotSmasher attempts to provide useful and timely information, we do not guarantee that the information is accurate, current, or suitable for any particular purpose. We assume no obligation to update or continue to post information or updates to said information.
While you visit our site, BotSmasher does not guarantee that access to this site will be uninterrupted, that this site will be free of viruses or that this site cannot be tampered with by third parties.
BotSmasher does not guarantee that information sent to this site will not be obtained, reviewed, or tampered with by third parties.
This site and the information on this site are provided "as is" with no warranties of any kind whatsoever, either express or implied, including, but not limited to, any warranties of title or accuracy or any implied warranties of merchantability or fitness for a particular purpose. Links to Third Party Sites
Some of the links in the BotSmasher Web site will let you leave this site. The linked sites are not under the control of BotSmasher and we are not responsible for the contents of any linked site, or any changes or updates to such sites. BotSmasher is not responsible for Webcasting or any other form of transmission received from any linked site. BotSmasher provides these links to you only as a matter of convenience, and the inclusion of any link does not imply endorsement by BotSmasher of the site.
Use of This Site and the Information Is At the User's Sole Risk
In no event will BotSmasher be liable for any damages whatsoever arising out of or related to this site, any site operated by a third party or any information contained in this site or any other site, including but not limited to direct, indirect, incidental, special, consequential or punitive damages, whether under a contract, tort or any other theory of liability, even if BotSmasher is aware of the possibility of such damages.
Transmitted Material Through the Internet
Transmissions are never completely private or secure. By visiting our site, you understand and accept that any message or information you send to this site may be read of intercepted by others unless there is a special notice that a particular message is encrypted. Sending a message or a resume to BotSmasher does not cause BotSmasher to have any special responsibility to you.
Agreement to Conduct Rules
You agree to abide by the BotSmasher User Conduct Rules, including but not limited to, agreeing not to use this site for any unlawful purpose:
By posting information in or otherwise using any communications service, message board, or other interactive service that may be available to you on or through the BotSmasher Site, you agree that you will not upload, post, or otherwise distribute or facilitate distribution of any materials, including text, communications, software, images, sounds, data, or other information (hereafter "Content") that:
is unlawful, threatening, abusive, harassing, defamatory, libelous, deceptive, fraudulent, invasive of another's privacy or publicity rights, tortious, or otherwise violates the BotSmasher rules or policies;
infringes on any patent, trademark, trade secret, copyright, right of publicity, or other proprietary right of any party;
constitutes unauthorized or unsolicited advertising, chain letters, any other form of unauthorized solicitation, or any form of lottery or gambling;
contains software viruses or any other computer code, files, or programs that are designed or intended to disrupt, damage, or limit the functioning of any software, hardware, or telecommunications equipment or to damage or obtain unauthorized access to any data or other information of any third party; or
contains information, material, or pictures of any person who is not both older than eighteen (18) years old and over the age of majority in such person's state, providence, or country of residence.
contains pornography or obscene material. BotSmasher has sole discretion as to what constitutes obscenity.
You also agree that you will not harvest or collect information about the users or members of this Site or use such information for the purpose of transmitting or facilitating transmission of unsolicited bulk electronic e-mail or communications. BotSmasher generally does not pre-screen, monitor, or edit the content posted by users of communications services, chat rooms, message boards, or other interactive services that may be available on or through this site. However, we have the right at our sole discretion to remove any content that, in our judgment, does not comply with these User Conduct Rules or is otherwise harmful, objectionable, or inaccurate. BotSmasher is not responsible for any failure or delay in removing such content.
Termination of Access
This Web site (excluding linked sites) is controlled by Karl Groves from our office in the United States of America. It can be accessed from all 50 states, as well as from other countries around the world. As each of these places has laws that may differ from those of the State of Maryland, by accessing this Web site, both you and Karl Groves agree that the statutes and laws of the State of Maryland, without regard to the conflicts of law principles thereof, will apply to all matters relating to use of this Web site. Those who choose to access this site from other locations do so on their own initiative and are responsible for compliance with local laws.
Copyright © 2013 BotSmasher. All Rights Reserved. For More Information
BotSmasher has an absolute zero tolerance for spamming of any kind. Any member who sends unsolicited emails or places posts on usenet, internet forums or discussion lists on which such messages are considered against that site's terms will be immediately and irrevocably banned from our site. If you believe you have received spam concerning BotSmasher, please contact us.