### Getting Started

Source: https://developers.google.com/custom-search/docs/overview_hl=ko

Instructions on how to get started with Programmable Search Engine by creating a basic search engine and customizing it.

```APIDOC
## Getting Started

The easiest way to get started with Programmable Search Engine is to create a basic search engine using the control panel. You can then download the key XML files that you need to modify to customize your search engine programmatically.
```

--------------------------------

### Example Promotion Element - XML

Source: https://developers.google.com/custom-search/docs/promotions_hl=zh-cn

An example of a fully defined Promotion element within a Promotions tag. This demonstrates how to structure a promotion with various attributes.

```xml
<Promotions>
  <Promotion id="AmericanGraphics0001"
    queries="american born chinese, American Born Chinese, abc, ABC"
    title="American Born Chinese"
    url="http://books.google.com/books?id=vawdZyrDw64C&dq=american+
    Chinese+gene+yang"
    description="Graphic novel. First-person account of growing up Asian
    American by Gene Luen Yang."
    image_url="http://146.74.224.231/archives/Gene%20Yang.jpg" />
</Promotions>
```

--------------------------------

### Setup for Word Cloud

Source: https://developers.google.com/custom-search/docs/more_examples

This section includes the necessary HTML and CSS to set up the search elements and style the word cloud container. It also loads the AnyChart JavaScript libraries required for creating the tag cloud visualization. This setup is essential for the JavaScript callback to function correctly.

```html
<script async
      src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<style>
  #container {
    width: 100%;
    height: 4.5in;
    margin: 0;
    padding: 0;
  }
</style>
<script src="https://cdn.anychart.com/releases/v8/js/anychart-base.min.js"></script>
<script src="https://cdn.anychart.com/releases/v8/js/anychart-tag-cloud.min.js"></script>
```

--------------------------------

### Search Starting Callback Example for Programmable Search Engine

Source: https://developers.google.com/custom-search/docs/more_examples

This example demonstrates how to use a 'search starting' callback to modify a search query before it is executed. It appends the current day of the week to the user's query. This callback can be used to dynamically alter search terms based on available information. It requires the Programmable Search Engine integration script and specific HTML elements for search box and results.

```javascript
const mySearchStartingCallback = (gname, query) => {
  const dayOfWeek = new Date().getDay();
  console.log(dayOfWeek);
  var days = {
        "0": "Sunday",
        "1": "Monday",
        "2": "Tuesday",
        "3": "Wednesday",
        "4": "Thursday",
        "5": "Friday",
        "6": "Saturday"
    };

    return query + ' ' + days[dayOfWeek];
};
// Install the callback.
window.__gcse || (window.__gcse = {});
  window.__gcse.searchCallbacks = {
    image: {
      starting: mySearchStartingCallback,
    },
    web: {
      starting: mySearchStartingCallback,
    },
};

```

```html
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

```

--------------------------------

### Basic XML Facet Item Example

Source: https://developers.google.com/custom-search/docs/refinements_hl=zh-cn

A simple example of an XML facet structure for a Programmable Search Engine. This snippet demonstrates a single `Facet` containing a `FacetItem` with a `Label` configured to boost search results.

```xml
<Facet>
  <FacetItem title="Lectures">
    <Label name="lectures" mode="BOOST" weight="0.8"/></Label>
  </FacetItem>
</Facet>
```

--------------------------------

### Search Starting Callback Example (JavaScript)

Source: https://developers.google.com/custom-search/docs/element_hl=zh-cn

An example of a searchStartingCallback that appends 'morning' or 'afternoon' to the query based on the current hour. This demonstrates how to dynamically alter search queries.

```javascript
const myWebSearchStartingCallback = (gname, query) => {
  const hour = new Date().getHours();
  return query + (hour < 12 ? ' morning' : ' afternoon');
};
window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;
```

--------------------------------

### Example of Correct XML Element and Attribute Usage

Source: https://developers.google.com/custom-search/docs/basics_hl=it

Shows the correct way to define XML elements with attributes, emphasizing that attributes must be within the opening tag and enclosed in double quotes. This ensures proper parsing by the Programmable Search Engine.

```XML
<Context> </Context>
<LookAndFeel> </LookAndFeel>
<element attribute="value">content</element>
```

--------------------------------

### Full API Resource Response Example

Source: https://developers.google.com/custom-search/v1/performance_hl=es-419

