API

Přehled

RoCAPTCHA API and system of communication is basicly very similar to reCAPTCHA.

Lifecycle:

  1. The user loads web application page with RoCAPTCHA JavaScript embedded.
  2. The user's browser requests new challenge from RoCAPTCHA server. Server generates new challenges and send to client browser hash identificator of this challenge.
  3. RoCAPTCHA's JavaScript downloads challenge image and displays it to user.
  4. User solves RoCAPTCHA challenge and submits result together with other data, which needs to be sent to application server.
  5. Application server sends challenge result to RoCAPTCHA server.
  6. RoCAPTCHA server compares given challenge result to right value and either true when equals or false otherwise.
  7. Application server saves the user data if RoCAPTCHA server returned true or asks user to complete RoCAPTCHA challenge once more.

API požadavek

All requests have to be made with URL https://rocaptcha.com/, for example https://rocaptcha.com/api/js/.

URL Type Parameters Response Description
/api/js/ GET

Returns JavaScript code, which will be controlling RoCAPTCHA solving process.

Gets JavaScript code for managing and rendering RoCAPTCHA.
/api/form/ GET JSON: {'status': <status code>, 'content': <HTML form>}

If status code equals OK, returned HTML form will be inserted to page.

Gets HTML form for displaying RoCAPTCHA test.
/api/generate/ GET JSON: {'status': <status code>, 'content': <hash>,
'animal_status': <animal status code>}

Returns new image hash value. If status code equals OK, this hash will be used for downloading image test from RoCAPTCHA server.

Generates new test image and returns it's hash.
/api/verify/ POST
  • key (required) - private key
  • hash (required) - image hash
  • response (required) - response value
  • remoteip (required) - client IP
  • lang (optional) - language code
JSON: {'status': <status code>}

Returns either PASSED or FAILED status. In case of some error may also return other status value, see status codes.

Verify response and returns PASSED or FAILED code.

Status codes

Code Description
OK Everything is fine.
ERROR Error on server side.
PASSED RoCATPCHA test was successfully passed.
FAILED RoCATPCHA test was not passed.
BAD_PUBLIC_KEY You have send wrong public key.
BAD_PRIVATE_KEY You have send wrong private key.
TIMEOUT Timeout of 20 minutes has passed, you have to generate test again.
WRONG_RESPONSE You have send wrong response value. Valid is integer value from 0 to 360.
WRONG_HASH You have send wrong image hash code. Try generating new one.

Animal status codes

Code Description
NONE This animal has no particulat state.
FOUND Animal has been found and is looking for its owner.
LOST Animal has been lost by owner and is missing.
ADOPTION Animal is availible for adoption.

Currently supported languages

Language code Name
en English
cs Czech