Skip to main content
The Custom Search JSON API exposes a rich set of filter parameters that let you constrain results along every dimension Google’s index supports: publication date, content language, user geography, file format, licensing rights, specific domains, and exact or excluded term matching. You can combine these filters freely in a single request. This guide covers each parameter in detail with accepted values, practical examples, and guidance on combining filters effectively.

​
Parameter reference table

The table below summarises every filter parameter covered in this guide. All parameters are passed as query string arguments on a GET request to https://www.googleapis.com/customsearch/v1.

​
Date and recency filters

​
dateRestrict

Limit results to pages indexed within a rolling time window relative to today. The format is a single letter (d, w, m, or y) followed by a positive integer.

​
sort

Override the default relevance ranking. Setting sort=date returns results ordered by the date Google last indexed the page — the most recently crawled pages appear first. This is most useful when you need fresh content and relevance is a secondary concern.
Combine sort=date with dateRestrict for the strongest recency signal. sort=date alone changes the ordering but not the time window; dateRestrict alone filters the window but preserves relevance ordering.

​
Language and geography filters

​
lr — Language restrict

Restrict results to pages written in a specific language. The format is lang_ followed by an ISO 639-1 language code.

​
gl — Geolocation

Specify the geographic location of the end user as a two-letter ISO 3166-1 alpha-2 country code. This parameter influences (but does not strictly restrict) result ranking — pages relevant to users in that country will score higher.
Common gl values: us, gb, ca, au, de, fr, in, br, jp, mx, es, it, kr, nl.

​
cr — Country restrict

Strictly restrict results to pages originating from a specific country, regardless of the user’s geography. The format is the word country followed by a two-letter uppercase country code.
cr restricts the origin of the page (typically inferred from the domain’s country TLD or hosting). gl signals the user’s country to influence ranking. You can use both together.

​
File type filter

​
fileType

Return only results of a specific file format. Google’s index supports a wide range of document types:
You can also use the filetype: operator directly inside q for the same effect:

​
Rights and licensing filter

​
rights

Restrict results to pages whose content is licensed under a specific Creative Commons license. You can combine multiple values with | (pipe):
The rights filter relies on metadata declared by the publisher. It does not guarantee that content is actually free to reuse. Always verify licensing directly on the source page before republishing or incorporating content.

​
Site targeting filters

​
siteSearch + siteSearchFilter

Control which domain(s) contribute to your results on a per-request basis. Set siteSearch to a domain and siteSearchFilter to i (include) or e (exclude).
Return results only from developer.mozilla.org:
siteSearch accepts one domain per request. To include or exclude multiple domains, configure them permanently in the Programmable Search Engine Control Panel as Included sites or Excluded sites.

​
Term-level filters

​
exactTerms

Require that every result contains a specific exact phrase. This is the API equivalent of wrapping terms in quotes in a Google search. Use it to eliminate loosely related results when your query terms are ambiguous.

​
excludeTerms

Exclude any result that contains the specified term or phrase. This is the API equivalent of the -term operator in a Google search.

​
orTerms

Return results that contain at least one of the specified terms, in addition to the main query. Terms are separated by spaces (treated as OR). This broadens results without requiring all terms to appear.

​
Combining filters

Filters compose freely. The example below performs a tightly scoped query: English-language PDF research papers on neural architecture search, published within the last year, from academic domains, excluding blog content:
Start with broad filters and progressively tighten them. If dateRestrict=d7 yields too few results, try m1. If exactTerms removes too many valid results, remove it and add the phrase directly to q as a quoted string instead.

​
Filter interaction reference

Understanding how filters interact helps you avoid accidentally over-constraining your query:
  • dateRestrict filters the result set to a time window.
  • sort=date orders the filtered set by recency.
  • Use both together for “most recent results within a window”.
  • sort=date without dateRestrict re-ranks all matching results by date, which can surface very old pages if they were recently re-crawled.
  • lr=lang_en restricts the language of the content.
  • gl=us signals the user’s country, influencing ranking but not strictly filtering.
  • cr=countryUS restricts the origin country of the page, not its language.
  • You can use all three simultaneously for maximum geographic and linguistic precision.
Both restrict results to a domain, but they behave differently:
  • siteSearch=example.com&siteSearchFilter=i is a structured filter applied by the API before ranking.
  • q=site:example.com+your+terms uses Google’s site: operator inside the query string. The siteSearch parameter is preferred for programmatic use because it keeps the domain out of the query and makes the intent explicit.
Both require an exact phrase in results, but exactTerms applies as a hard post-filter, while a quoted string in q is weighted heavily in ranking. For strict enforcement, use exactTerms; for softer preference, embed the quoted phrase in q.

​
Error reference

The free tier allows 100 queries per day per project. The paid tier supports up to 10,000 queries per day per project. Filter parameters do not affect query cost — each API call counts as one query regardless of how many filters you apply.