This is an example of a full API response, typically returned when no specific fields are requested. It includes various fields, demonstrating the data that would be transferred without optimization.

```json
{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}
```

--------------------------------

### Image/Web Search - Registering Starting Callback in __gcse Object

Source: https://developers.google.com/custom-search/docs/element

Shows how to register a search starting callback by assigning a function to the '__gcse.searchCallbacks.web.starting' property. This allows dynamic addition or overriding of the callback function.

```javascript
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
```

--------------------------------

### Search Starting Callback Example - JavaScript

Source: https://developers.google.com/custom-search/docs/more_examples_hl=bn

This example demonstrates how to use a 'search starting' callback to modify a search query before it's executed. The callback appends the current day of the week to the query. It requires the Custom Search Element API to be included via a script tag.

```html
<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:g9ckaktfipe"></script>
```

```javascript
const mySearchStartingCallback = (gname, query) => {
  const dayOfWeek = new Date().getDay();
  console.log(dayOfWeek);
  var days = {
        "0": "Sunday",
        "1": "Monday",
        "2": "Tuesday",
        "3": "Wednesday",
        "4": "Thursday",
        "5": "Friday",
        "6": "Saturday"
    };

    return query + ' ' + days[dayOfWeek];
};
// Install the callback.
window.__gcse || (window.__gcse = {});
  window.__gcse.searchCallbacks = {
    image: {
      starting: mySearchStartingCallback,
    },
    web: {
      starting: mySearchStartingCallback,
    },
};

```

```html
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
```

--------------------------------

### Como comentar código XML no Mecanismo de Pesquisa Programável

Source: https://developers.google.com/custom-search/docs/basics_hl=pt-br

Mostra como usar tags de comentário XML (`<!-- -->`) para adicionar notas ou desativar temporariamente o código XML em arquivos de configuração do Mecanismo de Pesquisa Programável. Observe que esses comentários não são preservados nos arquivos baixados do Painel de Controle.

```xml
<!-- Este é um comentário. Esta linha não será analisada como código XML. -->
<!-- <element attribute="value">Conteúdo</element> -->
```

--------------------------------

### XML Syntax and Structure for Programmable Search Engine

Source: https://developers.google.com/custom-search/docs/basics_hl=it

Demonstrates the basic syntax and structure required for XML files used in Programmable Search Engine configuration. It covers element pairing, correct nesting, and attribute formatting, crucial for valid configuration.

```XML
<?xml version="1.0"?>
<sandwich>
  <filling>peanut butter</filling>
</sandwich>
```

--------------------------------

### GET /demo/v1

Source: https://developers.google.com/custom-search/v1/performance

Demonstrates how to use the 'fields' parameter to request a partial response from the Demo API.

```APIDOC
## GET /demo/v1

### Description
This endpoint allows fetching resources from the Demo API. The `fields` query parameter can be used to limit the data returned in the response.

### Method
GET

### Endpoint
`/demo/v1`

### Query Parameters
- **fields** (string) - Optional - Specifies a subset of fields to include in the response. Supports comma-separated values, nested field selection (e.g., `a/b/c`), and sub-selectors for arrays/objects using parentheses (e.g., `items(title,characteristics/length)`). Wildcards (`*`) can also be used.

### Request Example
```json
GET https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
```

### Response
#### Success Response (200)
- **kind** (string) - The type of the returned resource.
- **items** (array) - A list of items, where each item contains the requested fields.
  - **title** (string) - The title of the item.
  - **characteristics** (object) - An object containing characteristics of the item.
    - **length** (string) - The length characteristic of the item.

#### Response Example
```json
{
  "kind": "demo",
  "items": [
    {
      "title": "First title",
      "characteristics": {
        "length": "short"
      }
    },
    {
      "title": "Second title",
      "characteristics": {
        "length": "long"
      }
    }
  ]
}
```
```

--------------------------------

### Basic REST API Request Example

Source: https://developers.google.com/custom-search/v1/using_rest

An example of a GET request to the Custom Search JSON API. This demonstrates the required parameters: API key, Programmable Search Engine ID (cx), and the search query (q).

```http
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures
```

--------------------------------

### XML Example of a Fully Configured Promotion Element

Source: https://developers.google.com/custom-search/docs/promotions_hl=ja

