Cse.siterestrict: list

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


HTTP request

GET https://www.googleapis.com/customsearch/v1/siterestrict


Parameter name Value Description
Required query parameters
cx string The custom search engine ID to use for this request.
q string Query
Optional query parameters
c2coff string Turns off the translation between zh-CN and zh-TW.
cr string Country restrict(s).
dateRestrict string Specifies all search results are from a time period
exactTerms string Identifies a phrase that all documents in the search results must contain
excludeTerms string Identifies a word or phrase that should not appear in any documents in the search results
fileType string Restricts results to files of a specified extension. A list of file types indexable by Google can be found in Search Console Help Center.
filter string Controls turning on or off the duplicate content filter.
  • See Automatic Filtering 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.
gl string 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 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 string 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 string Creates a range in form as_nlo value..as_nhi value and attempts to append it to query
hl string Sets the user interface language. 
hq string Appends the specified query terms to the query, as if they were combined with a logical AND operator.
imgColorType string Returns black and white, grayscale, or color images: mono, gray, and color.

Acceptable values are:
  • "color": color
  • "gray": gray
  • "mono": mono
imgDominantColor string Returns images of a specific dominant color: red, orange, yellow, green, teal, blue, purple, pink, white, gray, black and brown.

Acceptable values are:
  • "black": black
  • "blue": blue
  • "brown": brown
  • "gray": gray
  • "green": green
  • "orange": orange
  • "pink": pink
  • "purple": purple
  • "red": red
  • "teal": teal
  • "white": white
  • "yellow": yellow
imgSize string Returns images of a specified size, where size can be one of: icon, small, medium, large, xlarge, xxlarge, and huge.

Acceptable values are:
  • "huge": huge
  • "icon": icon
  • "large": large
  • "medium": medium
  • "small": small
  • "xlarge": xlarge
  • "xxlarge": xxlarge
imgType string Returns images of a type, which can be one of: clipart, face, lineart, stock, photo, and animated.

Acceptable values are:
  • "clipart": Clip art
  • "face": Face
  • "lineart": Line drawing
  • "stock": Stock
  • "photo": Photo
  • "animated": Animated
linkSite string Specifies that all search results should contain a link to a particular URL
lowRange string Creates a range in form as_nlo value..as_nhi value and attempts to append it to query
lr string The language restriction for the search results

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 unsigned integer Number of search results to return
orTerms string 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
relatedSite string Specifies that all search results should be pages that are related to the specified URL
rights string Filters based on licensing. Supported values include: cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived and combinations of these. See typical combinations.
safe string Search safety level

Acceptable values are:
  • "active": Enables SafeSearch filtering.
  • "off": Disables SafeSearch filtering. (default)
searchType string Specifies the search type: image.

Acceptable values are:
  • "image": custom image search
siteSearch string Specifies all search results should be pages from a given site
siteSearchFilter string Controls whether to include or exclude results from the site named in the siteSearch parameter

Acceptable values are:
  • "e": exclude
  • "i": include
sort string The sort expression to apply to the results
start unsigned integer 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.

Request body

Do not supply a request body with this method.


