Creating a new search engine

Instead of creating a new search engine from scratch, it is faster to create one from a context file. There is one in the GitHub repo named cse.xml.

A context file can be uploaded in the Advanced tab under 'Search engine context'.

> Context: Defining a Programmable Search Engine on Google

Hiding Ads

To hide ads on the search results page, a Google Workspace / G-Suite superadmin must be added in the search engine Users tab and set as Administrator. Within a few days of doing so, Google will recognize the search engine as part of a non-profit / education institution. When that happens, the Show Ads toggle in the Ads tab can be switched to 'off'.

> Information for non-profits on Google

Promotions

Google is very temperamental with regard to promotions. If you attempt to manage them using the Google Programmable Search admin interface, things may get mixed up, particularly the order in which they appear. Because we have sooooo many, it's important to maintain order so that any particular promotion is more easily findable.

Deleting a promotion

This in the only use case where it is safe to use the Google Programmable Search admin interface. Delete away!

Adding / modifying a promotion

Do not use the Google Programmable Search admin interface for these tasks. Instead....

Export a promotions.xml file in the Promotions tab of the Search Features area.
Make the desired edits to the xml file offline
Upload the modified file

Promotion attributes

Note: all attribute values require special character to be encoded (e.g., & instead of &)

Attribute	Purpose	Value
id	Uniquely identifies the promotion and makes it distinct from other promotions. The value is used for sorting the list of promotions in the Google Programmable Search admin interface.	Same value as title, but all lower case. Spaces are fine here. Replace all ampersand "&" and slash "/" characters with underscore "_".
title	The promotion's title, displayed in search results.	Human-readable. Normal casing and punctuation. Note - Sep 13, 2024 When importing from xml, Google will omit any promotions that include "&", ">", or "<" entities in the title attribute – even though these may have been included in an xml export. Replace these entities with non-special characters (e.g., replace "&" with "and") for the purposes of xml import. You can change each back to the desired entity after import using the Google interface.
queries	Triggers the display of a promotion is used an a search phrase.	Comma-separated list of phrases.
url	The link destination of the promotion.	Complete web address, including http(s)://

Reordering promotions

Export a promotions.xml file in the Promotions tab of the Search Features area.
Download the promotions processor script from the repo.
Run the script with the promotions.xml file in the same directory
Delete all promotions from the search engine in question using the Google Programmable Search admin interface. This may take a lot of clicks.
Upload the promotions-processed.xml file generated by the processor script to the search engine using the Google Programmable Search admin interface.

Browser not supported