This XML snippet demonstrates a complete `<Promotion>` element with all essential attributes defined. It includes `id`, `queries`, `title`, `url`, `description`, and `image_url` to showcase how a promotion is set up for a specific search query.

```xml
<Promotions>
  <Promotion id="AmericanGraphics0001"
    queries="american born chinese, American Born Chinese, abc, ABC"
    title="American Born Chinese"
    url="http://books.google.com/books?id=vawdZyrDw64C&dq=american+born+
    Chinese+gene+yang"
    description="Graphic novel. First-person account of growing up Asian
    American by Gene Luen Yang."
    image_url="http://146.74.224.231/archives/Gene%20Yang.jpg" />
</Promotions>
```

--------------------------------

### JavaScript: Alert on Last Results Page with Results Rendered Callback

Source: https://developers.google.com/custom-search/docs/more_examples_hl=zh-tw

The 'results rendered' callback can modify how search results are displayed after they are populated. This example triggers an alert when the user reaches the last page of search results. It requires the CSE JS and the callback installation.

```html
<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
```

```javascript
myWebResultsRenderedCallback = function(){
    var searchresults= document.getElementsByClassName("gsc-cursor-page");
    var index= document.getElementsByClassName("gsc-cursor-current-page");
    if(index.item(0).innerHTML == searchresults.length){
       alert("This is the last results page");
    }
};

```

```javascript
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
      // Since the callback is in the global namespace, we can refer to it by name,
      // 'myWebResultsRenderedCallback', or by reference, myWebResultsRenderedCallback.
      rendered: myWebResultsRenderedCallback,
  },
};

```

```html
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
```

--------------------------------

### XML Basic Structure and Syntax

Source: https://developers.google.com/custom-search/docs/basics_hl=es-419

Demonstrates the fundamental structure and syntax rules of XML, including element nesting, case sensitivity, and attribute formatting. This is crucial for creating well-formed Programmable Search Engine configuration files.

```xml
<sandwich>
  <filling> peanut butter</filling>
</sandwich>
```

```xml
<element attribute="value">content</element>
```

--------------------------------

### GET /customsearch/v1

Source: https://developers.google.com/custom-search/v1/performance

This example demonstrates how to use the `fields` parameter to retrieve specific fields from the Custom Search API response.

```APIDOC
## GET /customsearch/v1

### Description
This endpoint allows you to search for content using the Google Custom Search engine. The `fields` query parameter can be used to limit the response to a subset of fields, improving efficiency.

### Method
GET

### Endpoint
/customsearch/v1

### Parameters
#### Query Parameters
- **fields** (string) - Required - Specifies a subset of fields to return in the response. Fields are comma-separated and can include nested fields using '/' and wildcards using '*'. Sub-selections can be made using `( )`.
- **q** (string) - Required - The query string to search for.

### Request Example
```json
{
  "example": "https://www.googleapis.com/customsearch/v1?q=google&fields=kind,items(title,link)"
}
```

### Response
#### Success Response (200)
- **kind** (string) - The type of the resource. This is always customsearch#search.
- **items** (array) - The search results.
  - **title** (string) - The title of the search result.
  - **link** (string) - The URL of the search result.

#### Response Example
```json
{
  "kind": "customsearch#search",
  "items": [
    {
      "title": "Google",
      "link": "https://www.google.com/"
    },
    {
      "title": "Google",
      "link": "https://www.google.com/search?q=google"
    }
  ]
}
```

#### Error Response (400)
- **error** (object) - Contains error details.
  - **code** (integer) - The error code.
  - **message** (string) - A description of the error. Example: "Invalid field selection specified."

```

--------------------------------

### JavaScript and CSS Setup for Word Cloud

Source: https://developers.google.com/custom-search/docs/more_examples_hl=id

This section includes the necessary JavaScript and CSS to enable the word cloud functionality. It loads the Google Custom Search engine script, defines styles for the chart container, and includes the AnyChart base and tag cloud libraries. This setup is crucial for the `resultsReadyWordCloudCallback` to function correctly.

```html
<script async
      src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<style>
  #container {
    width: 100%;
    height: 4.5in;
    margin: 0;
    padding: 0;
  }
</style>
<script src="https://cdn.anychart.com/releases/v8/js/anychart-base.min.js"></script>
<script src="https://cdn.anychart.com/releases/v8/js/anychart-tag-cloud.min.js"></script>

```

--------------------------------

