Programmatically Creating Custom Search Engines

This page documents request methods for programmers who want to write client applications that dynamically create custom search engines (CSE) or interact with Custom Search. While pages in the Developer's Guide do not presume any programming knowledge, this page assumes that you know how to program and are familiar with Hypertext Transfer Protocol (HTTP).

Contents

This page includes the following sections:

• Overview
• Authentication
• Summary of Request Methods ^Updated!
• Details of Request Methods ^Updated!
• The Status Codes
• Taking the Next Step

Overview

The Custom Search API lets you skip the control panel altogether and use a client application of your choice to retrieve a list of custom search engines (CSE) under an account, create and delete custom search engines, and retrieve code for a search box, among other things.

The API uses standard HTTP requests, such as: GET, POST, and DELETE. All requests must have an Authorization header that contains an authentication token (described in the next section). In response, the Custom Search server sends an HTTP status code (such as a 200-type status for success or 400-type status for failure) that reflects the result of each request. You can use any programming language that lets you issue HTTP requests and parse XML-based responses.

Basically, the process of programmatically creating search engines involves the following steps:

1. Create the custom search engine specification or context XML. To learn more, see the Defining Your Search Engine Specifications page.
2. Create the annotations XML to let Custom Search know which sites to search or ignore and how to rank the search results. To learn more, see the Selecting Sites to Search page.
3. Get the authentication token from the Account Authentication API. To learn more, see Authentication.
4. Send an authenticated request to the Custom Search server to submit the context XML. To learn more, see Creating and Updating the Search Engine Specification.
5. Send another authenticated request to the Custom Search server to submit the annotations XML. To learn more, see Creating and Updating Annotations.
6. To display the search box and the search results in your website, retrieve the code for displaying the search box and the results page and insert the code into your HTML page. To learn more, see Retrieving the Code for the Search Box and Retrieving the Code for the Search Results.

Back to top

Authentication

Like many Google services, Custom Search is protected by Google Accounts. This means that your client application must have an authentication token in order to interact with Custom Search. You can get authentication tokens from the Google Accounts Authentication Service, which is an API that processes requests for access and issues authentication tokens.

Although the Accounts Authentication API supports multiple authentication methods, Custom Search only supports ClientLogin, which is the interface that lets you incorporate programmatic login into your desktop or mobile applications. It also supports CAPTCHA for greater security against password trollers. When you make a request to ClientLogin, provide the service name for Custom Search, which is cprose.

If your client application is accessing Custom Search on behalf of other users, you must first get their explicit authorization. They can provide their usernames and passwords directly to your client. The Accounts Authentication Service returns authentication tokens that your client can then send to the Custom Search service, and you must use the token with every subsequent request on behalf of your users. The tokens do expire after a while.

For an overview of authenticating with Google, see the Google Data APIs Authentication Overview; for more detailed documentation, see the Account Authentication API; for general FAQ, see the Google Data APIs Frequently Asked Questions; for user discussions on the Google Accounts API, visit the Google Accounts API Group.

Once you have acquired an authentication token, you can use it to create the Authorization header for each subsequent API request, as in the following:

Here is an example of an authenticated GET request:

GET http://www.google.com/coop/api/default/cse/
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

Back to top

Summary of the Request Methods

This section summarizes the different types of supported operations and identifies the URL that corresponds to each operation. It includes the following tables:

• Creating, Updating, and Deleting Search Engines
• Retrieving Search Engines, Promotions, and Search Results ^Updated!
• Retrieving Custom Search Code for Webpages
• Associating the Search Engine with an AdSense Account

The operations are discussed in greater detail in the next section.

Creating, Updating, and Deleting Search Engines

Back to top

Retrieving Search Engines, Promotions, and Search Results^Updated!

Back to top

Retrieving Custom Search Code for Webpages

Back to top

Associating the Search Engine with an AdSense Account

Details About the Request Methods

The section describes the different request methods you can use to create and manage your search engines.

