JSON API reference

  • Boolean OR search finds documents containing at least one of a series of terms.

  • Boolean operators like AND (.), NOT (-), and OR (|) can be used in cr and lr parameters to refine search results.

  • Parentheses can be used with Boolean operators to control the order of evaluation in search queries.

  • You can internationalize queries by specifying interface language and filtering results by language using parameters like "hl" and "lr".

  • SafeSearch can be used to filter adult content from search results using the "safe" parameter.
Boolean OR Search [ OR ]
Description

The OR query term retrieves documents that include one of a series of (two or more) query terms. To use the OR query term, you would insert the search term OR, in uppercase letters, between each term in the series.

You can also use the "as_oq" request parameter (like "as_oq=London+Paris") to submit a search for any term in a set of terms.

Note: If a search request specifies the query "London+OR+Paris", the search results will include documents containing at least one of those two words. In some cases, documents in the search results may contain both words.
Examples

Search for London or Paris:

User input:london OR paris Query term:q=london+OR+paris

Search for vacation and either London or Paris:

Query term:q=vacation+london+OR+paris

Search for vacation and one of London, Paris or chocolates:

Query term:  q=vacation+london+OR+paris+OR+chocolates

Search for vacation and chocolates and either london or paris, with the least weight being given to chocolates:

Query term:  q=vacation+london+OR+paris+chocolates

Search for vacation, chocolates and flowers in documents that also contain either London or Paris:

Query term:  q=vacation+london+OR+paris+chocolates+flowers

Search for vacation and one of London or Paris and also search for one of chocolates or flowers:

Query term:  q=vacation+london+OR+paris+chocolates+OR+flowers

Boolean Operators

You may use Boolean operators in values for the following parameters:

  • cr
  • lr

Boolean Operator Definitions

Note: You cannot include spaces in parameter values.

Boolean AND [.]
Description

The AND operator (.) returns results that are in the intersection of the collections to either side of the "." operator.
Examples

This example removes all results that are in either French or Italian:
lr=(-lang_fr).(-lang_it)

Boolean NOT [-]
Description

The NOT operator (-) removes all results that are in the collection immediately following the minus ("-") operator.
Examples

This example removes all results that are in French:
lr=-lang_fr

This example removes all results that are in either French or Italian:
lr=(-lang_fr).(-lang_it)

Note: You may have noticed that the second example above uses the Boolean AND operator to specify that results should not be written in French or Italian. Depending on the placement of parentheses in your query, you could use either the Boolean AND operator or the Boolean OR operator to express this query. This is because if a document is written in French, then it is not written in Italian. Thus, your Boolean statement must express that the document is not written in French and the document is not written in Italian.

Boolean OR [|]
Description

The OR operator (|) returns results that are in either the collection to the left or the collection to the right of the pipe ("|") operator.
Examples

This example returns all results that are written in either Simplified Chinese or Traditional Chinese:
lr=lang_zh-TW|lang_zh-CN

This example requests all results that are not written in French or Italian; notice that it places parentheses in a different location than the sample query for the Boolean AND operator:
lr=-(lang_fr|lang_it)


Boolean Parentheses [()]
Description

This operator lets you ensure that all terms in the innermost set of parentheses are evaluated before terms outside the parentheses are evaluated. You can use parentheses to adjust the order in which terms are evaluated.
Examples

The example for the NOT [-] operator shows the following construct for request results that are not written in either French or Italian:
lr=(-lang_fr).(-lang_it)

The example for the OR (|) operator also shows a request for results not written in French of Italian. Since the latter example uses the OR operator rather than the AND operator, it also must change the location of the parentheses:
lr=-(lang_fr|lang_it)

Internationalizing Queries and Results Presentation

The Google WebSearch service enables you to search for documents in multiple languages. You can specify the character encoding that should be used to interpret your HTTP request and to encode your response. You can also filter results to only include documents written in certain languages.

The following sections discuss issues related to searching in multiple languages:

Interface Languages

You can use the "hl" request parameter to identify the language of your graphical interface. The "hl" parameter value may affect search results, especially on international queries when language restriction (using the "lr" parameter) is not explicitly specified. In such cases, the "hl" parameter may promote search results in the same language as the user's input language.

We suggest you explicitly set the "hl" parameter in search results to ensure that Google selects the highest quality search results for each query.

Please see the Supported Interface Languages section for a complete list of valid values for the "hl" parameter.

Simplified Chinese and Traditional Chinese are two writing variants of the Chinese language. The same concept may be written differently in each variant. Given a query in one of the variants, the Google WebSearch service can return results that include pages in both variants.

To use this feature:

  1. Set the "c2coff" request parameter to 0
    and
  2. Do one of the following:
    • Do not set the "lr" request parameter
      or
    • Set the "lr" request parameter to lr=lang_zh-TW|lang_zh-CN

The following example shows the query parameters you would include in a request for results in both simplified and traditional Chinese. (Note that additional required information, such as the "client", is not included in the example.)

search?hl=zh-CN
    &lr=lang_zh-TW|lang_zh-CN
    &c2coff=0

Filtering Results

Google WebSearch provides a number of ways to filter your search results:

Automatic Filtering of Search Results

In an effort to provide the best search results possible, Google uses two techniques to automatically filter search results that are generally considered undesirable:

  • Duplicate Content—If multiple documents contain the same information, then only the most relevant document of that set is included in your search results.

  • Host Crowding—If there are many search results from the same site, Google may not show all the results from that site or may show the results lower in
    the ranking than they otherwise would have been.

