Paginate Search Results with the Custom Search API

const API_KEY = 'YOUR_API_KEY';
const CX = 'YOUR_SEARCH_ENGINE_ID';
const BASE_URL = 'https://www.googleapis.com/customsearch/v1';

/**
 * Fetch a single page of search results.
 *
 * @param {string} query          - The search query
 * @param {number} page           - 1-based page number (1–10)
 * @param {number} resultsPerPage - Results per page, 1–10 (default 10)
 */
async function fetchPage(query, page = 1, resultsPerPage = 10) {
  if (page < 1 || page > 10) {
    throw new RangeError('Page must be between 1 and 10.');
  }

  const start = (page - 1) * resultsPerPage + 1;

  const params = new URLSearchParams({
    key: API_KEY,
    cx: CX,
    q: query,
    num: resultsPerPage,
    start,
  });

  const response = await fetch(`${BASE_URL}?${params}`);

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

  return response.json();
}

// Fetch page 3 of results for "open source databases"
const data = await fetchPage('open source databases', 3);
console.log(`Showing results ${data.queries.request[0].startIndex}–` +
            `${data.queries.request[0].startIndex + data.items.length - 1}`);

import requests

API_KEY = "YOUR_API_KEY"
CX = "YOUR_SEARCH_ENGINE_ID"
BASE_URL = "https://www.googleapis.com/customsearch/v1"


def fetch_page(query: str, page: int = 1, results_per_page: int = 10) -> dict:
    """
    Fetch a single page of search results.

    Args:
        query:            The search query string.
        page:             1-based page number (1–10).
        results_per_page: Number of results per page (1–10).

    Returns:
        Parsed JSON response dict.

    Raises:
        ValueError:           If page is out of the 1–10 range.
        requests.HTTPError:   On non-2xx API responses.
    """
    if not 1 <= page <= 10:
        raise ValueError("Page must be between 1 and 10.")

    start = (page - 1) * results_per_page + 1

    params = {
        "key": API_KEY,
        "cx": CX,
        "q": query,
        "num": results_per_page,
        "start": start,
    }

    response = requests.get(BASE_URL, params=params, timeout=10)
    response.raise_for_status()
    return response.json()


# Fetch page 3
data = fetch_page("open source databases", page=3)
req = data["queries"]["request"][0]
print(f"Showing results {req['startIndex']}–{req['startIndex'] + len(data['items']) - 1}")

/**
 * Build a map of page numbers → API query parameter objects.
 *
 * @param {string} query          - Current search query
 * @param {number} totalResults   - From searchInformation.totalResults
 * @param {number} currentPage    - The page the user is currently viewing
 * @param {number} resultsPerPage - num parameter (default 10)
 * @returns {{ pages, prev, next, current }}
 */
function buildPaginationState(query, totalResults, currentPage = 1, resultsPerPage = 10) {
  const totalPages = Math.min(Math.ceil(parseInt(totalResults, 10) / resultsPerPage), 10);

  const makeParams = (page) => ({
    q: query,
    start: (page - 1) * resultsPerPage + 1,
    num: resultsPerPage,
  });

  return {
    current: currentPage,
    totalPages,
    pages: Array.from({ length: totalPages }, (_, i) => ({
      page: i + 1,
      params: makeParams(i + 1),
      isCurrent: i + 1 === currentPage,
    })),
    prev: currentPage > 1 ? makeParams(currentPage - 1) : null,
    next: currentPage < totalPages ? makeParams(currentPage + 1) : null,
  };
}

// Usage
const state = buildPaginationState('open source databases', '1430000', 3);
console.log(state.prev);   // { q: '...', start: 21, num: 10 }
console.log(state.next);   // { q: '...', start: 41, num: 10 }
console.log(state.totalPages); // 10

from math import ceil


def build_pagination_state(
    query: str,
    total_results: str | int,
    current_page: int = 1,
    results_per_page: int = 10,
) -> dict:
    """
    Build a pagination state dict for rendering page controls.

    Returns a dict with keys: current, total_pages, pages, prev, next.
    Each 'params' entry contains the kwargs to pass to fetch_page().
    """
    total = int(total_results)
    total_pages = min(ceil(total / results_per_page), 10)

    def make_params(page: int) -> dict:
        return {
            "query": query,
            "page": page,
            "results_per_page": results_per_page,
        }

    pages = [
        {"page": i, "params": make_params(i), "is_current": i == current_page}
        for i in range(1, total_pages + 1)
    ]

    return {
        "current": current_page,
        "total_pages": total_pages,
        "pages": pages,
        "prev": make_params(current_page - 1) if current_page > 1 else None,
        "next": make_params(current_page + 1) if current_page < total_pages else None,
    }


# Usage
state = build_pagination_state("open source databases", "1430000", current_page=3)
print(state["prev"])        # {'query': '...', 'page': 2, 'results_per_page': 10}
print(state["next"])        # {'query': '...', 'page': 4, 'results_per_page': 10}
print(state["total_pages"]) # 10