• Creating and Updating the Search Engine Specification
• Creating and Updating Annotations
• Deleting a Search Engine
• Retrieving Components of the Search Engines ^Updated!
• Associating a Search Engine with an AdSense Account

To create the search engine, you need to submit a context XML and an annotations XML.

If you do not know the ID for the custom search engine, you can retrieve the list of search engines and extract the CustomSearchEngine id value.

To learn more about the context XML and its required format, see the Defining Your Search Engine Specifications page; to learn more about the annotations XML, see Selecting Sites to Search page.

Back to top

Creating and Updating the Search Engine Specification

To create or update a context or search engine specification, send an authenticated POST request with the context XML in the message body to the following URL:
http://www.google.com/coop/api/default/cse/<CSE_ID>.

Note: If the search engine already exists, sending the request will replace the stored context XML with the submitted context XML.

The following is an example of a POST request that creates the search engine specification.

POST http://www.google.com/coop/api/default/cse/my_first_cse
Content-Type: text/xml
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

            
 <CustomSearchEngine keywords="cars" language="en">
   <Title>My First CSE</Title>
   <Description>Car Search</Description>
   <Context>
      <BackgroundLabels>
       <Label name="_cse_my_first_cse" mode="FILTER" />
       <Label name="_cse_exclude_my_first_cse" mode="ELIMINATE" />
     </BackgroundLabels>
   </Context>
   <LookAndFeel nonprofit="false" />
 </CustomSearchEngine>

If the request includes a valid XML, the Custom Search server will respond with the Custom Search context XML that it stored. In some cases, it might be slightly different from the context XML that you sent.

<?xml version="1.0" encoding="UTF-8" ?>
  <CustomSearchEngine id="my_first_cse" keywords="cars" language="en">
    <Title>My First CSE</Title>
    <Description>Car Search</Description>
    <Context>
     <BackgroundLabels>
       <Label name="_cse_my_first_cse" mode="FILTER" />
       <Label name="_cse_exclude_my_first_cse" mode="ELIMINATE" />
     </BackgroundLabels>
    </Context>
    <LookAndFeel nonprofit="false" />
  </CustomSearchEngine>

Back to top

Creating and Updating Annotations

To selectively add or remove annotations from the annotations file stored by the Custom Search server, send an authenticated POST request with the Batch XML format in the message body to the following URL:
http://www.google.com/coop/api/default/annotations/.

Note: Custom Search has a file size limit for annotations. To learn more about the limits, see the Selecting Sites to Search page.

You send only the annotations that you want to add or remove from the search engines. If you want to modify an existing annotation, you can remove the annotation and add the modified version in the same message. Because Custom Search combines all the annotations for all the search engines into a single XML annotations file, you can add and remove annotations for multiple search engines in a single message.

Using the Batch Update XML

The Batch element can have two child sections, Add and Remove. The Batch element can contain either or both sections in the same message and has the following hierarchy:

• Batch
  • Add
    • Annotations
      • Annotation
        • Label
        • Comment (optional)
  • Remove
    • Annotations
      • Annotation href

You can have only one Add section and one Remove section, each of which can have a single Annotations subsection with multiple Annotation elements. For a more detailed discussion of Annotations XML format, see the Selecting Sites to Search page.

Adding Annotations

To add annotations to your account, use the Add element and populate it with annotations in the standard annotations XML format, as shown in the following:

<Annotations>
      <Annotation about="http://www.example.com/*">
        <Label name="_cse_example"/>
      </Annotation>
      <Annotation about="http://www.sample.net/*">
        <Label name="_cse_example"/>
      </Annotation>      

</Annotations>

Let's say that you created another search engine for an account that already has two search engines, and you want to upload the annotations just for that search engine. You can send the following request.

POST http://www.google.com/coop/api/default/annotations/
Content-Type: text/xml
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"



