Developer Tools Community listing

Google Custom Search API

Searches over a website or collection of websites

https://customsearch.googleapis.com2 endpointsapiKey authno ratings yet100.0% uptime

Bring your own key. This API needs your own Google Custom Search API key - get one from the provider, add it once below, and the proxy injects it on every call. Your OmniStream plan covers the unified SDK, key storage, and proxy - the provider's own rate limits still apply to your key.

This is a community listing. If you own this API, you can request ownership.

Install the SDK

npm install omnistream-sdk

import { OmniClient } from "omnistream-sdk";

const omni = new OmniClient({ token: process.env.OMNI_KEY! });

// One key reaches every API on the marketplace.
const data = await omni.call("google-custom-search/search.cse.list");

One install, one key - the same client calls every API on the marketplace.

Try it

Try itone Omni key, every API

Your Omni key

GET/customsearch/v1

$.xgafv

V1 error format.

access_token

OAuth access token.

alt

Data format for response.

callback

JSONP

fields

Selector specifying which fields to include in a partial response.

key

API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.

oauth_token

OAuth 2.0 token for the current user.

prettyPrint

Returns response with indentations and line breaks.

quotaUser

Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.

upload_protocol

Upload protocol for media (e.g. "raw", "multipart").

uploadType

Legacy upload protocol for media (e.g. "media", "multipart").

c2coff

