Custom Search

CSE: list

The cse.list method returns metadata about the search performed, metadata about the custom search engine used for the search, and the search results.  
Try it now.

This method requires three query parameters:

  • The search engine to use in your request (using either the cx or cref query parameters)
  • The search terms for in this request (using the q query parameter).
  • Your API key (using the key query parameter).

All other query parameters are optional.

Request

HTTP request

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

Parameters

Parameter name Value Description
Required parameters
q string The search expression.
Optional parameters
c2coff string Enables or disables Simplified and Traditional Chinese Search
  • The default value for this parameter is 0 (zero), meaning that the feature is enabled. Supported values are:
    • 1: Disabled
    • 0: Enabled (default)
cr string Restricts search results to documents originating in a particular country.
  • You may use Boolean operators 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 page for a list of valid values for this parameter.
cref string The URL of a linked custom search engine specification to use for this request. 
  • Does not apply for Google Site Search
  • If both cx and cref are specified, the cx value is used
cx string The custom search engine ID to use for this request.
  • If both cx and cref are specified, the cx value is used.
dateRestrict string 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 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 Webmaster Tools 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 The local Google domain (for example, google.com, google.de, or google.fr) to use to perform the search. 
highRange string
  • Specifies the ending value for a search range.
  • Use lowRange and highRange to append an inclusive search range of lowRange...highRange  to the 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.

Acceptable values are:
  • "black": black
  • "blue": blue
  • "brown": brown
  • "gray": gray
  • "green": green
  • "pink": pink
  • "purple": purple
  • "teal": teal
  • "white": white
  • "yellow": yellow
imgSize string Returns images of a specified size.

Acceptable values are:
  • "huge": huge
  • "icon": icon
  • "large": large
  • "medium": medium
  • "small": small
  • "xlarge": xlarge
  • "xxlarge": xxlarge
imgType string Returns images of a type.

Acceptable values are:
  • "clipart": clipart
  • "face": face
  • "lineart": lineart
  • "news": news
  • "photo": photo
linkSite string Specifies that all search results should contain a link to a particular URL
lowRange string Specifies the starting value for a search range.
Use lowRange and highRange to append an inclusive search range of lowRange...highRange to the query.
lr string 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 unsigned integer Number of search results to return.
  • Valid values are integers between 1 and 10, inclusive.
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.
safe string Search safety level.

Acceptable values are:
  • "high": Enables highest level of SafeSearch filtering.
  • "medium": Enables moderate SafeSearch filtering.
  • "off": Disables SafeSearch filtering. (default)
searchType string Specifies the search type: image If unspecified, results are limited to webpages.

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.

Request body

Do not supply a request body with this method.

Response

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

JSON