<Batch>
  <Add>
    <Annotations>
      <Annotation about="http://www.solarenergy.org/*">
        <Label name="_cse_solar_example"/>
      </Annotation>
      <Annotation about="http://www.solarfacts.net/*">
        <Label name="_cse_solar_example"/>
      </Annotation>
      <Annotation about="http://en.wikipedia.org/wiki/*">
        <Label name="_cse_exclude_solar_example"/>
      </Annotation>

   </Annotations>
  </Add>
</Batch>   

Removing Annotations

The XML for removing annotations is slightly different. Instead of using the full annotation format with URL and label names, you just need to use the annotations ID or href id. Custom Search tags each annotation with an href id. To get this ID, retrieve all the annotations and extract the href id of the annotations you want to delete.

The following is a code snippet that removes annotations.

  <Remove>
     <Annotations>
       <Annotation href="Cg93d3cuZ29vZ2xlLmNvbS8Qrsq3gv456gRI" />
       <Annotation href="Cg93d3cuZ29vZ2xlLmNvbS8Qzsq3gvWd23" />
     </Annotations>
  </Remove>

Making Multiple Changes

You can also send a batch update with both Add and Remove elements, as in the following example.

POST http://www.google.com/coop/api/default/annotations/
Content-Type: text/xml
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"


<Batch>
  <Add>
    <Annotations>
      <Annotation about="www.cnn.com/*" score="1.0">
        <Label name="test" />
        <Comment>News</Comment>
      </Annotation>
      <Annotation about="www.youtube.com/*" score="0.5">
        <Label name="test" />
        <Comment>Videos</Comment>
      </Annotation>
    </Annotations>
  </Add>
  
  <Remove>
     <Annotations>
       <Annotation href="Cg93d3cuZ29vZ2xlLmNvbS8Qrsq3gv456gRI" />
       <Annotation href="Cg93d3cuZ29vZ2xlLmNvbS8Qzsq3gvWd23" />
     </Annotations>
  </Remove>
</Batch>           

If the request includes valid XML, the Custom Search server will respond with the annotations XML it will store.

<Batch>
  <Add>
     <Annotations>
       <Annotation about="www.cnn.com/*" score="1" comment="News" timestamp="0x00045d3da6b1d7fd" href="Cg13d3cuY25uLmNvbS8qEP2vx7Xap5cC">
         <Label name="test" />
       </Annotation>
       <Annotation about="www.youtube.com/*" score="0.5" comment="Videos" timestamp="0x00045d3da6b1d81a" href="ChF3d3cueW91dHViZS5jb20vKhCasMe12qeXAg">
         <Label name="test" />
       </Annotation>
     </Annotations>
  </Add>

  <Remove>
    <Annotations>
      <Annotation href="Cg93d3cuZ29vZ2xlLmNvbS8Qrsq3gv456gRI" />
      <Annotation href="Cg93d3cuZ29vZ2xlLmNvbS8Qzsq3gvWd23" />
    </Annotations>
  </Remove>
</Batch>

Creating and Updating Promotions ^New!

To selectively add or remove promotions from the promotions file stored by the Custom Search server, send an authenticated POST request with the Batch XML format in the message body to the following URL:
http://www.google.com/coop/api/default/promotions/<CSE_ID>.

Note: Custom Search has a file size limit for promotions. To learn more about the limits, see the Creating Special Results page.

You send only the promotions that you want to add or remove from the search engine. If you want to modify an existing promotion, you can remove it and add the modified version in the same message.

Using the Batch Update XML

The Batch element can have two child sections, Add and Remove. The Batch element can contain either or both sections in the same message and has the following hierarchy:

• Batch
  • Add
    • Promotions
      • Promotion
  • Remove
    • Promotions
      • Promotion

You can have only one Add section and one Remove section, each of which can have a single Promotions subsection with multiple Promotion elements. For a more detailed discussion of the Promotions XML format, see the Creating Special Results page.

Adding Promotions

To add promotions to your account, use the Add element and populate it with promotions in the standard promotions XML format, as shown in the following:

