URL Encode Parameters for Automated API Testing in GitHub Actions
Properly URL-encode query parameters, API keys, and search strings in GitHub Actions curl commands and API test workflows. Avoid 400 Bad Request errors from unencoded special characters.
The Problem
Your GitHub Actions workflow calls an API with dynamic parameters — search queries, filter values, or date ranges. Special characters like spaces, ampersands, and plus signs break the URL, causing 400 Bad Request errors that only surface in CI.
Why This Matters
URL encoding bugs are notoriously inconsistent — they work in browsers (which auto-encode) but fail in curl (which doesn't). CI environments make this worse because parameter values come from environment variables with unpredictable characters. Proper encoding is required for any API that accepts user-generated content, search terms, or structured data in query strings.
Step-by-Step Instructions
Test your URL parameters in the encoder below
Paste your query string value (e.g., a search term with spaces or special characters) into the URL encoder. Use the encoded output to construct your test API calls.
Use <code>curl --data-urlencode</code> for automatic encoding
curl --data-urlencode 'q=hello world' https://api.example.com/search automatically encodes the value. For GET requests, use -G --data-urlencode to append encoded parameters to the URL.
Encode in shell with Python one-liner
For complex cases: ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$VALUE'))"). This handles all RFC 3986 reserved characters and works on all GitHub-hosted runners.
Validate encoded URLs in API contract tests
Add an assertion step that decodes the URL and verifies the round-trip: encode → request → parse response → assert expected data. This catches encoding mismatches between your client and the API server.
Try It Now — URL Encoder
Open full page →All processing happens in your browser — no data is sent to any server.
Before & After Example
- name: Search API
run: |
QUERY="hello world & more"
# ❌ WRONG: spaces and & break the URL
curl "https://api.example.com/search?q=$QUERY&limit=10"
# Sends: /search?q=hello world & more&limit=10
# Result: 400 Bad Request or wrong results
- name: Search API with proper URL encoding
run: |
QUERY="hello world & more"
LIMIT=10
# Method 1: curl --data-urlencode (simplest)
curl -G "https://api.example.com/search" \
--data-urlencode "q=$QUERY" \
--data-urlencode "limit=$LIMIT" \
-H "Authorization: Bearer ${{ secrets.API_TOKEN }}"
# Method 2: Python encoding for complex cases
ENCODED_QUERY=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$QUERY', safe=''))")
echo "Encoded query: $ENCODED_QUERY"
curl "https://api.example.com/search?q=$ENCODED_QUERY&limit=$LIMIT" \
-H "Authorization: Bearer ${{ secrets.API_TOKEN }}"
# Method 3: node.js
ENCODED=$(node -e "console.log(encodeURIComponent('$QUERY'))")
curl "https://api.example.com/search?q=$ENCODED&limit=$LIMIT"
Frequently Asked Questions
What's the difference between <code>encodeURI</code> and <code>encodeURIComponent</code>?
encodeURI encodes a full URL (preserving ://, /, ?, &). encodeURIComponent encodes a single parameter value (also encodes /, ?, &). Always use encodeURIComponent for query parameter values.
Why does <code>+</code> in a URL sometimes mean a space?
In the application/x-www-form-urlencoded format, + represents a space. In standard URL percent-encoding (RFC 3986), a space is %20. APIs can interpret them differently. Use %20 (urllib.parse.quote with safe='') to be safe.
How do I URL-encode an entire JSON body for a GET request?
For GET requests with JSON params, base64-encode the JSON and pass it as a single parameter: curl -G --data-urlencode "data=$(echo '{"key":"val"}' | base64)" URL. Or switch to a POST request with -H 'Content-Type: application/json'.
Related Workflows
Want the full URL Encoder experience?
Open the standalone tool for more space, keyboard shortcuts, and additional features.
Open URL Encoder →