JSON API reference

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
Guinea countryGN
Guinea-Bissau countryGW
Guyana countryGY
Haiti countryHT
Heard Island and Mcdonald Islands countryHM
Holy See (Vatican City State) countryVA
Honduras countryHN
Hong Kong countryHK
Hungary countryHU
Iceland countryIS
India countryIN
Indonesia countryID
Iran, Islamic Republic of countryIR
Iraq countryIQ
Ireland countryIE
Israel countryIL
Italy countryIT
Jamaica countryJM
Japan countryJP
Jordan countryJO
Kazakhstan countryKZ
Kenya countryKE
Kiribati countryKI
Korea, Democratic People's Republic of countryKP
Korea, Republic of countryKR
Kuwait countryKW
Kyrgyzstan countryKG
Lao People's Democratic Republic countryLA
Latvia countryLV
Lebanon countryLB
Lesotho countryLS
Liberia countryLR
Libyan Arab Jamahiriya countryLY
Liechtenstein countryLI
Lithuania countryLT
Luxembourg countryLU
Macao countryMO
Macedonia, the Former Yugosalv Republic of countryMK
Madagascar countryMG
Malawi countryMW
Malaysia countryMY
Maldives countryMV
Mali countryML
Malta countryMT
Marshall Islands countryMH
Martinique countryMQ
Mauritania countryMR
Mauritius countryMU
Mayotte countryYT
Mexico countryMX
Micronesia, Federated States of countryFM
Moldova, Republic of countryMD
Monaco countryMC
Mongolia countryMN
Montserrat countryMS
Morocco countryMA
Mozambique countryMZ
Myanmar countryMM
Namibia countryNA
Nauru countryNR
Nepal countryNP
Netherlands countryNL
Netherlands Antilles countryAN
New Caledonia countryNC
New Zealand countryNZ
Nicaragua countryNI
Niger countryNE
Nigeria countryNG
Niue countryNU
Norfolk Island countryNF
Northern Mariana Islands countryMP
Norway countryNO
Oman countryOM
Pakistan countryPK
Palau countryPW
Palestinian Territory countryPS
Panama countryPA
Papua New Guinea countryPG
Paraguay countryPY
Peru countryPE
Philippines countryPH
Pitcairn countryPN
Poland countryPL
Portugal countryPT
Puerto Rico countryPR
Qatar countryQA
Reunion countryRE
Romania countryRO
Russian Federation countryRU
Rwanda countryRW
Saint Helena countrySH
Saint Kitts and Nevis countryKN
Saint Lucia countryLC
Saint Pierre and Miquelon countryPM
Saint Vincent and the Grenadines countryVC
Samoa countryWS
San Marino countrySM
Sao Tome and Principe countryST
Saudi Arabia countrySA
Senegal countrySN
Serbia and Montenegro countryCS
Seychelles countrySC
Sierra Leone countrySL
Singapore countrySG
Slovakia countrySK
Slovenia countrySI
Solomon Islands countrySB
Somalia countrySO
South Africa countryZA
South Georgia and the South Sandwich Islands countryGS
Spain countryES
Sri Lanka countryLK
Sudan countrySD
Suriname countrySR
Svalbard and Jan Mayen countrySJ
Swaziland countrySZ
Sweden countrySE
Switzerland countryCH
Syrian Arab Republic countrySY
Taiwan, Province of China countryTW
Tajikistan countryTJ
Tanzania, United Republic of countryTZ
Thailand countryTH
Togo countryTG
Tokelau countryTK
Tonga countryTO
Trinidad and Tobago countryTT
Tunisia countryTN
Turkey countryTR
Turkmenistan countryTM
Turks and Caicos Islands countryTC
Tuvalu countryTV
Uganda countryUG
Ukraine countryUA
United Arab Emirates countryAE
United Kingdom countryUK
United States countryUS
United States Minor Outlying Islands countryUM
Uruguay countryUY
Uzbekistan countryUZ
Vanuatu countryVU
Venezuela countryVE
Vietnam countryVN
Virgin Islands, British countryVG
Virgin Islands, U.S. countryVI
Wallis and Futuna countryWF
Western Sahara countryEH
Yemen countryYE
Yugoslavia countryYU
Zambia countryZM
Zimbabwe countryZW

Country Codes

The following table lists the two-letter country codes that can be used as values of the "gl" parameter:

Country Country Code
Afghanistan af
Albania al
Algeria dz
American Samoa as
Andorra ad
Angola ao
Anguilla ai
Antarctica aq
Antigua and Barbuda ag
Argentina ar
Armenia am
Aruba aw
Australia au
Austria at
Azerbaijan az
Bahamas bs
Bahrain bh
Bangladesh bd
Barbados bb
Belarus by
Belgium be
Belize bz
Benin bj
Bermuda bm
Bhutan bt
Bolivia bo
Bosnia and Herzegovina ba
Botswana bw
Bouvet Island bv
Brazil br
British Indian Ocean Territory io
Brunei Darussalam bn
Bulgaria bg
Burkina Faso bf
Burundi bi
Cambodia kh
Cameroon cm
Canada ca
Cape Verde cv
Cayman Islands ky
Central African Republic cf
Chad td
Chile cl
China cn
Christmas Island cx
Cocos (Keeling) Islands cc
Colombia co
Comoros km
Congo cg
Congo, the Democratic Republic of the cd
Cook Islands ck
Costa Rica cr
Cote D'ivoire ci
Croatia hr
Cuba cu
Cyprus cy
Czech Republic cz
Denmark dk
Djibouti dj
Dominica dm
Dominican Republic do
Ecuador ec
Egypt eg
El Salvador sv
Equatorial Guinea gq
Eritrea er
Estonia ee
Ethiopia et
Falkland Islands (Malvinas) fk
Faroe Islands fo
Fiji fj
Finland fi
France fr
French Guiana gf
French Polynesia pf
French Southern Territories tf
Gabon ga
Gambia gm
Georgia ge
Germany de
Ghana gh
Gibraltar gi
Greece gr
Greenland gl
Grenada gd
Guadeloupe gp
Guam gu
Guatemala gt
Guinea gn
Guinea-Bissau gw
Guyana gy
Haiti ht
Heard Island and Mcdonald Islands hm
Holy See (Vatican City State) va
Honduras hn
Hong Kong hk
Hungary hu
Iceland is
India in
Indonesia id
Iran, Islamic Republic of ir
Iraq iq
Ireland ie
Israel il
Italy it
Jamaica jm
Japan jp
Jordan jo
Kazakhstan kz
Kenya ke
Kiribati ki
Korea, Democratic People's Republic of kp
Korea, Republic of kr
Kuwait kw
Kyrgyzstan kg
Lao People's Democratic Republic la
Latvia lv
Lebanon lb
Lesotho ls
Liberia lr
Libyan Arab Jamahiriya ly
Liechtenstein li
Lithuania lt
Luxembourg lu
Macao mo
Macedonia, the Former Yugosalv Republic of mk
Madagascar mg
Malawi mw
Malaysia my
Maldives mv
Mali ml
Malta mt
Marshall Islands mh
Martinique mq
Mauritania mr
Mauritius mu
Mayotte yt
Mexico mx
Micronesia, Federated States of fm
Moldova, Republic of md
Monaco mc
Mongolia mn
Montserrat ms
Morocco ma
Mozambique mz
Myanmar mm
Namibia na
Nauru nr
Nepal np
Netherlands nl
Netherlands Antilles an
New Caledonia nc
New Zealand nz
Nicaragua ni
Niger ne
Nigeria ng
Niue nu
Norfolk Island nf
Northern Mariana Islands mp
Norway no
Oman om
Pakistan pk
Palau pw
Palestinian Territory, Occupied ps
Panama pa
Papua New Guinea pg
Paraguay py
Peru pe
Philippines ph
Pitcairn pn
Poland pl
Portugal pt
Puerto Rico pr
Qatar qa
Reunion re
Romania ro
Russian Federation ru
Rwanda rw
Saint Helena sh
Saint Kitts and Nevis kn
Saint Lucia lc
Saint Pierre and Miquelon pm
Saint Vincent and the Grenadines vc
Samoa ws
San Marino sm
Sao Tome and Principe st
Saudi Arabia sa
Senegal sn
Serbia and Montenegro cs
Seychelles sc
Sierra Leone sl
Singapore sg
Slovakia sk
Slovenia si
Solomon Islands sb
Somalia so
South Africa za
South Georgia and the South Sandwich Islands gs
Spain es
Sri Lanka lk
Sudan sd
Suriname sr
Svalbard and Jan Mayen sj
Swaziland sz
Sweden se
Switzerland ch
Syrian Arab Republic sy
Taiwan, Province of China tw
Tajikistan tj
Tanzania, United Republic of tz
Thailand th
Timor-Leste tl
Togo tg
Tokelau tk
Tonga to
Trinidad and Tobago tt
Tunisia tn
Turkey tr
Turkmenistan tm
Turks and Caicos Islands tc
Tuvalu tv
Uganda ug
Ukraine ua
United Arab Emirates ae
United Kingdom uk
United States us
United States Minor Outlying Islands um
Uruguay uy
Uzbekistan uz
Vanuatu vu
Venezuela ve
Viet Nam vn
Virgin Islands, British vg
Virgin Islands, U.S. vi
Wallis and Futuna wf
Western Sahara eh
Yemen ye
Zambia zm
Zimbabwe zw