<Promotions>      
   <Promotion id="0001"
              queries="american born chinese, American Born Chinese, abc, ABC" 
              title="American Born Chinese" 
              url="http://books.google.com/books?id=vawdZyrDw64C"
              description="Graphic novel. First-person account of growing up Asian American by Gene Luen Yang."
              image_url="http://146.74.224.231/archives/Gene%20Yang.jpg" />
</Promotions>

If you do not define the ID of the promotion, Custom Search automatically assigns an ID. Let's say that you want to add promotions with and without IDs. You can send the following request.

POST http://www.google.com/coop/api/default/promotions/<CSE_ID>
Content-Type: text/xml
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"



<Batch>
  <Add>
     <Promotions>
       <Promotion id="0001"
                  queries="american born chinese, American Born Chinese, abc, ABC" 
                  title="American Born Chinese" 
                  url="http://books.google.com/books?id=vawdZyrDw64C"
                  description="Graphic novel. First-person account of growing up Asian American by Gene Luen Yang."
                  image_url="http://146.74.224.231/archives/Gene%20Yang.jpg" />
       
       <Promotion queries="wanderer, the wanderer" 
                  title="Groo the Wanderer" 
                  url="http://www.groo.com/"
                  description="Comedy. American series illustrated by Sergio Aragonés."
                  image_url="http://www.newsfromme.com/images5/groo11.jpg" />
     </Promotions>
  </Add>
</Batch>   

Removing Promotions

The XML for removing promotions is slightly different. Instead of using the full promotion format with queries and results, you just need to use the promotions ID. Custom Search tags each promotion with an Promotions id. If you did not create an ID for each promotion, Custom Search automatically assigns one to them. To get this ID, retrieve the promotions and extract the Promotion id of the promotions you want to delete.

The following is a code snippet that removes promotions.

<Batch>
  <Remove>    
     <Promotions>      
       <Promotion id="comics00001"/>
       <Promotion id="comics00103"/>
     </Promotions>
  </Remove>
<Batch>

Making Multiple Changes

You can also send a batch update with both Add and Remove elements, as in the following example.

POST http://www.google.com/coop/api/default/promotions/<cse_ID>
Content-Type: text/xml
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

<Batch>
  <Add>
     <Promotions>
       <Promotion id="0001"
                     queries="american born chinese, American Born Chinese, abc, ABC" 
                     title="American Born Chinese" 
                     url="http://books.google.com/books?id=vawdZyrDw64C"
                     description="Graphic novel. First-person account of growing up Asian American by Gene Luen Yang"
                     image_url="http://146.74.224.231/archives/Gene%20Yang.jpg" /></Promotions>
      <Promotion queries="wanderer, the wanderer" 
                 title="Groo the Wanderer" 
                 url="http://www.groo.com/"
                 description="Comedy. American series illustrated by Sergio Aragonés."
                 image_url="http://www.newsfromme.com/images5/groo11.jpg" />
      </Promotions>
  </Add>
  <Remove>    
     <Promotions>      
         <Promotion id="comics00001"/>
         <Promotion id="comics00103"/>
     </Promotions>
   </Remove>
</Batch>           

If the request includes valid XML, the Custom Search server will respond with the promotions XML it will store.

<Batch>
  <Add>
    <Promotions>
      <Promotion id="0001"
                 queries="american born chinese, American Born Chinese, abc, ABC" 
                 title="American Born Chinese" 
                 url="http://books.google.com/books?id=vawdZyrDw64C"
                 description="Graphic novel. First-person account of growing up Asian American by Gene Luen Yang."
                 image_url="http://146.74.224.231/archives/Gene%20Yang.jpg" /></Promotions>
      <Promotion queries="wanderer, the wanderer" 
                 title="Groo the Wanderer" 
                 url="http://www.groo.com/"
                 description="Comedy. American series illustrated by Sergio Aragonés."
                 image_url="http://www.newsfromme.com/images5/groo11.jpg" />
     </Promotions>
  </Add>
  <Remove>    
     <Promotions>      
       <Promotion id="comics00001"/>
       <Promotion id="comics00103"/>
     </Promotions>
  </Remove>
