Query string

Structure

The URI query string component comes after the path component, separated by a question mark (?), and before the optional fragment component, separated by a number sign (#), per the following URI format:

<span id="mwLQ"></span><span class="nc" id="mwLg">scheme</span><span class="w" id="mwLw"> </span><span class="l" id="mwMA">":"</span><span class="w" id="mwMQ"> </span><span class="p" id="mwMg">[</span><span class="l" id="mwMw">"//"</span><span class="w" id="mwNA"> </span><span class="nc" id="mwNQ">authority</span><span class="p" id="mwNg">]</span><span class="w" id="mwNw"> </span><span class="nc" id="mwOA">path</span><span class="w" id="mwOQ"> </span><span class="p" id="mwOg">[</span><span class="l" id="mwOw">"?"</span><span class="w" id="mwPA"> </span><span class="nc" id="mwPQ">query</span><span class="p" id="mwPg">]</span><span class="w" id="mwPw"> </span><span class="p" id="mwQA">[</span><span class="l" id="mwQQ">"#"</span><span class="w" id="mwQg"> </span><span class="nc" id="mwQw">fragment</span><span class="p" id="mwRA">]</span>

The structure of the query string is not well defined in the URI specification itself. Conventionally it consists of one or more key-value pairs, each usually in a key=value form, separated by a delimiter, usually an ampersand (&), as standardised in the likes of RFC 6068 for the mailto: scheme, and the HTML specifications for forms submitted as GET requests.

An example URL with a single query string parameter:

<span id="mwZQ"></span><span class="nl" id="mwZg">https://example.com/over/there?name=ferret</span>

An example URL with multiple query string parameters and a fragment identifier:

<span id="mwbA"></span><span class="nl" id="mwbQ">https://example.com/path/to/page?name=ferret&color=purple#fur</span>

An example email link with query string parameters for pre-populating certain fields:

<span id="mwcw"></span><span class="nl" id="mwdA">mailto:[email protected]?subject=meeting&[email protected]</span>

Web forms

One of the original uses was to contain the content of an HTML form, also known as web form. In particular, when a form containing the fields field1, field2, field3 is submitted, the content of the fields is encoded as a query string as follows:

field1=value1&field2=value2&field3=value3...

• The query string is composed of a series of field-value pairs.
• Within each pair, the field name and value are separated by an equals sign, "=".
• The series of pairs is separated by the ampersand, "&" (semicolons ";" are not recommended by the W3C anymore, see below).

While there is no definitive standard, most web frameworks allow multiple values to be associated with a single field (e.g. field1=value1&field1=value2&field2=value3).

For each field of the form, the query string contains a pair field=value. Web forms may include fields that are not visible to the user; these fields are included in the query string when the form is submitted.

This convention is a W3C recommendation. In the recommendations of 1999, W3C recommended that all web servers support semicolon separators in addition to ampersand separators to allow application/x-www-form-urlencoded query strings in URLs within HTML documents without having to entity escape ampersands. Since 2014, W3C recommends to use only ampersand as query separator.

The form content is only encoded in the URL's query string when the form submission method is GET. The same encoding is used by default when the submission method is POST, but the result is submitted as the HTTP request body rather than being included in a modified URL.

Indexed search

Before forms were added to HTML, browsers rendered the –<isindex> element as a single-line text-input control. The text entered into this control was sent to the server as a query string addition to a GET request for the base URL or another URL specified by the action attribute. This was intended to allow web servers to use the provided text as query criteria so they could return a list of matching pages.

When the text input into the indexed search control is submitted, it is encoded as a query string as follows:

argument1+argument2+argument3...

• The query string is composed of a series of arguments by parsing the text into words at the spaces.
• The series is separated by the plus sign, '+'.

Though the <isindex> element is deprecated and most browsers no longer support or render it, there are still some vestiges of indexed search in existence. For example, this is the source of the special handling of plus sign, '+' within browser URL percent encoding (which today, with the deprecation of indexed search, is all but redundant with %20). Also some web servers supporting CGI (e.g., Apache) will process the query string into command line arguments if it does not contain an equals sign, '=' (as per section 4.4 of CGI 1.1). Some CGI scripts still depend on and use this historic behavior for URLs embedded in HTML.

URL encoding

Some characters cannot be part of a URL (for example, the space) and some other characters have a special meaning in a URL: for example, the character # can be used to further specify a subsection (or fragment) of a document. In HTML forms, the character = is used to separate a name from a value. The URI generic syntax uses URL encoding to deal with this problem, while HTML forms make some additional substitutions rather than applying percent encoding for all such characters. SPACE is encoded as '+' or "%20".

HTML 5 specifies the following transformation for submitting HTML forms with the "GET" method to a web server. The following is a brief summary of the algorithm:

• Characters that cannot be converted to the correct charset are replaced with HTML numeric character references
• SPACE is encoded as '+' or '%20'
• Letters (A–Z and a–z), numbers (0–9) and the characters '~','-','.' and '_' are left as-is
• + is encoded by %2B
• All other characters are encoded as a %HH hexadecimal representation with any non-ASCII characters first encoded as UTF-8 (or other specified encoding)

The octet corresponding to the tilde ("~") is permitted in query strings by RFC3986 but required to be percent-encoded in HTML forms to "%7E".

The encoding of SPACE as '+' and the selection of "as-is" characters distinguishes this encoding from RFC 3986.

Limitations

As discussed in the HTTP specification, web services have sometimes imposed arbitrary length restrictions on URIs, rejecting requests they deem too long with 414 (Request-URI Too Long) status codes:

Various ad hoc limitations on request-line length are found in practice. It is RECOMMENDED that all HTTP senders and recipients support, at a minimum, request-line lengths of 8000 octets.

A workaround, applicable to HTML forms, is to configure the form to be submitted with the POST method instead of GET, thus the form data is sent in the HTTP request separated from the URI, rather than using the URI query string as in the GET method. Length limits on HTTP request bodies are typically much larger than those imposed on URI length.