XML API reference appendices

Boolean Operators

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

Boolean Operator Definitions

Note: You cannot include spaces in parameter values.

Boolean AND [.]

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


This example removes all results that are in either French or Italian:

Boolean NOT [-]

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


This example removes all results that are in French:

This example removes all results that are in either French or Italian:

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 [|]

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


This example returns all results that are written in either Simplified Chinese or Traditional Chinese:

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:

Boolean Parentheses [()]

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 evaulated.


The example for the NOT [-] operator shows the following construct for request results that are not written in either French or Italian:

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:

URL Escaping

To make an HTTP search request, you must follow certain conventions so that Google can correctly translate your HTTP request and generate an appropriate response.

The HTTP URL schema specifies that an HTTP URL request may only contain certain characters:

  • Alphanumeric characters: (a-z, A-Z, 0-9)
  • Special characters: $ - _ . | + ! * ' ( )
  • Reserved characters: ; / ? : @ = &

Google uses reserved characters to decode URLs and uses some special characters to request search features. Consequently, you should URL-escape all nonalphanumeric characters that occur in search parameter values.

To URL escape a string, convert each sequence of whitespace characters to a single "+" (plus sign) and replace any other nonalphanumeric characters with the hexadecimal encoding that represents the value of that character. The hexadecimal encodings for the special and reserved characters listed above are shown in the following table. Each of these characters should be URL escaped in request parameter values.

Character Hexadecimal
$ %24
- %2D
_ %5F
. %2E
+ %2B
! %21
* %2A
" %22
' %27
( %28
) %29
; %3B
/ %2F
? %3F
: %3A
@ %40
= %3D
& %26
| %7C


Original String URL Escaped String
punch&judy punch%26judy
O'Reilly O%27Reilly

You can find additional information on URL escaping at the W3C and IETF web sites.

Compressing Results

Google can compress search results using HTTP gzip compression. If you can decompress content that has been compressed using the gzip algorithm, you can obtain a 50 percent to 70 percent bandwidth savings, which may improve your response times.

To request that Google return results in compressed format, add the HTTP Accept-Encoding header to your HTTP search request as follows:

Accept-Encoding: gzip

If Google does return the search results using gzip compression, then we include the following line in the returned HTTP headers:

Content-Encoding: gzip

Note: If the Content-Encoding HTTP header is not present in the response as shown above, then Google did not compress the results.

This behavior is specified in the HTTP standard. Please consult that document for additional information about using HTTP gzip compression.

International Values

Character Encoding Schemes

The following table lists the character encoding schemes that Google supports. You can assign the ie and oe parameters the values in either of the first two columns of this table. The values in the first column are nicknames for the encoding schemes; the values in the second column are the standard names for the encoding schemes. Google returns the standard names in XML results, and the standard names are suitable for use in your document's HTTP Content-type headers.

Google name Encoding Associated Supported Languages
latin1 ISO-8859-1 Western European (Catalan, Danish, Dutch, English, Finnish, French, German, Indonesian, Italian, Norwegian, Portuguese, Spanish, Swedish)
latin2 ISO-8859-2 Eastern European (Croatian, Czech, Hungarian, Polish, Romanian, Serbian, Slovak, Slovenian)
latin3 ISO-8859-3  
latin4 ISO-8859-4 Baltic (Estonian, Latvian, Lithuanian)
cyrillic ISO-8859-5 Bulgarian, Russian
arabic ISO-8859-6  
greek ISO-8859-7 Greek
hebrew ISO-8859-8 Hebrew
latin5 ISO-8859-9  
latin6 ISO-8859-10 Icelandic
euc-jp EUC-JP Japanese
euc-kr EUC-KR Korean
sjis Shift_JIS Japanese
big5 Big5 Traditional Chinese
gb GB2312 Simplified Chinese
utf8 UTF-8 All

Supported Interface Languages

Google supports 74 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 am
Arabic ar
Armenian hy
Azerbaijani az
Bengali bn
Bulgarian bg
Burmese my
Catalan ca
Chinese (Simplified) zh-CN
Chinese (Traditional) zh-TW
Croatian hr
Czech cs
Danish da
Dutch nl
English (UK) en-GB
English en
Estonian et
Filipino fil
Finnish fi
French (Canadian) fr-CA
French fr
Georgian ka
German de
Greek el
Gujarati gu
Hebrew iw
Hindi hi
Hungarian hu
Icelandic is
Indonesian id
Italian it
Japanese ja
Kannada kn
Kazakh kk
Khmer km
Korean ko
Kyrgyz ky
Laothian lo
Latvian lv
Lithuanian lt
Macedonian mk
Malay ms
Malayam ml
Marathi mr
Mongolian mn
Nepali ne
Norwegian (Bokmal) no
Persian fa
Polish pl
Portuguese (Brazil) pt-BR
Portuguese (Portugal) pt-PT
Punjabi pa
Romanian ro
Russian ru
Serbian (Latin) sr-Latn
Serbian sr
Sinhalese si
Slovak sk
Slovenian sl
Spanish (Latin America) es-419
Spanish es
Swahili sw
Swedish sv
Tamil ta
Telugu te
Thai th
Turkish tr
Ukrainian uk
Urdu ur
Uzbek uz
Vietnamese vi
Welsh cy

Language Collection Values

You can use the following values to specify a language filter using the lr query parameter:

Language lr Parameter Value
Arabic lang_ar
Bulgarian lang_bg
Catalan lang_ca
Chinese (Simplified) lang_zh-CN
Chinese (Traditional) lang_zh-TW
Croatian lang_hr
Czech lang_cs
Danish lang_da
Dutch lang_nl
English lang_en
Estonian lang_et
Finnish lang_fi
French lang_fr
German lang_de
Greek lang_el
Hebrew lang_iw
Hungarian lang_hu
Icelandic lang_is
Indonesian lang_id
Italian lang_it
Japanese lang_ja
Korean lang_ko
Latvian lang_lv
Lithuanian lang_lt
Norwegian lang_no
Polish lang_pl
Portuguese lang_pt
Romanian lang_ro
Russian lang_ru
Serbian lang_sr
Slovak lang_sk
Slovenian lang_sl
Spanish lang_es
Swedish lang_sv
Turkish lang_tr

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