Build a Search Application with Google Custom Search

Building a search application with the Google Custom Search JSON API lets you embed Google-quality search directly into your product — scoped to specific domains, tuned to your audience, and fully under your control. This guide walks you through creating a Programmable Search Engine, wiring up a search input, calling the API when a user submits a query, and rendering results that include a title, snippet, and URL. You’ll finish with two complete working implementations: a standalone HTML/JavaScript single-page app and a Python Flask web application.

Prerequisites

Before you start, make sure you have the following:

A Google account to access the Google Cloud Console and the Programmable Search Engine control panel
An API key with the Custom Search JSON API enabled
A Search Engine ID (cx) from the Programmable Search Engine control panel
Basic familiarity with HTML/JavaScript or Python

If you haven’t created an API key yet, go to Google Cloud Console → APIs & Services → Credentials → Create Credentials → API key. Enable the Custom Search JSON API in the API Library before proceeding.

Step 1: Create and configure your Programmable Search Engine

Open the Programmable Search Engine control panel

Navigate to https://programmablesearchengine.google.com/ and sign in with your Google account. Click Add to create a new engine.

Scope the engine to a domain

In the Sites to search field, enter the domain you want to search. For example, to restrict results to a single documentation site, enter docs.example.com. You can add multiple domains or use a wildcard like *.example.com to include all subdomains.Give your engine a memorable name (for example, My Docs Search) and click Create.

Copy your Search Engine ID

After creation, click Control Panel on the confirmation screen. Under Basic, find the Search engine ID field and copy the value — this is your cx parameter. Keep it alongside your API key.

(Optional) Enable the entire web

If you want results from the whole web rather than specific sites, go to Control Panel → Basics and toggle Search the entire web to on. You can still pin or boost specific sites using the Sites panel.

Step 2: Understand the API request structure

Every search request is a GET to the base URL with your credentials and query:

GET https://www.googleapis.com/customsearch/v1
  ?key=YOUR_API_KEY
  &cx=YOUR_SEARCH_ENGINE_ID
  &q=YOUR_QUERY

The response contains a searchInformation object with metadata and an items array where each element represents one search result.

{
  "kind": "customsearch#search",
  "searchInformation": {
    "totalResults": "1430000",
    "searchTime": 0.32,
    "formattedSearchTime": "0.32",
    "formattedTotalResults": "1,430,000"
  },
  "items": [
    {
      "kind": "customsearch#result",
      "title": "Getting Started – Example Docs",
      "htmlTitle": "Getting <b>Started</b> – Example Docs",
      "link": "https://docs.example.com/getting-started",
      "displayLink": "docs.example.com",
      "snippet": "Learn how to set up your account and make your first API call in under five minutes.",
      "htmlSnippet": "Learn how to set up your account and make your first API call...",
      "formattedUrl": "https://docs.example.com/getting-started",
      "pagemap": {}
    }
  ]
}

The items array can contain up to 10 results per request. Use the num parameter (1–10) to reduce that count, and the start parameter to paginate through additional pages of results.

Step 3: Build the HTML/JavaScript application

