My favorites | English | Sign in

Gadgets API

Frequently Asked Questions

Getting Started

What are gadgets?
Gadgets are small web applications that run on multiple sites, including iGoogle, orkut, other OpenSocial containers, Google Desktop, and thousands of sites all over the web that use Gadgets for Your Webpage. Gadgets are written in a module language using XML that wraps HTML and JavaScript.
What's the difference between gadgets and Desktop Gadgets?

What you can do with gadgets:

  • Write in HTML; for dynamic behavior add JavaScript, Flash, or Silverlight.
  • Get started quickly: no downloads necessary, no libraries to learn, and no webserver required.
  • Create gadgets that run online in various sites — such as iGoogle, orkut, other OpenSocial containers, Maps, Desktop, and Calendar — as well as in third-party platforms and any webpage.

What you can do with Desktop gadgets:

  • Write in XML and JavaScript, optionally using C, C++, C#, or VB.net
  • Use advanced functionality, such as:
    • Free-form shapes and transparency
    • Client libraries
    • Responses to user actions outside the gadget (such as when the user opens iTunes or starts reading an email message)

Notes:

  • Google Desktop must be installed on the user's computer.
  • Not all gadgets can be added to a user’s desktop
Where do gadgets exist?
Gadgets are simply externally hosted XML files. They can be stored anywhere that normal web sites can be hosted. Google offers free hosting services that you can use to host your gadgets: Google Gadget Editor and Google Code Hosting.

Google fetches the XML specification when the gadget is displayed and caches it for approximately a few hours to prevent web hosting providers from being overloaded with requests.
How do I create gadgets?
Start by visiting the documentation and read through the "Getting Started" guide. Gadgets are externally hosted XML files that must be publicly accessible on the Internet. You can create a gadget XML using any text editor and upload to your hosting provider. Depending on which version of the API you're using (see Which version of API should I use?) you can test gadgets in the iGoogle developer sandbox or the Google Gadget Editor.

Gadgets re-use existing web technologies such as HTML, JavaScript, Flash, CSS, etc. if you have questions on gadget development, post your questions to the discussion group, and check out the gadgets support pages for additional resources.
What guidelines should I follow when creating gadgets?
See the Community Guidelines for details on the guidelines you should follow when creating gadgets.

Content Directory

What is the content directory?
The Content Directory is a listing of gadgets that can be added to iGoogle or other web pages. It provides a central location for users to find new gadgets to add to their pages. Most of the gadgets in the Content Directory were written by other companies and by Google's users.
How do I make my gadgets more discoverable?
There are various ways you can promote your gadget and help other users discover it. Getting more people to use your gadgets is rewarding and helps increase your gadget's ranking in our directory. Here's a few recommended ways to get started:
How does ranking work in the iGoogle directory, and how can I optimize my gadget for top placement?
The iGoogle directory is designed to help iGoogle users quickly and easily browse and search for gadgets they can add to iGoogle. Gadgets that rise to the top of the directory tend to be useful, fun, interactive, and regularly updated.