</Batch>      

Deleting a Search Engine

To delete a search engine, send an authenticated DELETE request to the following URL:
http://www.google.com/coop/api/default/cse/<CSE_ID>.

Warning: Verify that you have the correct CSE ID because you cannot undo this operation.

The following is an example of a DELETE request.

DELETE http://www.google.com/coop/api/default/cse/my_first_cse
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

Back to top

Retrieving Components of the Search Engines ^Updated!

You can retrieve the following:

• The complete list of search engines in an account
• The context XML of a specific custom search engine
• All the annotations in an account
• The XML feeds for the search results ^New!
• The promotions for a search engine
• The code for the search box that can be inserted in an HTML page
• The code for the search results that can be inserted in an HTML page

Retrieving a List of Search Engines

An account can have more than one search engine. To retrieve the complete list of custom search engines for the account, send an authenticated GET request to the following URL:
http://www.google.com/coop/api/default/cse/

The following is an example of a GET request that retrieves the entire list of search engines.

GET http://www.google.com/coop/api/default/cse/
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

The Custom Search server responds with a list of of custom search engine IDs and titles. The IDs are unique across all accounts, but the title is not. No other account owner has the same creator ID, but multiple account owners can have search engines with the same title.

<?xml version="1.0" encoding="UTF-8" ?>
  <CustomSearchEngines>
    <CustomSearchEngine id="my_first_cse" creator="0123456789" title="My First CSE" />
    <CustomSearchEngine id="my_second_cse" creator="0123456789" title="My Second CSE" />
  </CustomSearchEngines>

Back to top

Retrieving the Specifications of a Search Engine

To retrieve the context XML of a specific search engine, send an authenticated GET request to the following URL:
http://www.google.com/coop/api/default/cse/<CSE_ID>

The following is an example of a GET request that retrieves the context XML of a particular search engine.

GET http://www.google.com/coop/api/default/cse/my_first_cse
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

The Custom Search server responds with the context XML.

 <?xml version="1.0" encoding="UTF-8" ?>
   <CustomSearchEngine id="my_first_cse" creator="0123456789" keywords="cars" language="en">
     <Title>My First CSE</Title>
     <Description>Car Search</Description>
     <Context>
       <BackgroundLabels>
         <Label name="_cse_my_first_cse" mode="FILTER" />
         <Label name="_cse_exclude_my_first_cse" mode="ELIMINATE" />
       </BackgroundLabels>
     </Context>
     <LookAndFeel nonprofit="false" />
   </CustomSearchEngine>

Retrieving All Annotations

To retrieve all annotations for all search engines in an account, send an authenticated GET request to the following URL:
http://www.google.com/coop/api/default/annotations/.

The following is an example of a GET request that retrieves the annotations XML in its entirety.

GET http://www.google.com/coop/api/default/annotations/
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

The Custom Search server responds with the entire list of annotations.

<?xml version="1.0" encoding="UTF-8" ?>
  <Annotations start="0" num="2">
    <Annotation about="*.cnn.com/*" score="1" timestamp="0x0004545f2e9f36cf" href="CgsqLmNubi5jb20vKhDP7fz08ouVAg">
     <Label name="_cse_hg1shdcqrjs"/>
     <AdditionalData attribute="original_url" value="cnn.com/*"/>
    </Annotation>
    <Annotation about="*.google.com/*" score="1" timestamp="0x0004585ba0c61ce4" href="Cg4qLmdvb2dsZS5jb20vKhDkuZiGuouWAg">
     <Label name="_cse_qcfwlffvvrg"/>
     <AdditionalData attribute="original_url" value="google.com/*"/>
    </Annotation>
  </Annotations>    

Back to top

Retrieving XML Feeds of Search Results ^New!

