Replace the Google Custom Search JSON API before January 1, 2027

1from googleapiclient.discovery import build2 3service = build("customsearch", "v1", developerKey=GOOGLE_API_KEY)4result = (5    service.cse()6    .list(q="coffee grinders", cx=ENGINE_ID, num=5, gl="us", hl="en")7    .execute()8)9for item in result["items"]:10    print(item["title"], item["link"])

1GET https://customsearch.googleapis.com/customsearch/v12    ?key=GOOGLE_API_KEY&cx=ENGINE_ID3    &q=coffee%20grinders&num=5&gl=us&hl=en

1python -m pip install httpx2export LITESCRAPE_API_KEY=ls_live_...   # from https://litescrape.com/#demo

1"""Drop-in replacement for the Google Custom Search JSON API, served by Litescrape.
2
3    export LITESCRAPE_API_KEY=ls_live_...
4    python custom_search_migration.py "coffee grinders" --num 5 --gl us --hl en
5
6customsearch_list() accepts the keyword arguments of customsearch.cse.list()
7and returns a dictionary in the JSON API's Search shape: kind, queries,
8searchInformation, and items. Only httpx and the standard library are used.
9"""
10
11from __future__ import annotations
12
13import argparse
14import json
15import os
16import sys
17from typing import Any
18from urllib.parse import urlsplit
19
20import httpx
21
22LITESCRAPE_SEARCH_URL = "https://api.litescrape.com/api/google/search"
23DEFAULT_TIMEOUT = 60.0
24ENGINE_TITLE = "Litescrape Google Search"
25
26# Custom Search parameters with no Litescrape equivalent. Image search is
27# rejected by the API as an unsupported vertical, and licensing filters, sort
28# expressions, and link-based restrictions do not exist on a plain Google SERP.
29UNSUPPORTED = {
30    "searchType",
31    "imgSize",
32    "imgType",
33    "imgColorType",
34    "imgDominantColor",
35    "sort",
36    "rights",
37    "linkSite",
38    "relatedSite",
39}
40
41# Accepted so existing call sites keep working, then dropped. The engine ID
42# and API key belong to the Programmable Search Engine, and the Chinese
43# simplification switch has no counterpart.
44IGNORED = {"cx", "key", "c2coff", "alt", "fields", "prettyPrint", "quotaUser"}
45
46# Custom Search name on the left, Litescrape name on the right.
47RENAMED = {
48    "gl": "gl",
49    "hl": "hl",
50    "lr": "lr",
51    "cr": "cr",
52    "safe": "safe",
53    "filter": "filter",
54    "siteSearch": "as_sitesearch",
55    "siteSearchFilter": "as_dt",
56    "dateRestrict": "as_qdr",
57    "exactTerms": "as_epq",
58    "excludeTerms": "as_eq",
59    "orTerms": "as_oq",
60    "googlehost": "google_domain",
61}
62
63# Folded into the query string as Google search operators.
64QUERY_OPERATORS = {"q", "hq", "fileType", "lowRange", "highRange"}
65PAGING = {"num", "start"}
66
67
68def build_params(**cse: Any) -> dict[str, str]:
69    """Translate customsearch.cse.list() arguments into Litescrape query parameters."""
70    supplied = {name: value for name, value in cse.items() if value is not None and value != ""}
71
72    unsupported = sorted(name for name in supplied if name in UNSUPPORTED)
73    if unsupported:
74        raise ValueError(f"No Litescrape equivalent for: {', '.join(unsupported)}")
75    known = UNSUPPORTED | IGNORED | set(RENAMED) | QUERY_OPERATORS | PAGING
76    unknown = sorted(name for name in supplied if name not in known)
77    if unknown:
78        raise ValueError(f"Unknown Custom Search parameter(s): {', '.join(unknown)}")
79
80    query = str(supplied.get("q", "")).strip()
81    if not query:
82        raise ValueError("q is required")
83    terms = [query]
84    if "hq" in supplied:
85        terms.append(str(supplied["hq"]).strip())
86    if "fileType" in supplied:
87        terms.append(f"filetype:{str(supplied['fileType']).strip().lstrip('.')}")
88    if "lowRange" in supplied and "highRange" in supplied:
89        terms.append(f"{supplied['lowRange']}..{supplied['highRange']}")
90    params: dict[str, str] = {"q": " ".join(terms)}
91
92    num = int(supplied.get("num", 10))
93    if not 1 <= num <= 100:
94        raise ValueError("num must be between 1 and 100")
95    params["num"] = str(num)
96
97    # Custom Search counts results from 1; Google and Litescrape use a zero-based offset.
98    start = int(supplied.get("start", 1))
99    if start < 1:
100        raise ValueError("start must be 1 or greater")
101    if start > 1:
102        params["start"] = str(start - 1)
103
104    for cse_name, litescrape_name in RENAMED.items():
105        if cse_name in supplied:
106            params[litescrape_name] = str(supplied[cse_name]).strip()
107    if "gl" in params:
108        params["gl"] = params["gl"].lower()
109    if "as_sitesearch" in params and "as_dt" not in params:
110        params["as_dt"] = "i"
111    return params
112
113
114def to_custom_search(data: dict[str, Any], params: dict[str, str], start: int) -> dict[str, Any]:
115    """Reshape a Litescrape Google Search response into the JSON API's Search resource."""
116    organic = data.get("organic_results") or []
117    info = data.get("search_information") or {}
118    total = info.get("total_results")
119    count = int(params["num"])
120
121    def page(start_index: int) -> dict[str, Any]:
122        return {
123            "title": ENGINE_TITLE,
124            "totalResults": "" if total is None else str(total),
125            "searchTerms": params["q"],
126            "count": count,
127            "startIndex": start_index,
128            "inputEncoding": "utf8",
129            "outputEncoding": "utf8",
130            "safe": params.get("safe", "off"),
131            "gl": params.get("gl", ""),
132            "hl": params.get("hl", ""),
133        }
134
135    queries: dict[str, Any] = {"request": [page(start)]}
136    if start > 1:
137        queries["previousPage"] = [page(max(1, start - count))]
138    if (data.get("pagination") or {}).get("next"):
139        queries["nextPage"] = [page(start + count)]
140
141    items = []
142    for row in organic:
143        link = str(row.get("link", ""))
144        items.append(
145            {
146                "kind": "customsearch#result",
147                "title": row.get("title", ""),
148                "link": link,
149                "displayLink": urlsplit(link).hostname or "",
150                "snippet": row.get("snippet", ""),
151                "formattedUrl": row.get("displayed_link", ""),
152            }
153        )
154
155    search_time = info.get("time_taken_displayed")
156    return {
157        "kind": "customsearch#search",
158        "context": {"title": ENGINE_TITLE},
159        "queries": queries,
160        "searchInformation": {
161            "searchTime": search_time,
162            "formattedSearchTime": "" if search_time is None else f"{search_time:.2f}",
163            "totalResults": "" if total is None else str(total),
164            "formattedTotalResults": "" if total is None else f"{total:,}",
165        },
166        "items": items,
167        "litescrape": {"search_metadata": data.get("search_metadata", {})},
168    }
169
170
171def customsearch_list(
172    *,
173    api_key: str | None = None,
174    timeout: float = DEFAULT_TIMEOUT,
175    **cse: Any,
176) -> dict[str, Any]:
177    """Run one Custom Search style query against Litescrape and return the JSON API shape."""
178    key = api_key or os.environ.get("LITESCRAPE_API_KEY", "")
179    if not key:
180        raise RuntimeError("Set LITESCRAPE_API_KEY or pass api_key=...")
181    params = build_params(**cse)
182    response = httpx.get(
183        LITESCRAPE_SEARCH_URL,
184        params=params,
185        headers={"Authorization": f"Bearer {key}", "Accept": "application/json"},
186        timeout=timeout,
187    )
188    if response.status_code != 200:
189        try:
190            envelope = response.json()
191        except ValueError:
192            envelope = {"error": response.text[:200]}
193        raise RuntimeError(
194            f"Litescrape returned HTTP {response.status_code}: "
195            f"{envelope.get('error_code', '')} {envelope.get('error', '')} "
196            f"(request_id={envelope.get('request_id', '')})".strip()
197        )
198    start = int(cse.get("start") or 1)
199    return to_custom_search(response.json(), params, start)
200
201
202def main(argv: list[str] | None = None) -> int:
203    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
204    parser.add_argument("q", help="search terms, exactly as you passed them to cse.list()")
205    parser.add_argument("--num", type=int, default=10, help="results per page, 1 to 100")
206    parser.add_argument("--start", type=int, default=1, help="1-based index of the first result")
207    parser.add_argument("--gl", help="two-letter country code")
208    parser.add_argument("--hl", help="interface language, for example en")
209    parser.add_argument("--site", dest="siteSearch", help="site to include or exclude")
210    parser.add_argument("--site-filter", dest="siteSearchFilter", choices=["i", "e"])
211    parser.add_argument("--date", dest="dateRestrict", help="d7, w2, m6, y1")
212    parser.add_argument("--filetype", dest="fileType", help="pdf, docx, ...")
213    args = parser.parse_args(argv)
214    try:
215        result = customsearch_list(**vars(args))
216    except (ValueError, RuntimeError) as error:
217        print(f"error: {error}", file=sys.stderr)
218        return 1
219    json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
220    print()
221    return 0
222
223
224if __name__ == "__main__":
225    raise SystemExit(main())