The example below is a self-contained single HTML file. It renders a search input, calls the Custom Search API on form submission using the Fetch API, and displays results without any build tooling or dependencies. Replace YOUR_API_KEY and YOUR_SEARCH_ENGINE_ID with your actual values before opening the file in a browser.

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Custom Search App</title>
  <style>
    *, *::before, *::after { box-sizing: border-box; }

    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
      max-width: 720px;
      margin: 0 auto;
      padding: 2rem 1rem;
      color: #202124;
      background: #fff;
    }

    h1 { font-size: 1.5rem; margin-bottom: 1.5rem; }

    #search-form {
      display: flex;
      gap: 0.5rem;
      margin-bottom: 2rem;
    }

    #search-input {
      flex: 1;
      padding: 0.6rem 1rem;
      font-size: 1rem;
      border: 1px solid #dadce0;
      border-radius: 24px;
      outline: none;
    }

    #search-input:focus { border-color: #1a73e8; box-shadow: 0 0 0 2px #e8f0fe; }

    button[type="submit"] {
      padding: 0.6rem 1.4rem;
      font-size: 1rem;
      background: #1a73e8;
      color: #fff;
      border: none;
      border-radius: 24px;
      cursor: pointer;
    }

    button[type="submit"]:hover { background: #1558b0; }

    #status { color: #5f6368; font-size: 0.875rem; margin-bottom: 1rem; }

    .result { margin-bottom: 1.75rem; }

    .result-url {
      font-size: 0.8rem;
      color: #188038;
      margin-bottom: 0.2rem;
      white-space: nowrap;
      overflow: hidden;
      text-overflow: ellipsis;
    }

    .result-title {
      font-size: 1.1rem;
      color: #1a0dab;
      text-decoration: none;
      display: block;
      margin-bottom: 0.3rem;
    }

    .result-title:hover { text-decoration: underline; }

    .result-snippet { font-size: 0.9rem; color: #4d5156; line-height: 1.5; }

    #error { color: #c5221f; background: #fce8e6; padding: 0.75rem 1rem; border-radius: 4px; }

    .hidden { display: none; }
  </style>
</head>
<body>

  <h1>Search</h1>

  <form id="search-form">
    <input
      id="search-input"
      type="search"
      placeholder="Search docs.example.com…"
      autocomplete="off"
      required
    />
    <button type="submit">Search</button>
  </form>

  <p id="status" class="hidden"></p>
  <p id="error" class="hidden"></p>
  <div id="results"></div>

  <script>
    // ── Configuration ───────────────────────────────────────────────────────
    const API_KEY = 'YOUR_API_KEY';
    const SEARCH_ENGINE_ID = 'YOUR_SEARCH_ENGINE_ID';
    const BASE_URL = 'https://www.googleapis.com/customsearch/v1';

    // ── DOM references ───────────────────────────────────────────────────────
    const form = document.getElementById('search-form');
    const input = document.getElementById('search-input');
    const statusEl = document.getElementById('status');
    const errorEl = document.getElementById('error');
    const resultsEl = document.getElementById('results');

    // ── Helpers ──────────────────────────────────────────────────────────────

    /** Build the full API URL for a given query and optional start index. */
    function buildApiUrl(query, start = 1) {
      const params = new URLSearchParams({
        key: API_KEY,
        cx: SEARCH_ENGINE_ID,
        q: query,
        num: 10,
        start,
      });
      return `${BASE_URL}?${params}`;
    }

    /** Render a single search result item into an HTML string. */
    function renderResult(item) {
      return `
        <div class="result">
          <div class="result-url">${escapeHtml(item.displayLink)}</div>
          <a class="result-title" href="${escapeHtml(item.link)}" target="_blank" rel="noopener">
            ${item.htmlTitle}
          </a>
          <div class="result-snippet">${item.htmlSnippet}</div>
        </div>
      `;
    }

    /** Minimal HTML-escaping for attribute values. */
    function escapeHtml(str) {
      return str
        .replace(/&/g, '&amp;')
        .replace(/"/g, '&quot;')
        .replace(/</g, '&lt;')
        .replace(/>/g, '&gt;');
    }

    function showError(message) {
      errorEl.textContent = message;
      errorEl.classList.remove('hidden');
    }

    function clearError() {
      errorEl.textContent = '';
      errorEl.classList.add('hidden');
    }

    // ── Search logic ─────────────────────────────────────────────────────────

    async function performSearch(query, start = 1) {
      clearError();
      resultsEl.innerHTML = '';
      statusEl.textContent = 'Searching…';
      statusEl.classList.remove('hidden');

      try {
        const response = await fetch(buildApiUrl(query, start));

        if (!response.ok) {
          const data = await response.json().catch(() => ({}));
          const message = data?.error?.message || `HTTP ${response.status}`;
          throw new Error(message);
        }

        const data = await response.json();

        if (!data.items || data.items.length === 0) {
          statusEl.textContent = 'No results found.';
          return;
        }

        const total = parseInt(data.searchInformation.totalResults, 10).toLocaleString();
        const time = data.searchInformation.formattedSearchTime;
        statusEl.textContent = `About ${total} results (${time} seconds)`;

        resultsEl.innerHTML = data.items.map(renderResult).join('');

      } catch (err) {
        statusEl.classList.add('hidden');
        showError(`Search failed: ${err.message}`);
      }
    }

    // ── Event listeners ───────────────────────────────────────────────────────

    form.addEventListener('submit', (event) => {
      event.preventDefault();
      const query = input.value.trim();
      if (query) performSearch(query);
    });
  </script>

</body>
</html>

Embedding your API key in client-side HTML exposes it to anyone who views the page source. For production applications, proxy API calls through your own backend and keep the key server-side only.

Step 4: Build the Python Flask application

The Flask application below exposes a /search route that accepts a q query parameter, calls the Custom Search API server-side, and returns rendered HTML. This approach keeps your API key out of the browser. Install the dependencies first:

pip install flask requests

import os
import requests
from flask import Flask, render_template, request, jsonify

app = Flask(__name__)

API_KEY = os.environ.get("GOOGLE_API_KEY")
SEARCH_ENGINE_ID = os.environ.get("GOOGLE_SEARCH_ENGINE_ID")
BASE_URL = "https://www.googleapis.com/customsearch/v1"


def fetch_results(query: str, start: int = 1, num: int = 10) -> dict:
    """Call the Custom Search API and return the parsed JSON response."""
    params = {
        "key": API_KEY,
        "cx": SEARCH_ENGINE_ID,
        "q": query,
        "num": num,
        "start": start,
    }
    response = requests.get(BASE_URL, params=params, timeout=10)
    response.raise_for_status()
    return response.json()


@app.route("/")
def index():
    return render_template("index.html")


@app.route("/search")
def search():
    query = request.args.get("q", "").strip()
    start = max(1, int(request.args.get("start", 1)))

    if not query:
        return render_template("index.html", error="Please enter a search term.")

    try:
        data = fetch_results(query, start=start)
    except requests.HTTPError as exc:
        status_code = exc.response.status_code
        if status_code == 401:
            error = "Invalid API key. Check your GOOGLE_API_KEY environment variable."
        elif status_code == 403:
            error = "Daily query quota exceeded. Try again tomorrow or upgrade your plan."
        else:
            error = f"API error {status_code}. Please try again later."
        return render_template("index.html", query=query, error=error)

    items = data.get("items", [])
    search_info = data.get("searchInformation", {})

    return render_template(
        "results.html",
        query=query,
        items=items,
        total_results=search_info.get("formattedTotalResults", "0"),
        search_time=search_info.get("formattedSearchTime", "0"),
        start=start,
    )


if __name__ == "__main__":
    app.run(debug=True)

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Search</title>
</head>
<body>
  <h1>Search</h1>

  {% if error %}
    <p style="color: red;">{{ error }}</p>
  {% endif %}

  <form action="/search" method="get">
    <input
      type="search"
      name="q"
      value="{{ query or '' }}"
      placeholder="Enter a search term…"
      required
    />
    <button type="submit">Search</button>
  </form>
</body>
</html>

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>{{ query }} – Search Results</title>
</head>
<body>
  <h1>Search</h1>

  <form action="/search" method="get">
    <input type="search" name="q" value="{{ query }}" required />
    <button type="submit">Search</button>
  </form>

  <p>About {{ total_results }} results ({{ search_time }} seconds)</p>

  {% if items %}
    {% for item in items %}
      <div>
        <small style="color: green;">{{ item.displayLink }}</small><br />
        <a href="{{ item.link }}" target="_blank" rel="noopener">
          {{ item.title }}
        </a>
        <p>{{ item.snippet }}</p>
      </div>
    {% endfor %}
  {% else %}
    <p>No results found for <strong>{{ query }}</strong>.</p>
  {% endif %}
</body>
</html>

Run the Flask app with your credentials injected as environment variables:

GOOGLE_API_KEY=your_key GOOGLE_SEARCH_ENGINE_ID=your_cx python app.py

Then open http://localhost:5000 in your browser.

In production, use a secrets manager (e.g., Google Secret Manager, AWS Secrets Manager, or environment variables injected at deploy time) rather than hardcoding credentials anywhere in your source code.

Step 5: Handle errors gracefully

The Custom Search API returns standard HTTP status codes. Handle these cases in all applications:

Status	Meaning	Recommended action
`400`	Bad request — malformed parameters	Log and show a user-friendly “invalid query” message
`401`	Invalid or missing API key	Check your `key` parameter and Cloud Console credential settings
`403`	Quota exceeded or forbidden	Show a “try again later” message; consider caching results
`429`	Rate limited	Implement exponential back-off before retrying
`500`	Google server error	Retry with back-off; surface a temporary error message to the user

Exponential back-off example (Python)

import time
import requests

def fetch_with_backoff(url: str, params: dict, max_retries: int = 4) -> dict:
    """Retry a request with exponential back-off on 429 and 5xx responses."""
    for attempt in range(max_retries):
        response = requests.get(url, params=params, timeout=10)

        if response.status_code in (429, 500, 502, 503, 504):
            wait = 2 ** attempt  # 1s, 2s, 4s, 8s
            time.sleep(wait)
            continue

        response.raise_for_status()
        return response.json()

    raise RuntimeError("Max retries exceeded")

Next steps

Pagination

Learn how to use the start parameter to page through all available results.

Safe Search

Configure the safe parameter to filter adult content from your results.

Localization

Use lr, gl, cr, and hl to deliver region- and language-specific results.

API Reference

Browse the full list of query parameters and response fields.

Get Started

Core Concepts

Search Features

Guides

Help

Build a Search Application with Google Custom Search

Prerequisites

Step 1: Create and configure your Programmable Search Engine

Step 2: Understand the API request structure

Step 3: Build the HTML/JavaScript application

Step 4: Build the Python Flask application

Step 5: Handle errors gracefully

Next steps

Pagination

Safe Search

Localization

API Reference

​Prerequisites

​Step 1: Create and configure your Programmable Search Engine

​Step 2: Understand the API request structure

​Step 3: Build the HTML/JavaScript application

​Step 4: Build the Python Flask application

​Step 5: Handle errors gracefully

​Next steps

Pagination

Safe Search

Localization

API Reference

Prerequisites

Step 1: Create and configure your Programmable Search Engine

Step 2: Understand the API request structure

Step 3: Build the HTML/JavaScript application

Step 4: Build the Python Flask application

Step 5: Handle errors gracefully

Next steps