Like Google search results, the directory is algorithmic. We use a constantly evolving formula to bring the best gadgets to the top. Some of the factors in this formula include the gadget's popularity in the directory, the amount of time a user keeps the gadget on their page after adding it, the amount of metadata the gadget owner provides, and the user's personal iGoogle usage (for instance, if a user has a gadget on their iGoogle page, they won't see that gadget at all when they browse the directory).

Here are some suggestions to help you optimize your gadget and its placement in the iGoogle directory. First and most importantly, make sure your gadget is attractive, useful, and fun. If it's not good for users, they will delete it from their page immediately after adding it, which will hurt your directory ranking. Second, make sure you include as much metadata (thumbnail, description, author name & email)as possible in your gadget. More metadata means users will be able to find more information about your gadget in the directory. The more attractive your gadget listing is, the more popular your gadget is likely to be. Third, watch your gadget's size. Even if your gadget is of high quality, users may delete it if it doesn't look nice on their page. We recommend a height of 80-250 pixels and testing your gadget to make sure it works at a variety of widths, ranging from 180 to 600 pixels. We also recommend designing your gadget to fit with the aesthetics of the iGoogle page so that it will look consistent and attractive on iGoogle itself. And finally, test your gadget thoroughly. Make sure it works on a variety of different browsers (Internet Explorer, Firefox, Safari). It's also very important to make sure it loads quickly and works consistently & reliably. Most users won't keep a gadget that's slow or that breaks.

While these suggestions may help your gadget's directory ranking, it's important to remember that you are ultimately responsible for the performance of your gadget. With tens of thousands of gadgets in the iGoogle directory, we don't recommend relying on the directory to make your gadget popular. Instead, you should use tools like the Add to Google button on your website and in your promotional materials, Gadgets For Your Webpage, or online ads to drive usage for your gadget. This may sound inconvenient, but we think you'll be happy with the results — remember, after a user adds your gadget to their iGoogle page, they could see it every single time they visit Google.
What types of content are you accepting?

As described in the Terms and Conditions, you may not include and display content that violates our program policy. Please see our program policy and DMCA policy for more information.

These policies may be revised from time to time without notice.

Where can I find information about the gadget DMCA policy?
The iGoogle and gadget Digital Millennium Copyright Act policy is available at http://www.google.com/igoogle_dmca.html.
How do I submit my gadget to the content directory?
You should use the submission form to submit your gadget and have it considered for inclusion in the content directory. Gadgets are included based on their quality and usability.
How do I set the category for my gadget?

When you submit your gadget to the iGoogle directory, we automatically categorize it for you. However, sometimes you may want to explicitly define which category should be assigned to your gadget. To do this, simply add a category attribute within the <ModulePrefs> element in your gadget XML. Set the value to one of the categories listed in the directory and make it all lowercase letters.

Here's the current list of categories to choose from:

  • news
  • tools
  • communication
  • fun and games
  • finance
  • sports
  • lifestyle
  • technology
  • politics

You can optionally apply a second category to your gadget by adding another attribute labeled category2, and assigning it a different category listed in the directory. Here's a more full example of a gadget XML spec with two categories applied:

<ModulePrefs title="Healthy News Feeds"  category="news"  category2="lifestyle"  ... />

Please do your best to choose a category that best matches the *content* of your gadget. If you're having trouble determining which category to choose, consider omitting the category attribute initially and let us auto-categorize it for you. Later on, you can always tweak your gadget's metadata and reassign different categories if you feel it has been miscategorized. Remember, it's really to your advantage to choose a category that best matches your gadget's content in order maximize distribution and discover-ability among users.

How do I remove my gadget from the directory?
To remove your gadget from the content directory, simply remove the XML file from your hosting provider, such that accesses to your gadget return a 404 "Not Found" error. This will cause your gadget to drop to the bottom of the directory. If the gadget is not yours but is infringing your copyrights, please submit a DMCA copyright infringement notice.
Why is my gadget not showing up in the directory?
First, check to see if the gadget is already on your page. If a user has already added a particular gadget to their page, we won't show that gadget to that user. Second, make sure you've submitted your gadget to the directory. Once submitted, most gadgets will appear after there's a critical mass of people actively using them. To see all the gadgets ranked and displayed, visit the directory. If, your gadget still fails to appear, XML errors might prevent it from being added to the directory. Make sure your gadget passes XML validation with an XML validator.
Why is my screenshot/thumbnail not showing up?
Images such as the screenshot and thumbnails can take up to one or two weeks to show up, so please be patient. If the images still do not show up, ensure that they are accessible via the URLs provided in the gadget XML, and that they are not blocked by a robots.txt file. If you have been waiting longer than two weeks and the changes still have not been made, please let us know.
Why are my changes not being updated in the directory?
Changes made to gadgets in the directory can take one or two weeks to show up, so please be patient. If you have been waiting longer than two weeks and the changes still have not been made, please let us know.
How can I improve my gadget's rank in the directory?

The directory's ranking algorithms were designed to order high quality, popular gadgets first. There are things you can do to help improve your gadget's ranking:

  • Include thumbnail and screenshot images and as many optional metadata fields as possible.
  • Design your gadget to accommodate both small (800x600) and larger (1400x1050 and up) screen sizes, and try to limit the amount of vertical space your gadget uses.
  • Host your gadget somewhere reliable to ensure high performance and uptime.
  • Test your gadget across multiple browsers, such as Internet Explorer 6 and 7, Firefox 1.0-3.0, Opera, and Safari.
  • Don't require special client-side software (e.g. ActiveX).
  • Increase the number of users by helping people discover your gadget.

Note that your gadget's placement in the directory may vary over time. Also, you should not assume that the placement you see is the same as what other users will see.

What metadata fields should I include with my gadget?
In ordering the gadgets in the directory, one of the things the ranking algorithms look for is the presence of quality metadata,especially the screenshot and thumbnail fields. It's important to populate the mandatory fields listed on the submission page, and as many of the optional fields as possible. For feeds, it's also good to populate as many metadata fields as possible, and especially important to specify a thumbnail image.
Why is the screenshot different than the one I submitted?
It is sometimes necessary to adjust a gadget's metadata in order to host it. This can include updating or resizing the screenshot or thumbnail, and in some cases the title or description.
How long will it take for my gadget to appear in the directory?
Gadget submissions must go through a complex process in order to prevent malicious, illegal, etc. gadgets from polluting the directory. As a result, the amount of time it takes for your gadget to show up is not finite. It may take a week and a half or more. Most importantly, you want people to actively use your gadget. Once submitted, most gadgets will appear after there's a critical mass of people actively using them.

Learn how you can help people discover your gadget.

Using the API

What is the gadgets API?
The gadgets API is a simple way to create content and applications that run on many sites, including iGoogle, orkut, other OpenSocial containers, and Google Desktop. Gadgets don't require any downloads, and were designed to be flexible and easy to use.

Learn more or go directly to the gadgets Developers Guide.
What is XML?
XML is a data format which allows content to be "tagged", allowing both people and computers to easily understand its structure and meaning. Gadgets use XML because it lets people easily write gadgets using one of the many XML editing tools that are available.
Which version of the API should I use?
There are two versions of the gadgets API. The one you should use depends on where you're planning to deploy the gadget. The gadgets Developers Guide offers details on the differences between the versions and links to their respective documentation.
Where can I host my gadgets?
Gadgets are stored anywhere that normal web sites can be hosted. This includes normal web hosting environments, Google Code hosting, and the hosting provided by the Google Gadget Editor. The location must be accessible from the Internet, so that Google can fetch the gadgets and display them to users.
What kind of content can I include in my gadget display?
Since gadgets are essentially web pages, you can include anything that you could include in a normal web page — HTML, CSS, JavaScript, Flash, music, games, and even video. Using the external data fetching methods of the gadgets API, your gadget can even retrieve information from other sites or interact with third-party APIs. See these sections of the gadgets Developers Guide for more information:
How do I fetch remote content and display it inside a gadget?
The gadgets API provides a number of methods for fetching various kinds of external content. See the section of the gadgets Developers Guide on Working with Remote Content for more details.
How can I test my gadget for common errors?
Use the Gadget Checker to determine whether or not your gadget code includes XML or HTML errors, client-side latency, unused features, and more.

Troubleshooting

One of my gadgets has messed up my homepage. How I can start over?
You can use http://www.google.com/ig/resetprefs.html to reset your iGoogle page back to its original appearance.
Bandwidth has exceeded on my gadgets hosting server. What happened and what should I do?
Popular gadgets can put a huge strain on your web hosting service if the gadget requests content (such as images, feeds, flash, or other data types) directly from your hosting provider. Since this can quickly cause a problem, Google provides a "caching proxy". This allows Google to temporarily store resources used by the gadget so that your web hosting only receives a few hundred hits per day, regardless of its popularity. This can greatly reduce the amount of bandwidth used by your web hosting provider. Please see the gadgets Developers Guide section on Remote Content.
I updated my gadget, but I can't see my changes. What's going on?
Since gadgets can become very popular very quickly, they can put a large strain on web hosting providers. In order to alleviate this strain and provide a more consistent experience for gadget users, we "cache", or temporarily store, the gadget XML spec whenever a user loads a gadget. If you update your gadget XML file, you may not see the change until the cache expires — typically after one hour. Since this can hinder gadget development, you can disable the caching for a gadget on iGoogle by using the Developer gadget. For more information on the Developer gadget, please see the Developer gadget section of the gadgets Developers Guide.