PercentURL / Guides / curl URL Encode
curl URL Encode: Safely Add Query Values
Build a query string from raw values in the terminal. Let curl encode each value while keeping the parameter separators in place.
--get with one --data-urlencode option per parameter. Quote each argument so the shell does not treat spaces or & as command syntax.curl --get --data-urlencode 'q=red & blue' --data-urlencode 'page=2' 'https://api.example.test/search'Here, q is one value: red & blue. curl URL-encodes that value, then joins the fields as query parameters. The ampersand inside the search text is data; the separator between q and page is query structure.
What each option does
--data-urlencode 'q=red & blue'encodes the content after=. curl expects the parameter name in this form to already be URL-encoded.--getmoves the supplied data into the URL query and makes an HTTP GET request. Without it, curl's data options send an HTTP POST by default.- Repeating
--data-urlencodegives each value its own field. curl joins the fields with query separators; do not encode the whole query string as one value.
The example uses shell quoting that works in Bash/Zsh and PowerShell. In Windows PowerShell, call curl.exe to avoid the older curl alias. For Command Prompt, use double quotes around the arguments so & stays inside the quoted value.
GET query or POST form?
Use --get when the endpoint expects parameters in the URL:
curl --get --data-urlencode 'q=red & blue' 'https://api.example.test/search'For a form-style POST, omit --get:
curl --data-urlencode 'q=red & blue' 'https://api.example.test/search'Choose based on the API's documented method and content type. --data-urlencode is for URL-encoded form fields; it does not turn a request into JSON. If the API expects JSON, send the documented JSON body instead.
Common mistakes and quick fixes
| Symptom | Likely cause | Fix |
|---|---|---|
The command splits at & or runs another command | The value or URL was not quoted for your shell. | Quote each argument. In Bash/Zsh and PowerShell, single quotes are convenient; in Command Prompt, use double quotes. |
| The server receives POST instead of GET | --get was omitted. | Add --get only when the endpoint expects a GET query. |
| The server sees an unexpected extra parameter | A complete query string was passed as one field, so its internal separators became encoded data. | Pass each name/value pair as a separate --data-urlencode argument. |
A slash becomes %252F | The value was already encoded as %2F; encoding it again escapes the percent sign. | Pass the raw slash once if it is data, or leave an intentionally encoded value alone. Do not pre-encode and then run it through --data-urlencode. |
When you need to encode one value by hand
If you are building a command in another language or need to inspect one raw query value, encode that component alone. Keep the URL's ?, &, and = separators outside the value. The URL Encoder Online guide explains the difference between a parameter value and a full URL; use the PercentURL encoder for a one-off conversion. The browser tool does not send your curl request.