### JavaScript: Increase Font Size of Cursor Links with Results Rendered Callback

Source: https://developers.google.com/custom-search/docs/more_examples_hl=zh-tw

This 'results rendered' callback example demonstrates increasing the font size of the 'cursor' links. The default font size is 12px, and this code changes it to 20px. It requires the CSE JS and the callback installation.

```html
<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
```

```javascript
myWebResultsRenderedCallback = function(){
   document.getElementsByClassName("gsc-cursor")[0].style.fontSize = '20px';
};

```

```javascript
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
      // Since the callback is in the global namespace, we can refer to it by name,
      // 'myWebResultsRenderedCallback', or by reference, myWebResultsRenderedCallback.
      rendered: myWebResultsRenderedCallback,
  },
};

```

```html
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
```

--------------------------------

### GET /search (Regular/Advanced Search)

Source: https://developers.google.com/custom-search/docs/xml_results

This endpoint allows you to perform regular and advanced searches. You can specify search terms, number of results, and output format. The example demonstrates a search for 'socer' with specific parameters and returns an XML result.

```APIDOC
## GET /search (Regular/Advanced Search)

### Description
Performs a search query against the custom search engine. This endpoint supports various parameters to refine search results, including keywords, result quantity, and output format.

### Method
GET

### Endpoint
`/search`

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query string.
- **hl** (string) - Optional - Language of the user, which affects the translation dictionaries used.
- **start** (integer) - Optional - The result set to retrieve. Zero-based index.
- **num** (integer) - Optional - Number of search results to return per page.
- **output** (string) - Optional - The format of the output. e.g., 'xml', 'json'.
- **client** (string) - Optional - Specifies the calling application.
- **cx** (string) - Required - The custom search engine ID.

### Request Example
```
http://www.google.com/search?q=socer&hl=en&start=10&num=10&output=xml&client=google-csbe&cx=00255077836266642015:u-scht7a-8i
```

### Response
#### Success Response (200)
- **GSP** (object) - The root element for the search results.
  - **TM** (string) - Time taken for the query.
  - **Q** (string) - The original query.
  - **PARAM** (array) - Parameters used in the query.
  - **Spelling** (object) - Contains spelling suggestions if any.
  - **Context** (object) - Search context information.
  - **RES** (object) - The search results container.
    - **SN** (string) - Start number of the results.
    - **EN** (string) - End number of the results.
    - **M** (string) - Number of results found.
    - **FI** (object) - Indicates filtered results.
    - **NB** (object) - Navigation information for previous results.
    - **R** (array) - An array of individual search results.
      - **N** (string) - Result number.
      - **U** (string) - URL of the result.
      - **UE** (string) - Escaped URL of the result.
      - **T** (string) - Title of the result.
      - **CRAWLDATE** (string) - Date the page was crawled.
      - **S** (string) - Snippet of the search result.
      - **Label** (array) - Labels associated with the result.
      - **LANG** (string) - Language of the result.
      - **HAS** (object) - Content details.

#### Response Example
```xml
<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?>
<GSP VER="3.2">
   <TM>0.452923</TM>
   <Q>socer</Q>
   <PARAM name="cx" value="00255077836266642015:u-scht7a-8i" original_value="00255077836266642015%3Au-scht7a-8i"/>
   <PARAM name="hl" value="en" original_value="en"/>
   <PARAM name="q" value="socer" original_value="socer"/>
   <PARAM name="output" value="xml" original_value="xml"/>
   <PARAM name="client" value="google-csbe" original_value="google-csbe"/>
   <PARAM name="num" value="10" original_value="10"/>
   <Spelling>
      <Suggestion q="soccer"><b><i>soccer</i></b></Suggestion>
   </Spelling>
   <Context>
      <title>Sample Vacation CSE</title>
      <Facet>
         <FacetItem>
            <label>restaurants</label>
            <anchor_text>restaurants</anchor_text>
         </FacetItem>
         <FacetItem>
            <label>wineries</label>
            <anchor_text>wineries</anchor_text>
         </FacetItem>
      </Facet>
   </Context>
   <RES SN="1" EN="10">
      <M>6080</M>
      <FI />
      <NB>
         <NU>/search?q=socer&amp;hl=en&amp;lr=&amp;ie=UTF-8&amp;output=xml&amp;client=test&amp;start=10&amp;sa=N</NU>
      </NB>
      <R N="1">
         <U>http://www.soccerconnection.net/</U>
         <UE>http://www.soccerconnection.net/</UE>
         <T>SoccerConnection.net</T>
         <CRAWLDATE>May 21, 2007</CRAWLDATE>
         <S><b>soccer</b>; players; coaches; ball; world cup;<b>...</b></S>
         <Label>transcodable_pages</Label>
         <Label>accessible</Label>
         <Label>soccer_sites</Label>
         <LANG>en</LANG>
         <HAS>
            <DI>
               <DT>SoccerConnection.net</DT>
               <DS>Post your <b>soccer</b> resume directly on the Internet.</DS>
            </DI>
            <L/>
            <C SZ="8k" CID="kWAPoYw1xIUJ"/>
            <RT/>
         </HAS>
      </R>
   </RES>