If you are Site Search customer or a Custom Search partner, you can retrieve the XML feeds for your search results by sendin an authenticated GET request to the following URL:
http://www.google.com/cse?<CSE ID>&q=<query term>&output=xml.

The following is an example of a GET request that retrieves the results XML for the query, "Einstein."

GET http://www.google.com/cse?cx=999999999999999999999:srraaaaaaaa&q=einstein&output=xml
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

The Custom Search server responds with the results XML. If the webpage has structured data, the data is included.

<GSP VER="3.2">
    <TM>0.405150</TM>
    <Q>einstein</Q>
    <PARAM name="cx" value="cx=999999999999999999999:srraaaaaaaa" original_value="cx=999999999999999999999:srraaaaaaaa"/>
    <PARAM name="q" value="einstein" original_value="einstein"/>
    <PARAM name="output" value="xml" original_value="xml"/>
    <PARAM name="adkw" value="AELymgUxINzkwsr2ClnvOZ4bodqf4MPdK634hYkFSIGs9-bHCGP_obrUjCfugy_8JPaHjXINX6NJt_fOotOsBkrtj9OxtZAWHgc2a2jRPl3OfKVbQgAluMA" original_value="AELymgUxINzkwsr2ClnvOZ4bodqf4MPdK634hYkFSIGs9-bHCGP_obrUjCfugy_8JPaHjXINX6NJt_fOotOsBkrtj9OxtZAWHgc2a2jRPl3OfKVbQgAluMA"/>
    <PARAM name="hl" value="en" original_value="en"/>
    <PARAM name="oe" value="UTF-8" original_value="UTF-8"/>
    <PARAM name="ie" value="UTF-8" original_value="UTF-8"/>
    <PARAM name="client" value="google-csbe" original_value="google-csbe"/>
    <PARAM name="boostcse" value="0" original_value="0"/>
    −
    <Context>
      <title>Genius Search Engine</title>
    </Context>
    −
    <RES SN="1" EN="10">
    <M>569000</M>
    −
    <NB>
    −
      <NU>
      /custom?q=einstein&hl=en&client=google-csbe&cx=cx=999999999999999999999:srraaaaaaaa&boostcse=0&output=xml&ie=UTF-8&oe=UTF-8&start=10&sa=N
      </NU>
    </NB>
    <RG START="1" SIZE="10"/>
    <RG START="1" SIZE="1"/>
    −
    <R N="1">
    −
      <U>
      http://www.scribd.com/doc/48868/Albert-Einstein-The-World-as-I-See-It
      </U>
      −
      <UE>
      http://www.scribd.com/doc/48868/Albert-Einstein-The-World-as-I-See-It
      </UE>
      <T>Albert <b>Einstein</b> - The World as I See It</T>
      <RK>0</RK>
      −
      <S>
      May 10, 2007 <b>...</b> The collection of thoughts on various scenarios by Albert Eienstein Religion <br>  <b>Einstein</b> Albert Religion-Christianity Business-Asian.
      </S>
      <LANG>en</LANG>
      <Label>_cse_srraacmywxi</Label>
      −
      <PageMap>
      −
        <DataObject type="document">
            <Attribute name="title">Albert Einstein &ndash The World as I See It</Attribute>
            <Attribute name="author">pablasarabjot</Attribute>
            <Attribute name="description">
            The collection of thoughts on various scenarios by Albert Eienstein
            </Attribute>
            ...
            <Attribute name="thumbnail_url">
            http://i5.scribdassets.com/profiles/images/dbw8y5a0etg2a-thumb.jpg
            </Attribute>
            <Attribute name="filetype_image">
            http://www.scribd.comhttp://s7.scribdassets.com/images/filetypes/pdf_16x16.gif?1256049874
            </Attribute>
        </DataObject>
      </PageMap>
....

Back to top

Retrieving Promotions of a Search Engine

To retrieve promotions of a search engine, send an authenticated GET request to the following URL:
http://www.google.com/coop/api/default/promotions/<CSE_ID>.

