This document provides guidelines for the creation of a Google Base XML data feed in the Atom 0.3 format. We've linked standard attributes to their respective sections in the official Atom 0.3 specification to assist you in finding additional information about the components from our examples. Although we provide examples of Atom 0.3 files, we provide minimal details about Atom 0.3 itself. If you are interested in learning more about this standard, we suggest looking over this specification at http://www.mnot.net/drafts/draft-nottingham-atom-format-02.html.
Section 1: Atom 0.3
Below is an example of a basic Atom 0.3 document containing a single item. Based on the Atom 0.3 specification, there are four pre-defined elements at the entry level - title, link, issued, and modified. Although these elements are optional in the Atom 0.3 standard, Google Base requires them.
<?xml version="1.0"?> <feed version="0.3" xmlns="http://purl.org/atom/ns#"> <title> Google Jobs</title> <link href="http://www.google.com/support/jobs/" rel="alternate" type="text/html" /> <modified> 2005-10-11T18:30:02Z</modified> <author> <name>Google</name> </author> <id>tag:google.com,2005-10-15:/support/jobs</id> <entry> |
Section 2: Extending Atom 0.3
As we can see, the pre-defined attributes only allow for limited details about an item. To include more detailed information about an item, we've extended Atom 0.3 by adding the Google Base namespace. Defining the Google Base namespace allows you to use additional elements, called "attributes" in Google Base, and increases the amount of information you can provide about each item in a feed. You can find a list of attributes specific to your item type by clicking on an item type name here.
In this next example, we've taken the sample item introduced above and included additional attributes defined in the Google Base namespace:
<?xml version="1.0"?> <feed version="0.3" xmlns="http://purl.org/atom/ns#" |
The two major additions in this example are the addition of the namespace declaration (in the third line) and the inclusion of four Google Base attributes (image_link, expiration_date, job_function, and location).
Google Base Namespace DeclarationThe following namespace declaration is required in order to use attributes defined only in the Google Base namespace.
xmlns:g="http://base.google.com/ns/1.0"In addition to declaring the Google Base namespace, you must also include a prefix within every attribute tag. We add this prefix to Google Base attributes to distinguish attributes defined in our namespace from elements defined in Atom 0.3. The prefix selected for this namespace declaration is "g":
<g:image_link>http://www.google.com/images/google_sm.gif</g:image_link>Attributes in the Google Base namespace must include this prefix or the attributes, and any values they contain, will be ignored.
Google Base AttributesThe attributes defined in the Google Base namespace are designed to correspond with a specific feed item type. The term "item type" classifies a feed based on the type of information it includes. View a complete list of our item types.
You are required to use as many relevant attributes as are specific to your item type. Supplying additional information about your items by using these attributes will greatly increase your items' chances of showing up in search results. In addition, many attributes defined in the Google Base namespace can be used more than once within a single item. This enables you to add more available information about an item in your feed.
Section 3: Creating Custom Attributes
For cases where attributes defined in the Google Base namespace are not appropriate or don't quite match up with the information you'd like to include, simply create your own. The custom attributes you define can be used in addition to the attributes and elements defined in the Google Base and Atom 0.3 namespaces.
In the following example, we've taken the sample we extended earlier and added a few custom attributes:
<?xml version="1.0"?> <feed version="0.3" xmlns="http://purl.org/atom/ns#" xmlns:g="http://base.google.com/ns/1.0" |
The major additions in this example are the addition of a second namespace declaration (in the fourth line) and the special formatting of the custom attribute tags (language_skills, prior_experience_years, and start_date).
Custom Namespace DeclarationThe following namespace declaration is required in order to use custom attributes not already defined in the Atom 0.3 or the Google Base namespaces:
xmlns:c="http://base.google.com/cns/1.0"In addition to declaring the Google Base custom namespace, you must also include a prefix in both of the attribute tags. In this case we selected "c" as the prefix for our custom attributes. It is important to remember that the prefix selected in the namespace declaration must always match the prefix in your custom attribute tags.
<c:language_skills type="string">Fluent in English and German</c:language_skills>Attributes in the Google Base custom namespace must include this prefix or the attributes, and any values they contain, will be ignored.
Formatting Custom AttributesCustom attributes also need to be formatted in a certain way to allow us to recognize them. The format of a custom attribute can be broken down into the following values:
<[prefix]:[attribute_name] type="[content_type]">[value]</[prefix]:[attribute_name]>To illustrate how this format should be used, please view the example below:
<c:language_skills type="string">Fluent in English and German</c:language_skills>For more details about the values and examples of formatting custom attributes, please visit the Custom Attributes XML Namespace Module.
Section 4: Important Checklist
Before you submit your feed, we highly recommend running through the following list to help ensure your file is properly formatted:
- Your filename must end with the .xml extension.
- The feed filename you register in your Google Base account must match the name you assign to your file.
- Remember to include namespace declarations: xmlns:g="http://base.google.com/ns/1.0" and xmlns:c="http://base.google.com/cns/1.0"
- Verify the prefix included in the Google Base and Custom Google Base attribute tags matches the prefix defined in the namespace declaration.
- Remove attributes that do not contain any values.
Section 5: Final Note
The sample entry included in this document was simplified to allow for clearer focus on the basics of constructing a Google Base XML data feed. While we accept feeds containing other elements defined in the Atom 0.3 standard or in your own namespace, any information these elements contain will be ignored during processing and will not appear in your listings. At this time we will only process data contained in the default Atom 0.3 elements and in attributes within the Google Base and Custom Google Base namespaces.