Sign in


New search engine...

My search engines

Email preferences

Linked Custom Search Engines

In a Linked CSE the specification of the search engine is hosted on your website. In a Google Stored CSE the specification is stored at Google.

With a traditional Google Stored CSE, you create the CSE either by logging in and using the wizard or writing an XML file and uploading to Google (via the Advanced tab). The search box code that you use refers to this specification stored at Google using the "cx" parameter. To change any aspect of the CSE, you have to either use the Control panel or upload the new XML specification. This imposes several limitations:

  • Creating and maintaining a CSE is a manual process.
  • It is difficult to create a very large number of CSEs, say one for each of your users or a slightly different one for each of your pages.
  • It is difficult to use other data sources such as iCal, RSS, Google Base, etc. to programmatically create CSEs.

Linked CSEs overcome these limitations of Google Stored CSEs. With Linked CSEs, you host the CSE specification on your web site and include the url for this specification in your CSE search request. Google retrieves the CSE specification from your website when your user searches in the CSE. This has several very important benefits:

  • You can easily convert your data to a Custom Search Engine.
  • You can automatically generate any number of CSEs, each possibly tuned to a particular user, the particular page, time of day, etc. In fact, you can generate CSEs on demand, in response to a users query or a page on your site that your user is searching from. We provide several interesting tools, such as creating a Linked CSE out of the links on a page, that you can use.
  • You can easily update your Linked CSE definitions without pushing data to Google.
  • There are no global, per user annotation limits.

You can now exploit the full power of your ideas to dynamically generate CSEs. The tools provided by us and third parties make it easier to keep your CSE in sync with your own website and those of others. Some interesting sources of data you could use to create CSEs are iCal feeds, your referrer logs and your users' bookmarks or browsing history. You could even change the look and feel of your CSE in response to the health or traffic of your website. Get creative - the possibilities are limitless!

CSE specification can refer to one or more external annotation files. This makes it easier to share annotations between CSEs.

Please note however that some of the features of Google Stored CSEs such as collaboration and Google Marker won't work with Linked CSEs. If you already have annotations stored with Google, you can download them and include these annotations in your Linked CSE. For more information, read Switch from Google Stored CSE to Linked CSE. Note also that Linked CSEs are always free, ad-supported CSEs; the Linked CSE mechanism cannot be used to host CSE specifications for Google Site Search.

Example of a Linked CSE

The following is a very simple example of the use of a Linked CSE whose specification is at The CSE specification contains the sites to search over, the look and feel of the results, etc. Here is the code for the search box that uses this CSE specification. Note the parameter called 'cref'.

Important form parameters:

  • cref: The url of your CSE specification
  • q: The query box

Try this search engine out here!

Note that this search box could be on the same site as the CSE specification file, on multiple pages on that site or even on a different site.

The first time a user issues a search query, we will fetch the CSE specification and use it to process the query. We also cache your CSE specification and periodically refresh it, so that you don't have to worry about serving Google's CSE specification requests every time your user issues a query. If you change the specification of your Linked CSE and need it refreshed right away simply go to our Linked CSE refresh page and enter your URL of your CSE specification.

Example of a Linked CSE with results hosted on your site

Just like with a standard Custom Search Engine, you can also use a Linked CSE to host results on your site. In order to do this you need two snippets of code, one for the search box and one for the search results. The search box code looks similar to the example above, with a few changes:

Important form parameters:

  • action field: The URL you wish to host the results at (in this example we use
  • cref: The url of your CSE specification
  • cof: Either FORID:9, FORID:10 or FORID:11. This specifies what ads format you want to display. See the CSE specification for more information.
  • q: The query box

At the URL pointed to by the action field above, you need to place this code where you want the search results to appear:

Annotations in Linked CSEs

For Linked CSEs to work, you will need to specify the annotations as shown in the above example. There are two ways to specify annotations:

  • External annotations: You specify the location of your annotation files using <Include> tags. Read more about external annotation files. The example we saw in the previous section uses two external annotation files: one of which is a file stored on a server and the other is the output of a script.

  • Inline annotations: You put the annotations along with your CSE specification in the same file. Read more about inline annotations. The above example has two inline annotations:* and*.

We require each file to be less than 3MB in size. If you have more annotations than that, you can split them up into multiple files and use <Include> tags for specifying those files. You can have up to fifty files, but the total size of all the files you have included must be less than 10MB. We expect that this will allow you to include about 25K annotations per CSE. If you need more than that, we encourage you to go meta - create multiple CSEs, get the results and put them together for your users. This programmatic interface allows you to do almost anything!