API
Please visit Docs and FAQ section about implementations and examples about ImHuman Api
Table of Contents
Introduction
Browsing this page I guess you know what an API is, if you don't in short it is a common language to share data and information in our case. It is language independent, meaning that you can access the information with any web enabled language and method. Usually some big and control freak APIs needs several communication messages in order to service. But fortunately our simple one only needs one comminucation. Here is how it works in short;
- Your website is going to display some content that requires human|bot check, so with your identification and parameters it asks the ImHuman API for humanizers*
- If identification and parameters are correct ImHuman API provides you with humanizers.
* Humanizer is an 1 by 3 arrray | object which includes the image, name and value for an input
Expected Parameters
For the ease of use ImHuman API requires parameters via GET method.
Simple words, http://www.url.com?param1=1¶m2=2
Parameters Table. All parameters are consisted of small case letters
| PARAMETER | TYPE | REQUIRED | EXPLANATION |
|---|---|---|---|
| api | Double | YES | Version of Client API-Library. Exists in order to prevent conflicts if a future API update takes place. ImHuman API will reject requests made from clients who are using libraries older than Minimum Client Library version. |
| user | String | YES | API user value for the identification. Generated by control panel automatically when you add a website. |
| key | String | YES | API key value for the identification. Automatically generated also |
| row | Integer | YES | How many rows of humanizers to return. Creates GRID with the col value where GRID = row * col GRID can not be bigger than 25 |
| col | Integer | YES | How many columns of humanizers to return |
| sel | Interger | YES | How many humanizers needs to be selected. Minimum 2 maximum GRID - 1, which is 24 |
Response Format
ImHuman API reponds in JSON format. PHP decodes the JSON format by default with the json_decode() function from PHP 4.4.x I guess and if not there are tons of libraries made for json parsing for PHP and many languages. Best resource is json.org, which includes all libraries in nearly all languages.
Response Values
| VALUE | TYPE | EXPLANATION |
|---|---|---|
| APIV | Double | Current ImHuman API version which ImHuman API runs on. Just for debugging |
| MAPIV | Double | Currently required Minimum Client Library version to connect to API |
| CLAPIV | Double | Currently connected client's library version. (debugging) |
| ERROR | Integer | Error Identification Number which returns 0 on ne error and starts from 100 on errors |
| RSP | String |
If an error occured returns the explanation of the error code |
| RSP::WORD | String | The word | tag needs to be selected through humanizers |
| RSP::ANSWER | String | Answer for the correct humanizer selection. |
| RSP::GRID | Array|Object | Consists or [row * col] by [3] array. [row * col ][ i ] :: [ src = humanizer source ][ name = humanizer unique name][ value= humanizer unique value ] |
Error Codes
| ERROR CODE | ERROR STRING |
|---|---|
| 100 | NO USER SUPPLIED |
| 101 | NO KEY SUPPLIED |
| 102 | NO ROW SUPPLIED |
| 103 | NO COLUMN SUPPLIED |
| 104 | NO SELECTION SUPPLIED |
| 105 | NO API SUPPLIED |
| 106 | PLEASE UPDATE YOUR API TO CURRENT VERSION |
| 107 | IMHUMAN API DATABASE CONNECTION ERROR |
| 108 | MINIMUM 3 HUMANIZERS REQUIRED |
| 109 | MINIMUM 2 SELECTION REQUIRED |
| 110 | SELECTION CAN NOT BE BIGGER THAN (OR EQUAL TO) GRID |
| 111 | INVALID API USER | KEY |
| 112 | MAXIMUM GRID SIZE 25 |
| 113 | SELECTION IS TOO BIG |
| 114 | DB ERROR |
June 10th, 2009 - 07:07
How can i get my api for my site?
June 10th, 2009 - 07:31
Visit Control Panel and click on create website link.
July 4th, 2009 - 09:37
hi
November 11th, 2010 - 04:04
and my site ip???
November 11th, 2010 - 10:02
You can find it out by many websites. it is your dns ip in many cases. google for it and you will be able to find your website IP
January 24th, 2011 - 20:14
Why do I have empty boxes?
How to put the picture?
Help, all set in the instructions.
April 14th, 2011 - 11:54
I want to receive words in Russian. But i receive ?????? in the word field in JSON by the link http://api.elxsy.com/?api=1.0&user=my_user_id&key=my_user_key&row=1&col=5&sel=3&lang=ru. It works great if i use lang=en. But i need Russian. What can i do?
April 29th, 2011 - 05:34
I’m trying to figure this out, but it’s just not coming to me. How in the world do I get an API key?
I’ve clicked on “Create Website” on the control panel page. But the only thing that happens is the page goes dark (all except the menu on the top bar). What am I doing wrong?
Btw, this is a great idea.
Edit: I’m trying to click through to post this comment, but I’m getting some images that say “This image not available”. So, I don’t know if it’s a muffin or not!
April 30th, 2011 - 15:13
Update: I’ve registered on this site and have gotten my API ID and key. I’ve also entered those details into my site’s settings.
However, on my site it’s saying “Please select all: (s):” and there are just five empty boxes.
November 27th, 2011 - 13:51
One of pictures on Flikr unavailable. May I use own pictures from my site, not flikr?
November 28th, 2011 - 20:38
Unfortunately not at this moment, but I am reviewing the API and functionality;
I think those changes will make a better API and experience
December 7th, 2012 - 08:59
Hello! I’ve clicked on “Create Website”, have got password, but at my profile page I can not see API key. Where can I see it?