</GSP>
```
```

--------------------------------

### Exemplo de Sintaxe XML para Mecanismo de Pesquisa Programável

Source: https://developers.google.com/custom-search/docs/basics_hl=pt-br

Demonstra a sintaxe básica de tags XML, atributos e valores, conforme usado em arquivos de configuração do Mecanismo de Pesquisa Programável. Inclui exemplos de tags de elemento e atributos com valores entre aspas duplas.

```xml
<Context>
  <!-- Seu conteúdo de contexto aqui -->
</Context>
<LookAndFeel>
  <!-- Suas configurações de aparência aqui -->
</LookAndFeel>
```

--------------------------------

### Load Programmable Search Engine with JavaScript

Source: https://developers.google.com/custom-search/docs/more_examples_hl=fa

This script tag asynchronously loads the Google Programmable Search Engine. The `cx` parameter is essential for initializing your specific search engine configuration. This should be included in your HTML to enable the search functionality.

```html
<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:g9ckaktfipe"></script>

```

--------------------------------

### Example of Search Starting Callback in JavaScript

Source: https://developers.google.com/custom-search/docs/more_examples_hl=hi

This JavaScript callback modifies the search query by appending the current day of the week. It's useful for personalizing search results based on temporal context. The callback function `mySearchStartingCallback` takes `gname` and `query` as arguments and returns the modified query.

```javascript
const mySearchStartingCallback = (gname, query) => {
  const dayOfWeek = new Date().getDay();
  console.log(dayOfWeek);
  var days = {
        "0": "Sunday",
        "1": "Monday",
        "2": "Tuesday",
        "3": "Wednesday",
        "4": "Thursday",
        "5": "Friday",
        "6": "Saturday"
    };

    return query + ' ' + days[dayOfWeek];
};
// Install the callback.
window.__gcse || (window.__gcse = {});
  window.__gcse.searchCallbacks = {
    image: {
      starting: mySearchStartingCallback,
    },
    web: {
      starting: mySearchStartingCallback,
    },
};
```

--------------------------------

### Implement Search Engine Labels in Context File

Source: https://developers.google.com/custom-search/docs/ranking

This example illustrates the implementation of search engine labels within the context file. It includes 'BackgroundLabels' for including or eliminating sites and demonstrates 'Label' elements with 'name' and 'mode' attributes.

```xml
<!--Search engine labels-->
<BackgroundLabels>
  <Label name="_include_" mode="FILTER"/>
  <Label name="_exclude_" mode="ELIMINATE"/>
<lt;/BackgroundLabels>
```

--------------------------------

### Search Starting Callback Example for Programmable Search Engine

Source: https://developers.google.com/custom-search/docs/more_examples_hl=he

This JavaScript code defines a callback function that modifies a search query by appending the current day of the week. It's designed to be used with Google's Programmable Search Engine to personalize search results based on the day.

```javascript
const mySearchStartingCallback = (gname, query) => {
  const dayOfWeek = new Date().getDay();
  console.log(dayOfWeek);
  var days = {
        "0": "Sunday",
        "1": "Monday",
        "2": "Tuesday",
        "3": "Wednesday",
        "4": "Thursday",
        "5": "Friday",
        "6": "Saturday"
    };

    return query + ' ' + days[dayOfWeek];
};
// Install the callback.
window.__gcse || (window.__gcse = {});
  window.__gcse.searchCallbacks = {
    image: {
      starting: mySearchStartingCallback,
    },
    web: {
      starting: mySearchStartingCallback,
    },
};

```