Skip to content

URLSearchParams

The URLSearchParams class provides utilities for working with URL query strings according to the WHATWG URL Standard. It implements Python's MutableMapping interface, allowing Pythonic dictionary-style access.

Creating URLSearchParams

The URLSearchParams constructor accepts several initialization formats:

From a Query String

from pywhatwgurl import URLSearchParams

# With or without leading "?"
params = URLSearchParams("name=John&age=30")
params = URLSearchParams("?name=John&age=30")

Query String Parsing

Query strings are parsed using the application/x-www-form-urlencoded parser.

From a Dictionary

params = URLSearchParams({"name": "John", "age": "30"})

From a List of Tuples

Useful when you have duplicate keys:

params = URLSearchParams([
    ("tag", "python"),
    ("tag", "url"),
    ("tag", "parsing")
])

Empty

params = URLSearchParams()

Reading Parameters

params = URLSearchParams("name=John&age=30")

# Get a value (raises KeyError if not found)
print(params["name"])  # "John"

# Check if a parameter exists
if "name" in params:
    print("Name is set!")

# Safe get with default
value = params.get("missing")  # None

get_all(name) for Multiple Values

Returns all values for a parameter as a tuple. Corresponds to getAll() in the spec:

params = URLSearchParams("tag=a&tag=b&tag=c")
print(params.get_all("tag"))      # ("a", "b", "c")
print(params.get_all("missing"))  # ()

Modifying Parameters

params = URLSearchParams("tag=a&tag=b")

# Set a value (replaces all existing values for this key)
params["tag"] = "new"
print(str(params))  # "tag=new"

# Delete a key
del params["tag"]

append(name, value) for Multiple Values

The append() method adds a parameter without removing existing ones:

params = URLSearchParams("tag=a")
params.append("tag", "b")
print(str(params))  # "tag=a&tag=b"

delete(name, value) for Specific Values

The delete() method can remove only matching values:

params = URLSearchParams("a=1&a=2&a=3")
params.delete("a", "2")  # Only remove a=2
print(str(params))  # "a=1&a=3"

Iterating

params = URLSearchParams("a=1&b=2&c=3")

# Iterate over key-value pairs
for key, value in params.items():
    print(f"{key}: {value}")

# Get all keys
for key in params.keys():
    print(key)

# Get all values
for value in params.values():
    print(value)

Alternative Iterations

params = URLSearchParams("a=1&b=2")

print(list(params.keys()))    # ["a", "b"]
print(list(params.values()))  # ["1", "2"]
print(list(params.items()))   # [("a", "1"), ("b", "2")]

Size and Length

Use len() to get the number of parameters. Corresponds to the size property:

params = URLSearchParams("a=1&b=2&c=3")
print(len(params))  # 3

Sorting

sort()

The sort() method sorts parameters by key using a stable sort:

params = URLSearchParams("c=3&a=1&b=2")
params.sort()
print(str(params))  # "a=1&b=2&c=3"

String Conversion

Use str() to get the encoded query string (without ?). This uses the application/x-www-form-urlencoded serializer:

params = URLSearchParams({"name": "John Doe", "city": "New York"})
print(str(params))  # "name=John+Doe&city=New+York"

Space Encoding

URLSearchParams encodes spaces as + (not %20) per the application/x-www-form-urlencoded format, which is standard for query strings and HTML form data.

Using with URL

URLSearchParams integrates seamlessly with the URL class via the searchParams property:

from pywhatwgurl import URL

url = URL("https://example.com/search?q=python")

# Access search_params with dictionary-style syntax
print(url.search_params["q"])  # "python"

# Modify search_params (automatically updates the URL)
url.search_params["q"] = "javascript"
url.search_params["page"] = "2"

print(url.href)  # "https://example.com/search?q=javascript&page=2"

# Delete parameters
del url.search_params["page"]
print(url.search)  # "?q=javascript"

URL Update Steps

When search_params is modified, the URL's query is automatically updated per the update steps defined in the spec.

Practical Examples

Building a Query String

from pywhatwgurl import URLSearchParams

params = URLSearchParams()
params["search"] = "python url parsing"
params["category"] = "libraries"
params["sort"] = "stars"
params["order"] = "desc"

query = str(params)
# "search=python+url+parsing&category=libraries&sort=stars&order=desc"

Parsing Form Data

The application/x-www-form-urlencoded format is used for HTML form submissions:

form_data = "username=john_doe&email=john%40example.com&newsletter=on"
params = URLSearchParams(form_data)

print(params["username"])      # "john_doe"
print(params["email"])         # "john@example.com"
print("newsletter" in params)  # True

Handling Multiple Values

params = URLSearchParams()

# Add multiple tags (use append for duplicates)
for tag in ["python", "url", "whatwg", "parsing"]:
    params.append("tag", tag)

print(params.get_all("tag"))  # ("python", "url", "whatwg", "parsing")
print(str(params))            # "tag=python&tag=url&tag=whatwg&tag=parsing"

Further Reading

Next Steps