Pass Query Parameters in cURL Without Manual Encoding

When sending HTTP requests with curl, manually encoding URL query parameters (such as replacing spaces with %20 or special characters with their hex equivalents) is tedious and prone to formatting errors. This article explains how to cleanly pass query parameters using curl’s built-in features, specifically the modern --url-query flag and the classic --data-urlencode option paired with -G. These methods ensure your parameters are automatically and safely encoded before transmission.

Method 1: The Modern Way Using --url-query

Available in curl version 7.82.0 and later, the --url-query option is the cleanest and most direct way to append URL-encoded parameters to a GET request. It automatically formats and appends the key-value pairs to the URL you provide.

Basic Syntax

To use this option, simply define your base URL and use the --url-query flag for each parameter:

curl --url-query "search=query parameters" --url-query "limit=10" https://api.example.com/v1/resource

curl will automatically convert the space in “query parameters” to %20 (or +) and construct the final URL: https://api.example.com/v1/resource?search=query%20parameters&limit=10.

Reading from a File

If you have a large number of parameters or sensitive data, you can load the query parameters directly from a file. Prepend the filename with @:

curl --url-query "@params.txt" https://api.example.com/v1/resource

Method 2: The Classic Way Using -G and --data-urlencode

If you are using an older version of curl (prior to 7.82.0), the standard approach is to combine the GET flag (-G or --get) with the --data-urlencode flag.

By default, --data-urlencode sends data via a POST request. Adding the -G flag forces curl to take that encoded data, append it to the URL with a ? separator, and send it as a GET request instead.

Basic Syntax

Use a separate --data-urlencode flag for each key-value pair:

curl -G \
  --data-urlencode "search=query parameters" \
  --data-urlencode "category=tech & gadgets" \
  https://api.example.com/v1/resource

How it is Processed

In the example above, the ampersand (&) in “tech & gadgets” and the spaces are automatically encoded. The resulting request will be sent to:

https://api.example.com/v1/resource?search=query%20parameters&category=tech%20%26%20gadgets

This method is highly compatible and works across almost all legacy environments where curl is installed.