{
  "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?}&cref={cref?}&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,
        "cref": 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 Unique identifier for the type of current object. For this API, it is customsearch#search.
url object The OpenSearch URL element that defines the template for this API.
url.type string The MIME type of the OpenSearch URL template for the Custom Search API.
url.template string The actual OpenSearch template for this API.
queries object Contains one or more sets of query metadata, keyed by role name. The possible role names are defined bythe  OpenSearch query roles and by two custom roles: nextPage and previousPage.
queries.(key)[] list An array of metadata query objects describing possible roles. The "request" role is always present and has exactly one object, representing the current request. The "correction" role might provide several possible alternatives.
queries.(key)[].title string A description of the query.
queries.(key)[].totalResults long Estimated number of total search results. May not be accurate.
queries.(key)[].searchTerms string The search terms entered by the user.
queries.(key)[].count integer Number of search results returned in this set.
queries.(key)[].startIndex integer The index of the current set of search results into the total set of results, where the index of the first result is 1.
queries.(key)[].startPage integer The page number of this set of results, where the page length is set by the count property.
queries.(key)[].language string The language of the search results.
queries.(key)[].inputEncoding string The character encoding supported for search requests.
queries.(key)[].outputEncoding string The character encoding supported for search results.
queries.(key)[].safe string Specifies the  SafeSearch level used for filtering out adult results. This is a custom property not defined in the OpenSearch spec. Valid parameter values are:
  • off: Disable SafeSearch (default)
  • medium: Enable SafeSearch
  • high: Enable a stricter version of SafeSearch
queries.(key)[].cx string The identifier of a custom search engine created using the Custom Search Control Panel, if specified in request. This is a custom property not defined in the OpenSearch spec.
queries.(key)[].cref string A URL pointing to the definition of a linked custom search engine, if specified in request. This is a custom property not defined in the OpenSearch spec. Does not apply for Google Site Search.
queries.(key)[].sort string Specifies that results should be sorted according to the specified expression. For example, sort by date. 
queries.(key)[].filter string

Activates or deactivates the automatic filtering of Google search results. See Automatic Filtering for more information about Google's search results filters.

The default value for the filter parameter is 1, which indicates that the feature is enabled. Valid values for this parameter are:

  • 0: Disabled
  • 1: Enabled

Note: By default, Google applies filtering to all search results to improve the quality of those results.

queries.(key)[].gl string

Boosts search results whose country of origin matches the parameter value. See Country Codes for a list of valid values.

Specifying a gl parameter value in WebSearch requests should improve the relevance of results. This is particularly true for international customers and, even more specifically, for customers in English-speaking countries other than the United States.

queries.(key)[].cr string

Restricts search results to documents originating in a particular country. You may use Boolean operators in the cr parameter's value.

Google WebSearch determines the country of a document by analyzing the following:

  • The top-level domain (TLD) of the document's URL.
  • The geographic location of the web server's IP address.

See Country (cr) Parameter Values for a list of valid values for this parameter.

queries.(key)[].googleHost string Specifies the Google domain (for example, google.com, google.de, or google.fr) to which the search should be limited.
queries.(key)[].disableCnTwTranslation string

Enables or disables the Simplified and Traditional Chinese Search feature.

Supported values are:
  • 0: enabled (default)
  • 1: disabled
queries.(key)[].hq string Appends the specified query terms to the query, as if they were combined with a logical AND operator.
queries.(key)[].hl string

Specifies the interface language (host language) of your user interface. Explicitly setting this parameter improves the performance and the quality of your search results.

See the Interface Languages section of Internationalizing Queries and Results Presentation for more information, and Supported Interface Languages for a list of supported languages.

queries.(key)[].siteSearch string Restricts results to URLs from a specified site.
queries.(key)[].siteSearchFilter string Specifies whether to include or exclude results from the site named in the sitesearch parameter. Supported values are:
  • i: include content from site
  • e: exclude content from site
queries.(key)[].exactTerms string Identifies a phrase that all documents in the search results must contain.
queries.(key)[].excludeTerms string Identifies a word or phrase that should not appear in any documents in the search results.
queries.(key)[].linkSite string Specifies that all results should contain a link to a specific URL.
queries.(key)[].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. You can also use the Boolean OR query term for this type of query.
queries.(key)[].relatedSite string Specifies that all search results should be pages that are related to the specified URL. The parameter value should be a URL.
queries.(key)[].dateRestrict string 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.
queries.(key)[].lowRange string Specifies the starting value for a search range. Use cse:lowRange and cse:highrange to append an inclusive search range of lowRange...highRange to the query.
queries.(key)[].highRange string Specifies the ending value for a search range. Use cse:lowRange and cse:highrange to append an inclusive search range of lowRange...highRange to the query.
queries.(key)[].fileType string Restricts results to files of a specified extension. Filetypes supported by Google include:
  • Adobe Portable Document Format (pdf)
  • Adobe PostScript (ps)
  • Lotus 1-2-3 (wk1, wk2, wk3, wk4, wk5, wki, wks, wku)
  • Lotus WordPro (lwp)
  • Macwrite (mw)
  • Microsoft Excel (xls)
  • Microsoft PowerPoint (ppt)
  • Microsoft Word (doc)
  • Microsoft Works (wks, wps, wdb)
  • Microsoft Write (wri)
  • Rich Text Format (rtf)
  • Shockwave Flash (swf)
  • Text (ans, txt).

Additional filetypes may be added in the future. An up-to-date list can always be found in Google's file type FAQ.

queries.(key)[].rights string

Filters based on licensing. Supported values include:

  • cc_publicdomain
  • cc_attribute
  • cc_sharealike
  • cc_noncommercial
  • cc_nonderived
queries.(key)[].searchType string Allowed values are web or image. If unspecified, results are limited to webpages.
queries.(key)[].imgSize string Restricts results to images of a specified size. Supported values are:
  • icon (small)
  • small|medium|large|xlarge (medium)
  • xxlarge (large)
  • huge (extra-large)
queries.(key)[].imgType string Restricts results to images of a specified type. Supported values are:
  • clipart (clipart)
  • face (face)
  • lineart (lineart)
  • news (news)
  • photo (photo)
queries.(key)[].imgColorType string Restricts results to images of a specified color type. Supported values are:
  • mono (black and white)
  • gray (grayscale)
  • color (color)
queries.(key)[].imgDominantColor string Restricts results to images with a specific dominant color. Supported values are:
  • yellow
  • green
  • teal
  • blue
  • purple
  • pink
  • white
  • gray
  • black
  • brown
promotions[] array The set of promotions. Present only if the custom search engine's configuration files define any promotions for the given query.
promotions[].title string The title of the promotion.
promotions[].bodyLines[] list An array of block objects for this promotion. See Google WebSearch Protocol reference for more information.
promotions[].bodyLines[].title string The block object's text, if it has text.
promotions[].bodyLines[].url string The URL of the block object's link, if it has one.
promotions[].image object Image associated with this promotion, if there is one.
promotions[].image.source string URL of the image for this promotion link.
promotions[].image.width integer Image width in pixels.
promotions[].image.height integer Image height in pixels.
context nested object Metadata about the particular search engine that was used for performing the search query.
context.title string The name of the search engine that was used for the query.
context.facets[] list A set of facet objects (refinements) you can use for refining a search.
context.facets[].label string The label of the given facet item, which you can use to refine your search.
context.facets[].anchor string The displayable name of the item, which you should use when displaying the item to a human.
searchInformation object Encapsulates all information about the search.
searchInformation.searchTime double The time taken for the server to return search results.
searchInformation.formattedSearchTime string The time taken for the server to return search results, formatted according to locale style.
searchInformation.totalResults long The total number of search results returned by the query.
searchInformation.formattedTotalResults string The total number of search results, formatted according to locale style.
items[] list The current set of custom search results.
items[].kind string A unique identifier for the type of current object. For this API, it is customsearch#result.
items[].title string The title of the search result, in plain text.
items[].htmlTitle string The title of the search result, in HTML.
items[].snippet string The snippet of the search result, in plain text.
items[].htmlSnippet string The snippet of the search result, in HTML.
items[].cacheId string Indicates the ID of Google's cached version of the search result.
items[].mime string The MIME type of the search result.
items[].formattedUrl string The URL displayed after the snippet for each search result.
items[].htmlFormattedUrl string The HTML-formatted URL displayed after the snippet for each search result.
items[].pagemap object Contains PageMap information for this search result.
items[].pagemap.(key)[] list PageMap information, keyed by the name of this PageMap.
items[].pagemap.(key)[].(key) any value The actual PageMap information.
items[].labels[] list Encapsulates all information about refinement labels.
items[].labels[].name string The name of a refinement label, which you can use to refine searches. Don't display this in your user interface; instead, use displayName.
items[].labels[].displayName string The display name of a refinement label. This is the name you should display in your user interface.
items[].image object Encapsulates all information about an image returned in search results.
items[].image.height integer The height of the image, in pixels.
items[].image.width integer The width of the image, in pixels.
items[].image.byteSize integer The size of the image, in pixels.
items[].image.thumbnailHeight integer The height of the thumbnail image, in pixels.
items[].image.thumbnailWidth integer The width of the thumbnail image, in pixels.
spelling object Encapsulates a corrected query.
spelling.correctedQuery string The corrected query.
spelling.htmlCorrectedQuery string The corrected query, formatted in HTML.
items[].fileFormat string The file format of the search results.
promotions[].htmlTitle string The title of the promotion, in HTML.
promotions[].bodyLines[].htmlTitle string The text of the promotion.
context.facets[].label_with_op string
items[].labels[].label_with_op string

Atom

<feed gd:kind="customsearch#search" xmlns="http://www.w3.org/2005/Atom" xmlns:cse="http://schemas.google.com/cseapi/2010" xmlns:gd="http://schemas.google.com/g/2005" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>
    string
  </title>
  <id xmlns:cse="http://schemas.google.com/cseapi/2010" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
    string
    string
    string
    string
    string
    string
    string
  </id>
  <author>
    <name>
      string
    </name>
  </author>
  <updated>
    datetime
  </updated>
  <opensearch:Url type="application/atom+xml" template="https://www.googleapis.com/customsearch/v1?q={searchTerms}&num={count?}&start={startIndex?}&lr={language?}&safe={cse:safe?}&cx={cse:cx?}&cref={cse:cref?}&sort={cse:sort?}&filter={cse:filter?}&gl={cse:gl?}&cr={cse:cr?}}&googlehost={cse:googleHost?}&c2coff={?cse:disableCnTwTranslation}&hq={cse:hq?}&hl={cse:hl?}&siteSearch={cse:siteSearch?}&siteSearchFilter={cse:siteSearchFilter?}&exactTerms={cse:exactTerms?}&excludeTerms={cse:excludeTerms?}&linkSite={cse:linkSite?}&orTerms={cse:orTerms?}&relatedSite={cse:relatedSite?}&dateRestrict={cse:dateRestrict?}&lowRange={cse:lowRange?}&highRange={cse:highRange?}&searchType={cse:searchType?}&fileType={cse:fileType?}&rights={cse:rights?}&imgsz={cse:imgsz?}&imgtype={cse:imgtype?}&imgc={cse:imgc?}&imgcolor={cse:imgcolor?}&alt=atom"/>
  (foreach)
    <opensearch:Query role="string" title="string" totalResults="long" searchTerms="string" count="integer" startIndex="integer" startPage="integer" language="string" inputEncoding="string" outputEncoding="string" cse:safe="string" cse:cx="string" cse:cref="string" cse:sort="string" cse:filter="string" cse:gl="string" cse:cr="string" cse:googleHost="string" cse:disableCnTwTranslation="string" cse:hq="string" cse:hl="string" cse:siteSearch="string" cse:siteSearchFilter="string" cse:exactTerms="string" cse:excludeTerms="string" cse:linkSite="string" cse:orTerms="string" cse:relatedSite="string" cse:dateRestrict="string" cse:lowRange="string" cse:highRange="string" cse:fileType="string" cse:rights="string" cse:searchType="string" cse:imgSize="string" cse:imgType="string" cse:imgColorType="string" cse:imgDominantColor="string" xmlns:cse="http://schemas.google.com/cseapi/2010" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"/>
  (/foreach)
  <opensearch:totalResults>
    long
  </opensearch:totalResults>
  <opensearch:startIndex>
    integer
  </opensearch:startIndex>
  (foreach)
    <cse:promotion xmlns:cse="http://schemas.google.com/cseapi/2010">
      <title type="html">
        string
      </title>
      <displayTitle type="html">
        string
      </displayTitle>
      <link href="string" title="string"/>
      (foreach)
        <cse:bodyLine title="string" displayTitle="string" url="string" link="string"/>
      (/foreach)
      <cse:image src="string" height="integer" width="integer"/>
    </cse:promotion>
  (/foreach)
  <cse:context title="string" xmlns:cse="http://schemas.google.com/cseapi/2010">
    (foreach)
      <cse:facet>
        (foreach)
          <cse:item label="string" anchor="string"/>
        (/foreach)
      </cse:facet>
    (/foreach)
  </cse:context>
  <cse:searchInformation>
    <cse:searchTime>
      double
    </cse:searchTime>
    <cse:formattedSearchTime>
      string
    </cse:formattedSearchTime>
    <cse:totalResults>
      long
    </cse:totalResults>
    <cse:formattedTotalResults>
      string
    </cse:formattedTotalResults>
  </cse:searchInformation>
  <cse:spelling>
    <cse:correctedQuery type="html">
      string
    </cse:correctedQuery>
  </cse:spelling>
  (foreach)
    <entry gd:kind="customsearch#result" xmlns:cse="http://schemas.google.com/cseapi/2010" xmlns:gd="http://schemas.google.com/g/2005">
      <id>
        string
      </id>
      <updated>
        datetime
      </updated>
      <title type="html">
        string
      </title>
      <link href="string" title="string"/>
      <summary type="html">
        string
      </summary>
      <cse:cacheId>
        string
      </cse:cacheId>
      <cse:mime>
        string
      </cse:mime>
      <cse:fileFormat>
        string
      </cse:fileFormat>
      <cse:formattedUrl type="html">
        string
      </cse:formattedUrl>
      <cse:PageMap>
        (foreach)
          <cse:DataObject type="string">
            (foreach)
              <cse:Attribute name="string" value="string"/>
            (/foreach)
          </cse:DataObject>
        (/foreach)
      </cse:PageMap>
      <cse:Labels>
        (foreach)
          <cse:Label name="string" displayName="string"/>
        (/foreach)
      </cse:Labels>
      <cse:Image>
        <cse:contextLink>
          string
        </cse:contextLink>
        <cse:height>
          integer
        </cse:height>
        <cse:width>
          integer
        </cse:width>
        <cse:byteSize>
          integer
        </cse:byteSize>
        <cse:thumbnailLink>
          string
        </cse:thumbnailLink>
        <cse:thumbnailHeight>
          integer
        </cse:thumbnailHeight>
        <cse:thumbnailWidth>
          integer
        </cse:thumbnailWidth>
      </cse:Image>
    </entry>
  (/foreach)
</feed>
Property name Value Description Notes
feed object The result feed.
feed/gd:kind string Unique identifier for the type of current object. For the Custom Search API, this is customsearch#search.
feed/xmlns string Atom Syndication Format namespace.
feed/xmlns:cse string Custom Search extensions to the Google Data namespace.
feed/xmlns:gd string Google Data namespace.
feed/xmlns:opensearch string OpenSearch namespace.
feed/title object Encapsulates title information about the search request.
feed/title/text() string The title of this search request.
feed/id nested object Encapsulates all ID data about the search request.
feed/id/xmlns:cse string Custom Search extensions to the Google Data namespace.
feed/id/xmlns:opensearch string OpenSearch namespace.
feed/id/text() string Provides metadata about the search request, including the values of the search parameters.
feed/author object Encapsulates information about the API.
feed/author/name object Indicates the name of the API.
feed/author/name/text() string The name of this API.
feed/updated object Encapsulates all data about the time the search request was received.
feed/updated/text() datetime The date and time that this search request was received.
feed/opensearch:Url object The URL of the search query.
feed/opensearch:Url/type string The MIME type of the OpenSearch URL template for the Custom Search API.
feed/opensearch:Url/template string The OpenSearch URL element that defines the template for this API.
feed/opensearch:Query nested object Encapsulates all information about the search query.
feed/opensearch:Query/role string The role of this query. The possible role names are defined by the OpenSearch query roles and by two custom roles: nextPage and previousPage.
feed/opensearch:Query/title string A description of the query.
feed/opensearch:Query/totalResults long Estimated number of total search results. May not be accurate.
feed/opensearch:Query/searchTerms string The search terms entered by the user.
feed/opensearch:Query/count integer Number of search results returned in this set.
feed/opensearch:Query/startIndex integer The index of the current set of search results into the total set of results, where the index of the first result is 1.
feed/opensearch:Query/startPage integer The page number of this set of results, where the page length is set by the count property.
feed/opensearch:Query/language string The language of the search results.
feed/opensearch:Query/inputEncoding string The character encoding supported for search requests.
feed/opensearch:Query/outputEncoding string The character encoding of the search results.
feed/opensearch:Query/cse:safe string Indicates the SafeSearch level used for filtering results for adult content. Valid parameter values are:

  • off: Disable SafeSearch (default)
  • medium: Enable SafeSearch
  • high: Enable a stricter version of SafeSearch
feed/opensearch:Query/cse:cx string The identifier of a custom search engine created using the Custom Search Control Panel, if specified in request. This is a custom property not defined in the OpenSearch spec.
feed/opensearch:Query/cse:cref string A URL pointing to the definition of a linked custom search engine, if specified in request. This is a custom property not defined in the OpenSearch spec.
feed/opensearch:Query/cse:sort string Specifies that the results be sorted according to the specified expression. For example, sort by date.
feed/opensearch:Query/cse:filter string

Activates or deactivates the automatic filtering of Google search results. See Automatic Filtering for more information about Google's search results filters.

The default value for the filter parameter is 1, which indicates that the feature is enabled. Valid values for this parameter are:

  • 0: Disabled
  • 1: Enabled

Note: By default, Google applies filtering to all search results to improve the quality of those results.

feed/opensearch:Query/cse:gl string

Boosts search results whose country of origin matches the parameter value. See Country Codes for a list of valid values.

Specifying a gl parameter value in WebSearch requests should improve the relevance of results. This is particularly true for international customers and, even more specifically, for customers in English-speaking countries other than the United States.

feed/opensearch:Query/cse:cr string

Restricts search results to documents originating in a particular country. You may use Boolean operators in the cr parameter's value.

Google WebSearch 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 Country (cr) Parameter Values for a list of valid values for this parameter.

feed/opensearch:Query/cse:googleHost string Specifies the Google domain (for example, google.com, google.de, or google.fr) to which the search should be limited.
feed/opensearch:Query/cse:disableCnTwTranslation string

Enables or disables the Simplified and Traditional Chinese Search feature.

The default value for this parameter is 0 (zero), meaning that the feature is enabled. Values for are:

  • 1: Disabled
  • 0: Enabled (default)
feed/opensearch:Query/cse:hq string Appends the specified query terms to the query, as if they were combined with a logical AND operator.
feed/opensearch:Query/cse:hl string

Specifies the interface language (host language) of your user interface. Explicitly setting this parameter improves the performance and the quality of your search results.

See the Interface Languages section of Internationalizing Queries and Results Presentation for more information, and Supported Interface Languages for a list of supported languages.

feed/opensearch:Query/cse:siteSearch string Specifies that all search results should be pages from a given site.
feed/opensearch:Query/cse:siteSearchFilter string Specifies whether to include or exclude results from the site named in the sitesearch parameter. Supported values are:
  • i: include content from site
  • e: exclude content from site
feed/opensearch:Query/cse:exactTerms string Identifies a phrase that all documents in the search results must contain.
feed/opensearch:Query/cse:excludeTerms string Identifies a word or phrase that should not appear in any documents in the search results.
feed/opensearch:Query/cse:linkSite string Specifies that all search results should contain a link to a particular URL.
feed/opensearch:Query/cse: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. You can also use the Boolean OR query term for this type of query.
feed/opensearch:Query/cse:relatedSite string Specifies that all search results should be pages that are related to the specified URL. The parameter value should be a URL. 
feed/opensearch:Query/cse:dateRestrict string 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.
feed/opensearch:Query/cse:lowRange string Specifies the starting value for a search range. Use cse:lowRange and cse:highRange to append an inclusive search range of lowRange...highRange to the query.
feed/opensearch:Query/cse:highRange string Specifies the ending value for a search range. Use cse:lowRange and cse:highRange to append an inclusive search range of lowRange...highRange to the query.
feed/opensearch:Query/cse:fileType string Restricts results to files of a specified extension. Filetypes supported by Google include:
  • Adobe Portable Document Format (pdf)
  • Adobe PostScript (ps)
  • Lotus 1-2-3 (wk1, wk2, wk3, wk4, wk5, wki, wks, wku)
  • Lotus WordPro (lwp)
  • Macwrite (mw)
  • Microsoft Excel (xls)
  • Microsoft PowerPoint (ppt)
  • Microsoft Word (doc)
  • Microsoft Works (wks, wps, wdb)
  • Microsoft Write (wri)
  • Rich Text Format (rtf)
  • Shockwave Flash (swf)
  • Text (ans, txt).

Additional filetypes may be added in the future. An up-to-date list can always be found in Google's file type FAQ.

feed/opensearch:Query/cse:rights string

Filters based on licensing. Supported values include:

  • cc_publicdomain
  • cc_attribute
  • cc_sharealike
  • cc_noncommercial
  • cc_nonderived
feed/opensearch:Query/cse:searchType string Allowed value is image. If unspecified, results are limited to webpages.
feed/opensearch:Query/cse:imgSize string Restricts results to images of a specified size. Supported values are:
  • icon (small)
  • small|medium|large|xlarge (medium)
  • xxlarge (large)
  • huge (extra-large)
feed/opensearch:Query/cse:imgType string Restricts results to images of a specified type. Supported values are:
  • clipart (clipart)
  • face (face)
  • lineart (lineart)
  • news (news)
  • photo (photo)
feed/opensearch:Query/cse:imgColorType string Restricts results to images of a specified color type. Supported values are:
  • mono (black and white)
  • gray (grayscale)
  • color (color)
feed/opensearch:Query/cse:imgDominantColor string Restricts results to images with a specific dominant color. Supported values are:
  • yellow
  • green
  • teal
  • blue
  • purple
  • pink
  • white
  • gray
  • black
  • brown
feed/opensearch:Query/xmlns:cse string The Custom Search extension to the Google Data namespace.
feed/opensearch:Query/xmlns:opensearch string The Open Search namespace.
feed/opensearch:totalResults object Indicates the estimated total number of search results returned by the query.
feed/opensearch:totalResults/text() long Estimated number of total search results. May not be accurate.
feed/opensearch:startIndex object Indicates the index of the current set of search results into the total set of search results.
feed/opensearch:startIndex/text() integer The index of the current set of search results into the total set of results, where the index of the first result is 1.
feed/cse:promotion nested object Encapsulates all information about a promotion included in search results.
feed/cse:promotion/xmlns:cse string The Custom Search extension to the Google Data namespace.
feed/cse:promotion/title object The title of the promotion.
feed/cse:promotion/title/type string The MIME type of the title text.
feed/cse:promotion/title/text() string The title of the promotion.
feed/cse:promotion/link/href string The URL of the promoted link.
feed/cse:promotion/link/title string An abridged version of this promotion URL, e.g. www.example.com.
feed/cse:promotion/cse:bodyLine object The URL of the block object's link, if it has one.
feed/cse:promotion/cse:bodyLine/title string The block object's text, if it has text. See Google WebSearch Protocol reference for more information on block objects for promotions.
feed/cse:promotion/cse:bodyLine/url string The URL of the block object's link, if it has one.
feed/cse:promotion/cse:image object Encapsulates all information about an image associated with the promotion, if there is one.
feed/cse:promotion/cse:image/src string URL of the image.
feed/cse:promotion/cse:image/height integer Image height in pixels.
feed/cse:promotion/cse:image/width integer Image width in pixels.
feed/cse:context nested object Encapsulates a list of refinement labels (facets) associated with a set of search results.
feed/cse:context/title string The name of the search engine that was used for performing the query.
feed/cse:context/xmlns:cse string The Custom Search extension to the Google Data namespace.
feed/cse:context/cse:facet object Encapsulates information about all refinement labels returned for a search.
feed/cse:context/cse:facet/cse:item object Encapsulates information about a specific refinement label returned for a search.
feed/cse:context/cse:facet/cse:item/label string The label of the given facet item, which you can use to refine your search.
feed/cse:context/cse:facet/cse:item/anchor string The displayable name of the item, which you should use when displaying the item to a human.
feed/cse:searchInformation object Encapsulates all information about a specific search.
feed/cse:searchInformation/cse:searchTime object Indicates the time it took to perform a search.
feed/cse:searchInformation/cse:searchTime/text() double The time it took to perform a search.
feed/cse:searchInformation/cse:formattedSearchTime object Indicates the time it took to perform a search, in local format.
feed/cse:searchInformation/cse:formattedSearchTime/text() string The time it took to perform a search, formatted according to locale.
feed/cse:searchInformation/cse:totalResults object Indicates the estimated total number of results returned by the search.
feed/cse:searchInformation/cse:totalResults/text() long Estimated number of total search results. May not be accurate.
feed/cse:searchInformation/cse:formattedTotalResults object Indicates the estimated total number of results returned by the search, formatted according to locale.
feed/cse:searchInformation/cse:formattedTotalResults/text() string The estimated total number of results returned by the search (may not be accurate), formatted according to locale.
feed/entry nested object Feed entry.
feed/entry/gd:kind string A unique identifier for the type of current object. For this API, it is customsearch#result.
feed/entry/xmlns:cse string The Custom Search extension to the Google Data namespace.
feed/entry/xmlns:gd string The Google Data namespace.
feed/entry/id object The unique ID of a feed entry.
feed/entry/id/text() string The URL of this search result.
feed/entry/updated object Indicates when a result was processed.
feed/entry/updated/text() datetime The date and time that this search result was processed.
feed/entry/title object Indicates the title of the search result.
feed/entry/title/type string The MIME type of the title.
feed/entry/title/text() string The title of the search result.
feed/entry/link/href string The full URL to which the search result is pointing, e.g. http://www.example.com/foo/bar.
feed/entry/link/title string An abridged version of this search result's URL, e.g. www.example.com.
feed/entry/summary object Encapsulates data about the snippet returned for the search result.
feed/entry/summary/type string The MIME type of the snippet.
feed/entry/summary/text() string The snippet of the search result.
feed/entry/cse:cacheId object Indicates the cache ID of the search result.
feed/entry/cse:cacheId/text() string The cache ID of the search result.
feed/entry/cse:mime object Encloses information about the MIME type of the CSE ID.
feed/entry/cse:mime/text() string The MIME type.
feed/entry/cse:formattedUrl object Encapsulates information about the URL displayed after the search result snippet.
feed/entry/cse:formattedUrl/type string The type of the URL displayed after the search result snippet.
feed/entry/cse:formattedUrl/text() string The actual URL displayed after the search result snippet.
feed/entry/cse:PageMap object Encapsulates all information about a PageMap for a specific search result.
feed/entry/cse:PageMap/cse:DataObject object Encapsulates all information about a DataObject included in a PageMap.
feed/entry/cse:PageMap/cse:DataObject/type string The name of the pagemap for this search result. For more information, see PageMap documentation.
feed/entry/cse:PageMap/cse:DataObject/cse:Attribute object Encapsulates all information about a specific PageMap attribute.
feed/entry/cse:PageMap/cse:DataObject/cse:Attribute/name string PageMap named attribute.
feed/entry/cse:PageMap/cse:DataObject/cse:Attribute/value string PageMap value for the given named attribute.
feed/entry/cse:Labels object Encapsulates information about all labels returned for a search result.
feed/entry/cse:Labels/cse:Label object Encapsulates information about a specific label returned for a search result.
feed/entry/cse:Labels/cse:Label/name string Identifies the label of a search result.
feed/entry/cse:Labels/cse:Label/displayName string The user-visible label of a search result. Use this in your user interface.
feed/entry/cse:Image object Encapsulates all information about an image returned in search results.
feed/entry/cse:Image/cse:contextLink/text() string The URL to the page hosting the search result image.
feed/entry/cse:Image/cse:height object Indicates the height of the image.
feed/entry/cse:Image/cse:height/text() integer The height of the image, in pixels.
feed/entry/cse:Image/cse:width object Indicates the width of the image.
feed/entry/cse:Image/cse:width/text() integer The width of the image, in pixels.
feed/entry/cse:Image/cse:byteSize object Indicates the size of the image.
feed/entry/cse:Image/cse:byteSize/text() integer The size of the image, in bytes.
feed/entry/cse:Image/cse:thumbnailLink/text() string The URL of a thumbnail image.
feed/entry/cse:Image/cse:thumbnailHeight object Indicates the height of the thumbnail image.
feed/entry/cse:Image/cse:thumbnailHeight/text() integer The height of the thumbnail image, in pixels.
feed/entry/cse:Image/cse:thumbnailWidth object Indicates the width of the thumbnail image.
feed/entry/cse:Image/cse:thumbnailWidth/text() integer The width of the thumbnail image, in pixels.
feed/cse:spelling object Indicates spelling corrections for the entry.
feed/cse:spelling/cse:correctedQuery object Encapsulates a corrected query.
feed/cse:spelling/cse:correctedQuery/type string The type of query correction (for example, "Did you mean" or "Spell-corrected results").
feed/cse:spelling/cse:correctedQuery/text() string The text of the corrected query.
feed/entry/cse:fileFormat object Indicates the file format of the file returned in search results.
feed/entry/cse:fileFormat/text() string The file type returned in search results.
feed/cse:promotion/displayTitle object Encapsulates the information about the promotion title.
feed/cse:promotion/displayTitle/type string The MIME type of the promotion title.
feed/cse:promotion/displayTitle/text() string The text of the promotion title.
feed/cse:promotion/cse:bodyLine/displayTitle string The body of the promotion.

Try it!

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

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.