Google Commerce Search Deployment Guide September 2011 © 2011 Google 1
Deployment Guide This guide is meant to answer many common questions about Google Commerce Search (GCS). About this document The recommendations and information in this document were gathered through our work with a variety of clients and environments in the field. We thank our customers and partners for sharing their experiences and insights. What’s covered This guide provides some general guidance and best practices around Google Commerce Search.
Contents About this document Chapter 1 Understanding Your Deployment Administration APIs Console Deployment Chapter 2 Merchant Center, Feeds and Content API Structuring your content Chapter 3 The GCS Control Panel Admin accounts Automating admin tasks Chapter 4 The Search API for Shopping Request format Response format Chapter 5 GCS Stats and Analytics GCS Statistics page API Console Traffic Reports Google Analytics integration Appendix A Limits Items in general Feed Size Content API Limit Search Limit Appe
Chapter 1 Understanding Your Deployment Google Commerce Search (GCS) is a hosted search product--a web service that can provide search results on your web site. You have complete control over the look and feel of the user interface, as well as the ability to pick and choose which features to enable.
panel does allow additional accounts to be added for access, so sharing credentials shouldn’t be needed. APIs Console The APIs Console (https://code.google.com/apis/console/) is a third tool used in conjunction with GCS. To use GCS, you must have an API key--many Google services rely on developer keys to control access. A key for the “Search API for Shopping” is required when creating your GCS instance.
2. Formats a request for the Google Shopping API based on the keywords and any other parameters specified in the search request 3. Sends the Request to Google 4. Receives the Shopping API response from Google 5. Parses the Response 6. Applies any HTML or CSS styles to the results Results are displayed in the user’s browser. While it might sound like a lot of work, this all happens in under a second, in most cases.
Chapter 2 Merchant Center, Feeds and Content API Unlike Google Site Search, which uses the Google crawler (googlebot) to index your site, GCS builds its index from content that is directly fed or “pushed” to Google. In most cases, you might already be feeding some of your product data to Google through Merchant Center, for Google Product Search (formerly called “Froogle”). This product feed can also be shared with Google Commerce Search.
A typical GCS data feed might contain the following attributes for most items: Attribute Type Description id required Think of id as your primary key. This has to be a unique identifier. It doesn’t have to be a number - it can be a SKU or product id. link required The URL of the item. title required Product Title, up to 70 characters. description required Product Description, up to 10K characters Almost exclusively used for search, not display, so formatting is typically not that important.
Merchant Center overview The Merchant Center console enables you to specify and upload feeds to Google Product Search and Google Commerce Search. It also provides some diagnostics and reporting for your feeds and product data. Typically, you won’t need to log in to Merchant Center much once your feeds are submitted and working properly.
an item level instead of the entire feed. Destination Name API Name Description Google Product Search ProductSearch Your products will appear on Google Product Search (Set by default). Product Ads ProductAds You can use your product data to highlight your products in your Google.com search ads. Learn more. Commerce Search CommerceSearch You can use your product data for our new service which utilizes Google's search technology to power your own retail site. Learn more.
regular feeds, but the items are not inserted into the index. If there are errors, you will see them on the feed status page. The test feeds are a good way to work out any issues with your formatting when adding any new fields to the feed. Once the feed submits without error you should be able to submit a production feed without problem. Product status and data quality One your feed has been processed, new items are added to the index and updates to existing items occur.
The Data Quality tab appears. Content API for Shopping The Content API for Shopping lets you programmatically manage your catalog instead of relying on a feed file. It allows for much greater control of your products where you can selectively set usecases, inventory, expire products, delete and update items. It offers much more flexibility and provides item-by-item feedback if a particular operation (insert/update/delete) succeeded or failed.
XML is transmitted as the payload. For example operations, see the Content API docs or the GCS Docs for Feeds. Unlike feed files, you must explicitly issue delete commands for a given item to remove it from the inventory. With feed files, if an item is not present in subsequent feed files, it is considered void and is deleted from GCS tables. With the ContentAPI, an item remains in the GCS tables for a default 30 days unless it is explicitly deleted.
Chapter 3 The GCS Control Panel This chapter doesn’t comprehensively document all the features in the control panel, rather it highlights some best practices and specific use cases relative to the control panel. For complete information, see: ● ● GCS Configuration pages: http://code.google.com/apis/commercesearch/docs/ gcsconfiguration.html Context-sensitive help within the control panel Admin accounts There can be only one owner of a GCS instance associated with a single Google account.
the control panel. To see examples of the XML: 1. Create some rules manually. 2. Download the resulting XML. 3. Open the XML into your favorite editor, or have a script generate more XML in the same format. Admin API The GCS control panel shares the same API as CSE (Custom Search Engine), and most of the functionality within the control panel can be accessed programmatically using this API. The CSE API is documented at http://code.google.com/intl/en/apis/customsearch/docs/api.html.
< Set-Cookie: PREF=ID=4debb263401e6f34:TM=1304988036:LM=1304988036:S=XPruSwy4M_04MWrI; expires=Thu, 09-May-2013 00:40:36 GMT; path=/; domain=.google.com < X-Content-Type-Options: nosniff < Server: pfe < X-XSS-Protection: 1; mode=block < X-Google-Backends: /bns/ia/borg/ia/bns/prose-team/prose.frontend/1,pvd39:80 < X-Google-GFE-Request-Trace: pvd39:80,/bns/ia/borg/ia/bns/prose-team/prose.
Chapter 4 The Search API for Shopping The Search API for Shopping (Shopping API) is what allows you to search the products fed into Merchant Center. The Shopping API is typically implemented in server-side code (Java, php, .Net, and so on) which takes a user’s search query, makes an API call to Google, and gets the search results back--presenting them to the user.
one country in one language and one currency per request. There are two other parameters, alt and q, that are not required, but are typically passed in all API requests. The alt parameter specifies the result format either alt=atom or alt=json can be specified to return results in either XML (atom) or JSON format. The q parameter is used for full text search--terms in the q parameter are matched against all properties of all items in your feed.
● ● Spelling Recommendations Each module is enabled with the module-name.enabled parameter. Each also has another parameter, module-name.useGcsConfig, which when set to true, specifies that you want to use the configuration for that module as set in the GCS Control Panel. Some modules also have other parameters to control the results. For more details, see the content modules documentation at http://code.google.com/apis/shopping/search/v1/reference-content-modules.
● ● Specifying multiple values Specifying multiple facets Specifying multiple values You can allow users to choose multiple values with an OR operator. This will return items with either color=Red OR color=Green: &restrictBy=color(text)=Red|Green This is implemented when you allow users to check multiple values for a refinement. Specifying multiple facets Refinements are additive, so if you specify multiple restrictBy fields they will be ANDed.
Category breadcrumbs (parents of current category) can be returned by way of the category module. For more information, see: http://code.google.com/apis/commercesearch/docs/browse.html#breadcrumbs Response format The Shopping API returns results in XML (Atom) or JSON format. This is controlled with the alt parameter (alt=atom or alt=json). Most of our example code uses XML because XML makes for better human-readable examples, but the choice for your own implementation is up to you.
XML: &fields=openSearch:*,s:facets,entry(title,s:product/ s:attributes,s:product/s:providedId,s:product/s:link) Use the attributeFilter parameter to specify which of an item’s attributes you need: &attributeFilter=name(text),thumbnail(text),product+review+average(flo at),condition(text),price(float),brand(text) Best Practice: Limit the number of results returned for your default searches.
Chapter 5 GCS Stats and Analytics Google Analytics (GA) is the preferred method for analyzing GCS performance on your site, although you can use any third-party analytics package. Google Analytics does require some additional configuration, but before we look at implementing GA there are a few ways to get some basic GCS statistics without any extra code. GCS Statistics page The GCS Statistics page within the control panel provides very basic statistics.
These numbers do take into account SAYT and Autocompletion queries, which are not counted towards yearly GCS quota. API Console Traffic Reports Another place to find some usage statistics is in the Traffic Reports section of the API console: https://code.google.com/apis/console/ To view the Traffic Reports, click the Search API for Shopping link (should show a status of “ON”). This graph simply shows the total number of API requests for the given time period.
● ● ● ● Percentage of visitors that used search Percentage of searches that were refined Number of pageviews per search Percentage of search exits But wait, that’s not all! Even more important is seeing how well GCS usage results in conversions. Typically this means a sale, but you could also set up other goals such as a lead generated, or contact request initiated. So, if you’re not already tracking e-commerce conversions, you should be.
_gaq.push(['_setCustomVar', 1, 'ZeroResults', '', 3]); This creates a custom variable named “ZeroResults” and you’ll get a report of all the query terms under Visitors > Custom Variables. It’s not unusual to have quite a few zero results queries, but they should be a relatively small percentage of your total queries. You also want to be on the lookout for a large number of the same query terms.
tracking parameters--something like ?gaclick=promo--to the end of the URL. Now you have the ability to generate a report that shows how many times a promotion link was clicked. Navigation/Browse typically doesn’t need extra tracking parameters in the URL to report on Navigation usage (separate from search), unless you are using the same URL for site search and navigation. Although the URL parameter method is easy, it’s not always recommended.
Appendix A Limits Items in general Items automatically get deleted in 30 days. As a result, in order to remain in the index, each item needs to be refreshed once every 30 days.
Appendix B GCS Launch Checklist Customer Name: Production CX: Merchant Center ID: API Key: SAYT API Key: Merchant ID in Whitelist Visible Usecases & Category Feed Enabled in ICS GCS Account Properly Provisioned Quota set for API Key(s) API Per-User-Limit (set in API Console “Traffic Controls”) Whitelist for any Labs features Support Portal account active 29