Enables or disables [Simplified and Traditional Chinese Search](https://developers.google.com/custom-search/docs/json_api_reference#chineseSearch). The default value for this parameter is 0 (zero), meaning that the feature is enabled. Supported values are: * `1`: Disabled * `0`: Enabled (default)

Restricts search results to documents originating in a particular country. You may use [Boolean operators](https://developers.google.com/custom-search/docs/json_api_reference#booleanOperators) in the cr parameter's value. Google Search determines the country of a document by analyzing: * the top-level domain (TLD) of the document's URL * the geographic location of the Web server's IP address See the [Country Parameter Values](https://developers.google.com/custom-search/docs/json_api_reference#countryCollections) page for a list of valid values for this parameter.

The Programmable Search Engine ID to use for this request.

dateRestrict

Restricts results to URLs based on date. Supported values include: * `d[number]`: requests results from the specified number of past days. * `w[number]`: requests results from the specified number of past weeks. * `m[number]`: requests results from the specified number of past months. * `y[number]`: requests results from the specified number of past years.

exactTerms

Identifies a phrase that all documents in the search results must contain.

excludeTerms

Identifies a word or phrase that should not appear in any documents in the search results.

fileType

Restricts results to files of a specified extension. A list of file types indexable by Google can be found in Search Console [Help Center](https://support.google.com/webmasters/answer/35287).

filter

Controls turning on or off the duplicate content filter. * See [Automatic Filtering](https://developers.google.com/custom-search/docs/json_api_reference#automaticFiltering) for more information about Google's search results filters. Note that host crowding filtering applies only to multi-site searches. * By default, Google applies filtering to all search results to improve the quality of those results. Acceptable values are: * `0`: Turns off duplicate content filter. * `1`: Turns on duplicate content filter.

Geolocation of end user. * The `gl` parameter value is a two-letter country code. The `gl` parameter boosts search results whose country of origin matches the parameter value. See the [Country Codes](https://developers.google.com/custom-search/docs/json_api_reference#countryCodes) page for a list of valid values. * Specifying a `gl` parameter value should lead to more relevant results. This is particularly true for international customers and, even more specifically, for customers in English- speaking countries other than the United States.

googlehost

**Deprecated**. Use the `gl` parameter for a similar effect. The local Google domain (for example, google.com, google.de, or google.fr) to use to perform the search.

highRange

Specifies the ending value for a search range. * Use `lowRange` and `highRange` to append an inclusive search range of `lowRange...highRange` to the query.

Sets the user interface language. * Explicitly setting this parameter improves the performance and the quality of your search results. * See the [Interface Languages](https://developers.google.com/custom-search/docs/json_api_reference#wsInterfaceLanguages) section of [Internationalizing Queries and Results Presentation](https://developers.google.com/custom-search/docs/json_api_reference#wsInternationalizing) for more information, and [Supported Interface Languages](https://developers.google.com/custom-search/docs/json_api_reference#interfaceLanguages) for a list of supported languages.

Appends the specified query terms to the query, as if they were combined with a logical AND operator.

imgColorType

Returns black and white, grayscale, transparent, or color images. Acceptable values are: * `"color"` * `"gray"` * `"mono"`: black and white * `"trans"`: transparent background

imgDominantColor

Returns images of a specific dominant color. Acceptable values are: * `"black"` * `"blue"` * `"brown"` * `"gray"` * `"green"` * `"orange"` * `"pink"` * `"purple"` * `"red"` * `"teal"` * `"white"` * `"yellow"`

imgSize

Returns images of a specified size. Acceptable values are: * `"huge"` * `"icon"` * `"large"` * `"medium"` * `"small"` * `"xlarge"` * `"xxlarge"`

imgType

Returns images of a type. Acceptable values are: * `"clipart"` * `"face"` * `"lineart"` * `"stock"` * `"photo"` * `"animated"`

linkSite

Specifies that all search results should contain a link to a particular URL.

lowRange

Specifies the starting value for a search range. Use `lowRange` and `highRange` to append an inclusive search range of `lowRange...highRange` to the query.

Restricts the search to documents written in a particular language (e.g., `lr=lang_ja`). Acceptable values are: * `"lang_ar"`: Arabic * `"lang_bg"`: Bulgarian * `"lang_ca"`: Catalan * `"lang_cs"`: Czech * `"lang_da"`: Danish * `"lang_de"`: German * `"lang_el"`: Greek * `"lang_en"`: English * `"lang_es"`: Spanish * `"lang_et"`: Estonian * `"lang_fi"`: Finnish * `"lang_fr"`: French * `"lang_hr"`: Croatian * `"lang_hu"`: Hungarian * `"lang_id"`: Indonesian * `"lang_is"`: Icelandic * `"lang_it"`: Italian * `"lang_iw"`: Hebrew * `"lang_ja"`: Japanese * `"lang_ko"`: Korean * `"lang_lt"`: Lithuanian * `"lang_lv"`: Latvian * `"lang_nl"`: Dutch * `"lang_no"`: Norwegian * `"lang_pl"`: Polish * `"lang_pt"`: Portuguese * `"lang_ro"`: Romanian * `"lang_ru"`: Russian * `"lang_sk"`: Slovak * `"lang_sl"`: Slovenian * `"lang_sr"`: Serbian * `"lang_sv"`: Swedish * `"lang_tr"`: Turkish * `"lang_zh-CN"`: Chinese (Simplified) * `"lang_zh-TW"`: Chinese (Traditional)

num

Number of search results to return. * Valid values are integers between 1 and 10, inclusive.

orTerms

Provides additional search terms to check for in a document, where each document in the search results must contain at least one of the additional search terms.

Query

relatedSite

Specifies that all search results should be pages that are related to the specified URL.

rights

Filters based on licensing. Supported values include: `cc_publicdomain`, `cc_attribute`, `cc_sharealike`, `cc_noncommercial`, `cc_nonderived` and combinations of these. See [typical combinations](https://wiki.creativecommons.org/wiki/CC_Search_integration).

safe

Search safety level. Acceptable values are: * `"active"`: Enables SafeSearch filtering. * `"off"`: Disables SafeSearch filtering. (default)

searchType

Specifies the search type: `image`. If unspecified, results are limited to webpages. Acceptable values are: * `"image"`: custom image search.

siteSearch

Specifies a given site which should always be included or excluded from results (see `siteSearchFilter` parameter, below).

siteSearchFilter

Controls whether to include or exclude results from the site named in the `siteSearch` parameter. Acceptable values are: * `"e"`: exclude * `"i"`: include

sort

The sort expression to apply to the results. The sort parameter specifies that the results be sorted according to the specified expression i.e. sort by date. [Example: sort=date](https://developers.google.com/custom-search/docs/structured_search#sort-by-attribute).

start

The index of the first result to return. The default number of results per page is 10, so `&start=11` would start at the top of the second page of results. **Note**: The JSON API will never return more than 100 results, even if more than 100 documents match the query, so setting the sum of `start + num` to a number greater than 100 will produce an error. Also note that the maximum value for `num` is 10.

2 endpoints

GET/customsearch/v1

Returns metadata about the search performed, metadata about the engine used for the search, and the search results.

$.xgafvaccess_tokenaltcallbackfieldskeyoauth_tokenprettyPrintquotaUserupload_protocoluploadTypec2coffcrcxdateRestrictexactTermsexcludeTermsfileTypefilterglgooglehosthighRangehlhqimgColorTypeimgDominantColorimgSizeimgTypelinkSitelowRangelrnumorTermsqrelatedSiterightssafesearchTypesiteSearchsiteSearchFiltersortstart

GET/customsearch/v1/siterestrict

Returns metadata about the search performed, metadata about the engine used for the search, and the search results. Uses a small set of url patterns.

Typed client (copy, no install)

google-custom-search.ts

/**
 * GoogleCustomSearchAPI - generated by OmniStream from Google Custom Search API's OpenAPI spec.
 * One typed method per endpoint. A single Omni key reaches the API.
 */
const DEFAULT_BASE = "https://grid.skinvaults.online/v1/proxy/google-custom-search";

export class GoogleCustomSearchAPIError extends Error {
  status: number;
  code?: string;
  constructor(status: number, code: string | undefined, message?: string) {
    super(message || `GoogleCustomSearchAPI error ${status}`);
    this.name = "GoogleCustomSearchAPIError";
    this.status = status;
    this.code = code;
  }
}

export interface GoogleCustomSearchAPIOptions {
  baseUrl?: string;
  fetch?: typeof fetch;
  timeoutMs?: number;
}

export class GoogleCustomSearchAPI {
  /** @param token Your OmniStream key (one key for every API). */
  constructor(private token: string, private opts: GoogleCustomSearchAPIOptions = {}) {
    if (!token) throw new Error("GoogleCustomSearchAPI: token is required");
  }
  rateLimit: { remainingMinute?: number; remainingDay?: number } | null = null;

  private async _request(method: string, path: string, { params, body }: { params?: Record<string, unknown>; body?: unknown } = {}): Promise<any> {
    const f = this.opts.fetch ?? globalThis.fetch;
    const url = new URL((this.opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "") + path);
    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));
    const headers: Record<string, string> = { "x-omni-key": this.token };
    if (body !== undefined) headers["content-type"] = "application/json";
    const res = await f(url, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined });
    this.rateLimit = {
      remainingMinute: Number(res.headers.get("x-ratelimit-remaining-minute")) || undefined,
      remainingDay: Number(res.headers.get("x-ratelimit-remaining-day")) || undefined,
    };
    const data = await res.json().catch(() => ({}));
    if (!res.ok) throw new GoogleCustomSearchAPIError(res.status, data?.error?.code, data?.error?.message);
    return data.data ?? data;
  }

  /** Returns metadata about the search performed, metadata about the engine used for the search, and the search results. */
  searchCseList(params: { "$.xgafv"?: string; "access_token"?: string; "alt"?: string; "callback"?: string; "fields"?: string; "key"?: string; "oauth_token"?: string; "prettyPrint"?: boolean; "quotaUser"?: string; "upload_protocol"?: string; "uploadType"?: string; "c2coff"?: string; "cr"?: string; "cx"?: string; "dateRestrict"?: string; "exactTerms"?: string; "excludeTerms"?: string; "fileType"?: string; "filter"?: string; "gl"?: string; "googlehost"?: string; "highRange"?: string; "hl"?: string; "hq"?: string; "imgColorType"?: string; "imgDominantColor"?: string; "imgSize"?: string; "imgType"?: string; "linkSite"?: string; "lowRange"?: string; "lr"?: string; "num"?: number; "orTerms"?: string; "q"?: string; "relatedSite"?: string; "rights"?: string; "safe"?: string; "searchType"?: string; "siteSearch"?: string; "siteSearchFilter"?: string; "sort"?: string; "start"?: number }): Promise<any> {
    return this._request("GET", "/customsearch/v1", { params });
  }

  /** Returns metadata about the search performed, metadata about the engine used for the search, and the search results. Uses a small set of url patterns. */
  searchCseSiterestrictList(params: { "$.xgafv"?: string; "access_token"?: string; "alt"?: string; "callback"?: string; "fields"?: string; "key"?: string; "oauth_token"?: string; "prettyPrint"?: boolean; "quotaUser"?: string; "upload_protocol"?: string; "uploadType"?: string; "c2coff"?: string; "cr"?: string; "cx"?: string; "dateRestrict"?: string; "exactTerms"?: string; "excludeTerms"?: string; "fileType"?: string; "filter"?: string; "gl"?: string; "googlehost"?: string; "highRange"?: string; "hl"?: string; "hq"?: string; "imgColorType"?: string; "imgDominantColor"?: string; "imgSize"?: string; "imgType"?: string; "linkSite"?: string; "lowRange"?: string; "lr"?: string; "num"?: number; "orTerms"?: string; "q"?: string; "relatedSite"?: string; "rights"?: string; "safe"?: string; "searchType"?: string; "siteSearch"?: string; "siteSearchFilter"?: string; "sort"?: string; "start"?: number }): Promise<any> {
    return this._request("GET", "/customsearch/v1/siterestrict", { params });
  }
}

export default GoogleCustomSearchAPI;

Reviews

No reviews yet. Be the first to rate this API.

Frequently asked questions

Do I need an API key to use Google Custom Search API?

Yes. Google Custom Search API uses apiKey authentication, so you bring your own key from the provider. You store it once on OmniStream and the proxy injects it into every call, so your code only ever sends your Omni key.

What can you do with the Google Custom Search API API?

Searches over a website or collection of websites It exposes 2 endpoints over GET, including GET /customsearch/v1, GET /customsearch/v1/siterestrict.

How do I call Google Custom Search API from Python, TypeScript, Rust or Go?

Install the OmniStream SDK for your language and call Google Custom Search API through it. The client is generated from this API's OpenAPI spec, so parameters and responses are fully typed, and the same client also calls every other API in the marketplace.

Is Google Custom Search API free to use on OmniStream?

You can start on the free plan. OmniStream charges for the unified SDK, key storage and proxy rather than for Google Custom Search API itself, and Google Custom Search API's own rate limits still apply to your provider key.