This document describes some of the best practices around using the CSS API. The advice given on this page is not mandatory to use the API, but may help clarify some of the intended use.
Setup up your environment
To setup your development environment, follow the steps given from the Quickstart documentation.
- Generate a user and a permissions JSON file on the Google Cloud Console
- Enable the CSS API in the Google Cloud Console
- Add that user with Admin permissions to your CSS Account (group or domain)
Client libraries are now in the standard repositories for most programming language. You can find a list of them on our client library page.
Good methods to get started
We recommend testing with the following methods:
ListChildAccounts
ListChildAccounts is a read-only call that lists all of your CSS Domains (if called for a CSS Group) or your Merchants (if called for a CSS Domain). It is therefore a good method to test if everything is setup correctly.
Insert/List/Update/Delete a product
Once you know that the API itself works, try adding a product. Make sure you use
a raw_provided_id that you remember.
- Insert a test product using InsertCssProductInput. We have sample code if you need help on which attributes to send.
- List all of your products using ListCssProducts. There is a small processing delay before a product shows up after insertion, so if you don't see it, try again after a few seconds.
- Update a single product using
UpdateCssProductInput
using your
cssproductinput.name. You need to send only the attributes required to be updated. Refer to sample code here. - Delete the test product using
DeleteCssProductInput.
You will need to use the
raw_provided_id.
Use Async to improve performance
The CSS API is designed for parallel calls. You will find that the performance of single operations can be slow, but will be much faster when calling the same operation multiple times in parallel. The best way to use this feature is to use the async functionality of your programming language.
Examples from some programming languages:
- For Java, use insertCssProductInputCallable().futureCall()
- For Python, use CssProductInputsServiceAsyncClient
- For C#, use InsertCssProductInputAsync
Find and use the Async functionality of your programming language to insert multiple products at the same time. You don't need to worry about overloading our systems - this is what the quota limits are for.
More details can be found on our performance page.
Update a product
Once a product is uploaded, it will stay in our system until it is either updated, deleted, or expired.
- You can update the full product by sending the
InsertCssProductInputrequest again, using the sameraw_provided_idyou used initially. For now, you will need to send the full product data, even if only some attributes (maybe only price/availablibilty) have changed. - You can update parts of a product, using PATCH method
UpdateCssProductInput, specifying product name,and a JSON body containing the data you would like to update for the product. UnlikeInsertCssProductInput, that requires all applicable fields to be provided,UpdateCssProductInputonly requires you to specify the fields you would like to change. - You can delete a product by calling
DeleteCssProductInputwith the sameraw_provided_id. - Products expire automatically approximately one month after the last update.
Continuous operation mode
A continuous operation mode could look like the following:
- Use your own internal IDs as
raw_provided_id. - Re-upload all products on a regular schedule, maybe weekly. This will ensure that active products don't expire.
- Update individual products as soon as you get the changed data from your
merchants.
- If you can't react to changes immediately, find all changed products frequently (maybe hourly) and re-upload only those products.
- For products which are no longer available, you can either use the delete call or set the number of available offers to 0.
- Don't send us unchanged products frequently. These calls would count against your API quota. A weekly refresh is sufficient.
Headline offer selection
The headline offer does not necessarily need to be the top offer or the cheapest offer on your site, but it does need to be featured prominently. You can use this for cases where your top offer is changing fast: Here you could select another offer which is more stable.
Re-Check this document every once in a while
We have received feedback on how to improve this API, and are working on making some of these improvements available. This page will be updated when we have new features available that will simplify the usage of the CSS API.