If successful, this method returns a response body with the following structure:

  "kind": "customsearch#search",
  "url": {
    "type": "application/json",
    "template": "https://www.googleapis.com/customsearch/v1?q={searchTerms}&num={count?}&start={startIndex?}&lr={language?}&safe={safe?}&cx={cx?}&sort={sort?}&filter={filter?}&gl={gl?}&cr={cr?}&googlehost={googleHost?}&c2coff={disableCnTwTranslation?}&hq={hq?}&hl={hl?}&siteSearch={siteSearch?}&siteSearchFilter={siteSearchFilter?}&exactTerms={exactTerms?}&excludeTerms={excludeTerms?}&linkSite={linkSite?}&orTerms={orTerms?}&relatedSite={relatedSite?}&dateRestrict={dateRestrict?}&lowRange={lowRange?}&highRange={highRange?}&searchType={searchType}&fileType={fileType?}&rights={rights?}&imgSize={imgSize?}&imgType={imgType?}&imgColorType={imgColorType?}&imgDominantColor={imgDominantColor?}&alt=json"
  "queries": {
    (key): [
        "title": string,
        "totalResults": long,
        "searchTerms": string,
        "count": integer,
        "startIndex": integer,
        "startPage": integer,
        "language": string,
        "inputEncoding": string,
        "outputEncoding": string,
        "safe": string,
        "cx": string,
        "sort": string,
        "filter": string,
        "gl": string,
        "cr": string,
        "googleHost": string,
        "disableCnTwTranslation": string,
        "hq": string,
        "hl": string,
        "siteSearch": string,
        "siteSearchFilter": string,
        "exactTerms": string,
        "excludeTerms": string,
        "linkSite": string,
        "orTerms": string,
        "relatedSite": string,
        "dateRestrict": string,
        "lowRange": string,
        "highRange": string,
        "fileType": string,
        "rights": string,
        "searchType": string,
        "imgSize": string,
        "imgType": string,
        "imgColorType": string,
        "imgDominantColor": string
  "promotions": [
      "title": string,
      "htmlTitle": string,
      "link": string,
      "displayLink": string,
      "bodyLines": [
          "title": string,
          "htmlTitle": string,
          "url": string,
          "link": string
      "image": {
        "source": string,
        "width": integer,
        "height": integer
  "context": {
    "title": string,
    "facets": [
          "label": string,
          "anchor": string,
          "label_with_op": string
  "searchInformation": {
    "searchTime": double,
    "formattedSearchTime": string,
    "totalResults": long,
    "formattedTotalResults": string
  "spelling": {
    "correctedQuery": string,
    "htmlCorrectedQuery": string
  "items": [
      "kind": "customsearch#result",
      "title": string,
      "htmlTitle": string,
      "link": string,
      "displayLink": string,
      "snippet": string,
      "htmlSnippet": string,
      "cacheId": string,
      "mime": string,
      "fileFormat": string,
      "formattedUrl": string,
      "htmlFormattedUrl": string,
      "pagemap": {
        (key): [
            (key): (value)
      "labels": [
          "name": string,
          "displayName": string,
          "label_with_op": string
      "image": {
        "contextLink": string,
        "height": integer,
        "width": integer,
        "byteSize": integer,
        "thumbnailLink": string,
        "thumbnailHeight": integer,
        "thumbnailWidth": integer
Property name Value Description Notes
kind string
url object
url.type string
url.template string
queries object
queries.(key)[] list
queries.(key)[].title string
queries.(key)[].totalResults long
queries.(key)[].searchTerms string
queries.(key)[].count integer
queries.(key)[].startIndex integer
queries.(key)[].startPage integer
queries.(key)[].language string
queries.(key)[].inputEncoding string
queries.(key)[].outputEncoding string
queries.(key)[].safe string
queries.(key)[].cx string
queries.(key)[].sort string
queries.(key)[].filter string
queries.(key)[].gl string
queries.(key)[].cr string
queries.(key)[].googleHost string
queries.(key)[].disableCnTwTranslation string
queries.(key)[].hq string
queries.(key)[].hl string
queries.(key)[].siteSearch string
queries.(key)[].siteSearchFilter string
queries.(key)[].exactTerms string
queries.(key)[].excludeTerms string
queries.(key)[].linkSite string
queries.(key)[].orTerms string
queries.(key)[].relatedSite string
queries.(key)[].dateRestrict string
queries.(key)[].lowRange string
queries.(key)[].highRange string
queries.(key)[].fileType string
queries.(key)[].rights string
queries.(key)[].searchType string
queries.(key)[].imgSize string
queries.(key)[].imgType string
queries.(key)[].imgColorType string
queries.(key)[].imgDominantColor string
promotions[] list
promotions[].title string
promotions[].htmlTitle string
promotions[].bodyLines[] list
promotions[].bodyLines[].title string
promotions[].bodyLines[].htmlTitle string
promotions[].bodyLines[].url string
promotions[].image object
promotions[].image.source string
promotions[].image.width integer
promotions[].image.height integer
context nested object
context.title string
context.facets[] list
context.facets[].label string
context.facets[].anchor string
context.facets[].label_with_op string
searchInformation object
searchInformation.searchTime double
searchInformation.formattedSearchTime string
searchInformation.totalResults long
searchInformation.formattedTotalResults string
spelling object
spelling.correctedQuery string
spelling.htmlCorrectedQuery string
items[] list
items[].kind string
items[].title string
items[].htmlTitle string
items[].snippet string
items[].htmlSnippet string
items[].cacheId string
items[].mime string
items[].fileFormat string
items[].formattedUrl string
items[].htmlFormattedUrl string
items[].pagemap object
items[].pagemap.(key)[] list
items[].pagemap.(key)[].(key) any value
items[].labels[] list
items[].labels[].name string
items[].labels[].displayName string
items[].labels[].label_with_op string
items[].image object
items[].image.height integer
items[].image.width integer
items[].image.byteSize integer
items[].image.thumbnailHeight integer
items[].image.thumbnailWidth integer

Try it!

Use the APIs Explorer below to call this method on live data and see the response. Alternatively, try the standalone Explorer.