1python custom_search_migration.py "coffee grinders" --num 5 --gl us --hl en

{
  "kind": "customsearch#search",
  "context": {
    "title": "Litescrape Google Search"
  },
  "queries": {
    "request": [
      {
        "title": "Litescrape Google Search",
        "totalResults": "291",
        "searchTerms": "coffee grinders",
        "count": 5,
        "startIndex": 1,
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "off",
        "gl": "us",
        "hl": "en"
      }
    ],
    "nextPage": [
      {
        "title": "Litescrape Google Search",
        "totalResults": "291",
        "searchTerms": "coffee grinders",
        "count": 5,
        "startIndex": 6,
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "off",
        "gl": "us",
        "hl": "en"
      }
    ]
  },
  "searchInformation": {
    "searchTime": 0.33,
    "formattedSearchTime": "0.33",
    "totalResults": "291",
    "formattedTotalResults": "291"
  },
  "items": [
    {
      "kind": "customsearch#result",
      "title": "Coffee & Espresso Grinders | Expert Selection",
      "link": "https://clivecoffee.com/collections/grinders?srsltid=AfmBOoojKqyJzGo0dW_eimPNQ87MEzov-vMtwJizJaMRYem14un7Aalm",
      "displayLink": "clivecoffee.com",
      "snippet": "Shop curated coffee and espresso grinders from Eureka, Baratza, Mahlkönig & more. Chosen by real baristas.",
      "formattedUrl": "https://clivecoffee.com › collections › grinders"
    },
    ...
    {
      "kind": "customsearch#result",
      "title": "The 9 Best Coffee Grinders of 2026, Tested & Reviewed",
      "link": "https://www.seriouseats.com/the-best-coffee-grinders",
      "displayLink": "www.seriouseats.com",
      "snippet": "Jul 21, 2026 — The Baratza Virtuoso+ is the best coffee grinder for the bean-obsessed. With over 40 settings, it offers versatility without being over-designed ... Read more",
      "formattedUrl": "https://www.seriouseats.com › ... › Coffee & Tea › Gear"
    }
  ],
  "litescrape": {
    "search_metadata": {
      "id": "04b24a320ff2beeff120aa77",
      "status": "Success",
      "created_at": "2026-09-14 19:46:58 +00:00",
      "processed_at": "2026-09-14 19:47:01 +00:00",
      "total_time_taken": 2.9,
      "google_url": "https://www.google.com/search?q=coffee%20grinders&num=5&hl=en&gl=us",
      "json_endpoint": "https://api.litescrape.com/api/google/search?device=desktop&gl=us&google_domain=google.com&hl=en&num=5&q=coffee+grinders&start=0"
    }
  }
}

1# pip install litescrape-sdk2from litescrape_sdk import GoogleSearch, scrape3 4results = scrape(5    [GoogleSearch(q="coffee grinders", num=5, gl="us", hl="en")],6    api_key="ls_live_...",7)8for row in results[0].raise_for_error()["organic_results"]:9    print(row["title"], row["link"])