The following is an example of a GET request that retrieves the promotions XML.

GET http://www.google.com/coop/api/default/promotions/2b-oaog9aqg
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

The Custom Search server responds with the entire list of promotions.

<?xml version="1.0"?>
   <Promotions cse_id="2b-oaog9aqg" start="0" num="3" total="3">

      <Promotion id="p1" queries="chocolate" title="Best Chocolate for People with Taste" url="http://www.example.com/best/chocolate"/>
      <Promotion id="7c3481ba" queries="chocolate" title="The Dangerous Crimes of Chocolate Addicts" url="http://www.example.com/books/chocolate/danger.html"/>
      <Promotion id="5139e65a" queries="candy cane" title="Christmas Candies in Summer" url="http://www.example.com/candycane.asp" 
                 image_url="http://images.example.com/candycane.jpg"/>
   </Promotions>
    

You can use parameters to retrieve a range of promotions. If you do not use a paramater, Custom Search API uses the default values.

The following is an example of a GET request with parameters.

GET http://www.google.com/coop/api/default/promotions/2b-oaog9aqg?start=2&num=5

GET http://.../promotions/<cse_ID>?start=1

GET http://.../promotions/<cse_ID>?num=8

Back to top

Retrieving the Code for the Search Box

To get the code for the search box that you can insert into an HTML page, send an authenticated GET request to the following URL:
http://www.google.com/coop/api/default/cse/<CSE_ID>/code/searchbox.

The following is an example of a GET request that retrieves the search box code for a particular search engine.

GET http://www.google.com/coop/api/default/cse/my_first_cse/code/searchbox
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

The Custom Search server responds with the following:

<form action="http://www.google.com/cse" id="cse-search-box" target="_blank">
  <div>
    <input type="hidden" name="cx" value="0123456789:my_first_cse" />
    <input type="hidden" name="ie" value="UTF-8" />
    <input type="text" name="q" size="31" />
    <input type="submit" name="sa" value="Search" />
  </div>
</form>

<script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse-search-box&amp;lang=en"></script>

Retrieving the Code for the Search Results

To get the code for the search results that you can insert into an HTML page, send an authenticated GET request to the following URL:
http://www.google.com/coop/api/default/cse/<CSE_ID>/code/searchresults.

The following is an example of a GET request that retrieves the search results code for a particular search engine.

GET http://www.google.com/coop/api/default/cse/my_first_cse/code/searchresults
Authorization: GoogleLogin auth="IM6F7Cx2fo0TAiwlhNVdSE8Ov8hw6aHV"

The Custom Search server responds with the following:

<div id="cse-search-results"></div>
<script type="text/javascript">
  var googleSearchIframeName = "cse-search-results";
  var googleSearchFormName = "cse-search-box";
  var googleSearchFrameWidth = 600;
  var googleSearchDomain = "www.google.com";
  var googleSearchPath = "/cse";
</script>
<script type="text/javascript" src="http://www.google.com/afsonline/show_afs_search.js"></script>

Back to top

Associating a Search Engine with an AdSense Account ^New!

You can associate a search engine with an AdSense account by adding the AdSense element in the context XML specification, as described in Making Money. Send the authenticated POST request to http://www.google.com/coop/api/default/cse/<CSE_ID>. For a sample of code, see the Creating and Updating the Search Engine Specification section.

To retrieve the publisher ID and channel ID of the AdSense account, you could use the AdSense API, but it requires you to apply for review. You must meet the main requirements for using the AdSense API, which includes the following:

• You must have at least 100,000 daily page views.
• You must have an approved AdSense account.

To learn more, see the AdSense API review process.

Back to top

The Status Codes

When you send a request to the Custom Search API, it will return an HTTP status code that reflects the result of the request. The following tables describes the status codes.

Status Code for Success

Back to top

Status Code for Failure

Back to top

Exploring Other Features

If you want to customize the search results snippets for your own website, see Customizing Your Result Snippets.

< Back to the Developer's Guide