We recommend you leave these filters on for typical search requests because the filters significantly enhance the quality of most search results. However, you can bypass these automatic filters by setting the "filter" query parameter to 0 in your search request.

Filtering Adult Content with SafeSearch

Many Google customers do not want to display search results for sites that contain adult content. Using our SafeSearch filter, you can screen for search results that contain adult content and eliminate them. Google's filters use proprietary technology to check keywords, phrases and URLs. While no filters are 100 percent accurate, SafeSearch will remove the overwhelming majority of adult content from your search results.

Google strives to keep SafeSearch as current and comprehensive as possible by continually crawling the Web and by incorporating updates from user suggestions.

You can adjust the degree to which Google filters your results for adult content using the "safe" query parameter. The following table explains Google's SafeSearch settings and how those settings will affect your search results:

SafeSearch Level Description
high Enables a stricter version of safe search.
medium Blocks web pages containing pornography and other explicit sexual content.
off Does not filter adult content from search results.

* The default SafeSearch setting is off.

International Values

Supported Interface Languages

Google supports more than 80 languages. The default interface language is English. The following list identifies all of the interface languages that Google supports.

Display Language hl Parameter Value
Afrikaans af
Albanian sq
Amharic sm
Arabic ar
Azerbaijani az
Basque eu
Belarusian be
Bengali bn
Bihari bh
Bosnian bs
Bulgarian bg
Catalan ca
Chinese (Simplified) zh-CN
Chinese (Traditional) zh-TW
Croatian hr
Czech cs
Danish da
Dutch nl
English en
Esperanto eo
Estonian et
Faroese fo
Finnish fi
French fr
Frisian fy
Galician gl
Georgian ka
German de
Greek el
Gujarati gu
Hebrew iw
Hindi hi
Hungarian hu
Icelandic is
Indonesian id
Interlingua ia
Irish ga
Italian it
Japanese ja
Javanese jw
Kannada kn
Korean ko
Latin la
Latvian lv
Lithuanian lt
Macedonian mk
Malay ms
Malayam ml
Maltese mt
Marathi mr
Nepali ne
Norwegian no
Norwegian (Nynorsk) nn
Occitan oc
Persian fa
Polish pl
Portuguese (Brazil) pt-BR
Portuguese (Portugal) pt-PT
Punjabi pa
Romanian ro
Russian ru
Scots Gaelic gd
Serbian sr
Sinhalese si
Slovak sk
Slovenian sl
Spanish es
Sudanese su
Swahili sw
Swedish sv
Tagalog tl
Tamil ta
Telugu te
Thai th
Tigrinya ti
Turkish tr
Ukrainian uk
Urdu ur
Uzbek uz
Vietnamese vi
Welsh cy
Xhosa xh
Zulu zu

Country Collection Values

You can use the following values to specify a country filter using the "cr" query parameter:

Country Country Collection Name
Afghanistan countryAF
Albania countryAL
Algeria countryDZ
American Samoa countryAS
Andorra countryAD
Angola countryAO
Anguilla countryAI
Antarctica countryAQ
Antigua and Barbuda countryAG
Argentina countryAR
Armenia countryAM
Aruba countryAW
Australia countryAU
Austria countryAT
Azerbaijan countryAZ
Bahamas countryBS
Bahrain countryBH
Bangladesh countryBD
Barbados countryBB
Belarus countryBY
Belgium countryBE
Belize countryBZ
Benin countryBJ
Bermuda countryBM
Bhutan countryBT
Bolivia countryBO
Bosnia and Herzegovina countryBA
Botswana countryBW
Bouvet Island countryBV
Brazil countryBR
British Indian Ocean Territory countryIO
Brunei Darussalam countryBN
Bulgaria countryBG
Burkina Faso countryBF
Burundi countryBI
Cambodia countryKH
Cameroon countryCM
Canada countryCA
Cape Verde countryCV
Cayman Islands countryKY
Central African Republic countryCF
Chad countryTD
Chile countryCL
China countryCN
Christmas Island countryCX
Cocos (Keeling) Islands countryCC
Colombia countryCO
Comoros countryKM
Congo countryCG
Congo, the Democratic Republic of the countryCD
Cook Islands countryCK
Costa Rica countryCR
Cote D'ivoire countryCI
Croatia (Hrvatska) countryHR
Cuba countryCU
Cyprus countryCY
Czech Republic countryCZ
Denmark countryDK
Djibouti countryDJ
Dominica countryDM
Dominican Republic countryDO
East Timor countryTP
Ecuador countryEC
Egypt countryEG
El Salvador countrySV
Equatorial Guinea countryGQ
Eritrea countryER
Estonia countryEE
Ethiopia countryET
European Union countryEU
Falkland Islands (Malvinas) countryFK
Faroe Islands countryFO
Fiji countryFJ
Finland countryFI
France countryFR
France, Metropolitan countryFX
French Guiana countryGF
French Polynesia countryPF
French Southern Territories countryTF
Gabon countryGA
Gambia countryGM
Georgia countryGE
Germany countryDE
Ghana countryGH
Gibraltar countryGI
Greece countryGR
Greenland countryGL
Grenada countryGD
Guadeloupe countryGP
Guam countryGU
Guatemala countryGT