reCAPTCHA Client API Documentation

reCAPTCHA is a freely available CAPTCHA implementation. It distinguishes humans from computers. This document describes how to embed a reCAPTCHA on your website and how to customize its appearance.

How the reCAPTCHA API Works

1. The user loads the web page with the reCAPTCHA challenge JavaScript embedded.
2. The user's browser requests a challenge from reCAPTCHA. reCAPTCHA gives the user a challenge and a token that identifies the challenge.
3. The user fills out the web page form, and submits the result to your application server, along with the challenge token.
4. reCAPTCHA checks the user's answer, and gives you back a response.
5. If true, generally you will allow the user access to some service or information. E.g. allow them to comment on a forum, register for a wiki, or get access to an email address. If false, you can allow the user to try again.

This guide focuses on the first three steps. We have a set of APIs for checking the reCAPTCHA answer.

Signing up for a reCAPTCHA Key

In order to use reCAPTCHA, you need a public/private API key pair. This key pair helps to prevent an attack where somebody hosts a reCAPTCHA on their website, collects answers from their visitors and submits the answers to your site. You can sign up for a key on the reCAPTCHA Administration Portal.

Key Scope

Your reCAPTCHA token is valid only at the domain you sign up for and any subdomains (due to the potential attack mentioned above). Some users require keys for multiple sites, for example, a development server and a production server or simply multiple sites hosted on the same server. Three techniques can be used to work around this:

• If one of your servers is "localhost" or "127.0.0.1", reCAPTCHA will not enforce the same-domain rule. Just use the same key as for the production server.
• Generate a key for a broader scope. For example, if your application is a.example.com and your test server is test.corp.example.com, generate a key for example.com. Note that multiple users can sign up for the key for a domain, so there's no need to worry if you don't own all of example.com.
• Generate a different key for each domain.
  

Getting a reCAPTCHA Challenge

There are three ways to load the reCAPTCHA challenge on your web page

1. The challenge API. This is the easiest and most common method.
2. The non-JavasScript API. This is a backup for when the user doesn't have JavaScript.
3. The AJAX API. This API is useful when you need to dynamically add a CAPTCHA to your page.

Challenge and non-JavaScript API

The Challenge and non-JavaScript API are usually used together. To use these APIs together, you insert the following snippet of code in your website:

<script type="text/javascript"
   src="http://api.recaptcha.net/challenge?k=<your_public_key>">
</script>

<noscript>
   <iframe src="http://api.recaptcha.net/noscript?k=<your_public_key>"
       height="300" width="500" frameborder="0"></iframe><br>
   <textarea name="recaptcha_challenge_field" rows="3" cols="40">
   </textarea>
   <input type="hidden" name="recaptcha_response_field" 
       value="manual_challenge">
</noscript>

This code must be inserted within a <form> tag.  The <noscript> code is there in case the user's browser does not support JavaScript.  It embeds the two widget form fields manually.

These APIs create two form fields: recaptcha_challenge_field is a hidden field that describes the CAPTCHA which is put on the page. recaptcha_response_field is a text field where the user can enter their answer.

The challenge and noscript APIs take a query string parameter named "error". If an error occurred when validating a reCAPTCHA you should pass the error code in this parameter so it can be shown to the user.

reCAPTCHA AJAX API

Interactive Web applications may need to dynamically create the reCAPTCHA widget in response to user input. To support such applications, we also offer an AJAX API. (Here is a simple demo of the AJAX API). To enable the AJAX API, link to the recaptcha_ajax.js file in your HTML:

<script type="text/javascript" 
 src="http://api.recaptcha.net/js/recaptcha_ajax.js"></script>

This JavaScript file defines an object called Recaptcha. The methods in this object allow you to create CAPTCHA areas. The most important is the create method, which creates the CAPTCHA area:

Recaptcha.create("6LdIEwAA......",
"recaptcha_div", {
   theme: "red",
   callback: Recaptcha.focus_response_field
});

This creates a reCAPTCHA with the given public key in the recaptcha_div HTML element. In this example the "red" reCAPTCHA theme is used. Once the CAPTCHA area is created, the focus_response_field method will be called, focusing the reCAPTCHA area.

To submit the user's CAPTCHA response to the server, use the get_challenge and get_responsedestroy after you submit a reCAPTCHA, as challenges can not be attempted multiple times.

Depending on your site's requirements, you may not need all of these functions; only Recaptcha.create() is strictly required. The HTML source of the AJAX demo is a good place to get started.

Look & Feel Customization

You can optionally customize the look of the reCAPTCHA widget with some JavaScript settings. To use these settings, insert a <script> tag that defines a dictionary called RecaptchaOptions. The following dictionary fields can be set:

As an example, this script tag makes the reCAPTCHA have a white theme and have tabindex 2:

<script>
var RecaptchaOptions = {
   theme : 'white',
   tabindex : 2
};
</script>

Custom theming

You can customize the look of reCAPTCHA to adapt it to your website. Custom theming allows you to control exactly how the reCAPTCHA image appears. You can see a demo of custom theming. In order to use custom theming, you must first set the theme property of the RecaptchaOptions to 'custom'. This tells reCAPTCHA that it should not create a user interface of its own. reCAPTCHA will rely on the presence of HTML elements with the following IDs to display the CAPTCHA to the user:

• An empty div with ID recaptcha_image. This is where the actual image will be placed. The div will be 300x57 pixels.
• A text input with ID and name both set to recaptcha_response_field. This is where the user can enter their answer.
• Optionally, a div which contains the entire reCAPTCHA widget. This ID div should be placed into the custom_theme_widget and the style of the div should be set to display:none. After the reCAPTCHA theming code has fully loaded, it will make the div visible. This element avoids making the page flicker while it loads.

The Recaptcha JavaScript object provides methods which allow you to change the state of the CAPTCHA. You will want to look at the reload and switch_type methods for your theming implementation.

In order to create a UI for the CAPTCHA, you need to display different information when the CAPTCHA is in different states. For example, when the user is viewing an image CAPTCHA, a "switch to image" button should not be shown. Four CSS classes are available for you to create a stateful UI.

CSS Class	Visible when...
recaptcha_only_if_image	an image CAPTCHA is being displayed
recaptcha_only_if_audio	an image CAPTCHA is being displayed
recaptcha_only_if_incorrect_sol	the previous solution was incorrect
recaptcha_only_if_no_incorrect_sol	the previous solution was not incorrect

While theming does give you many options, you need to follow some user interface consistency rules:

• You must state that you are using reCAPTCHA near the CAPTCHA widget.
• You must provide a visible button that calls the reload function
• You must provide a way for visually impaired users to access an audio CAPTCHA.
• You must provide alt text for any images that you use as buttons in the reCAPTCHA widget.

Methods of the Recaptcha object

The Recaptcha JavaScript object has various methods that may be helpful. Only methods documented in this section should be relied upon. Specifically, any methods beginning with an underscore are subject to change and should not be used.

reload()	Displays a new CAPTCHA.
switch_type(newtype)	Can be called with an argument 'image' or 'audio' to allow the user to switch the type of the CAPTCHA.
showhelp()	Displays a popup with reCAPTCHA instructions.
get_challenge() get_response()	Helper functions that return the reCAPTCHA challenge string and the response that the user has typed in to the response field. They return null if the widget isn't showing. Can be used with the AJAX API to retrieve the answers so that an XMLHttpRequest can be used to post the reCAPTCHA solution.
focus_response_field()	Gives focus to the reCAPTCHA response field.
create(public_key, element, options)	In the AJAX API, loads the reCAPTCHA widget into the given element. public_key is your reCAPTCHA public key. element can be either a JavaScript Element object or the string ID of the element. Recaptcha.create() sets the element's innerHTML, so the element should normally be empty. options is the RecaptchaOptions dictionary explained above; it lets you set the theme and tabindex of the reCAPTCHA widget. With the AJAX API, options can also include a callback field: a function that will be called after the widget is done loading. If callback is not specified, nothing is called back.
destroy()	In the AJAX API, removes the reCAPTCHA widget from the element (sets the element's innerHTML to the empty string) and also resets some internal state. You need to use this if the user cancels out of a dialog and you want to cleanly remove the widget from the page. The AJAX API only allows you to show one reCAPTCHA widget at a time. If you call Recaptcha.create() twice for some reason, the API will automatically destroy the old widget before creating the new widget. You can see this behavior in the AJAX demo.

Using reCAPTCHA on an https site

In order to avoid getting browser warnings, if you use reCAPTCHA on an SSL site, you should replace http://api.recaptcha.net with https://api-secure.recaptcha.net. For example:

<script type="text/javascript"
   src="https://api-secure.recaptcha.net/challenge?k=<your_public_key>">
</script>

<noscript>
   <iframe src="https://api-secure.recaptcha.net/noscript?k=<your_public_key>"
       height="300" width="500" frameborder="0"></iframe><br>
   <textarea name="recaptcha_challenge_field" rows="3" cols="40">
   </textarea>
   <input type="hidden" name="recaptcha_response_field"
       value="manual_challenge">
</noscript>

Validating the CAPTCHA

This document explains about how to display the reCAPTCHA widget. To validate it, you'll need to use one of our plugins or write your own wrapper around the validation api.

Tips & Guidelines

• If the user enters the CAPTCHA incorrectly, you can help them by:
• Re-display the form in question with the form data they entered pre-filled.
• Use the error= parameter to challenge so that the error is displayed to the user.

That's it. You might want to look at the resources page to see examples of how to use reCAPTCHA in applications.

Other Resources

• The reCAPTCHA Discussion Group, where you can discuss the reCAPTCHA API with other users as well as the developers of reCAPTCHA.
• reCAPTCHA Resources Index. Links to plugins and libraries.
• The reCAPTCHA Plugins & Libraries Project, where you can find plugins for various applications and reCAPTCHA helper libraries.