URL Decoder

What does the URL Decoder do?

The URL Decoder converts UTF-8 percent-encoded hex sequences (e.g. %20, %26, %3D, %2F, %3A, +) back into human-readable plain text web URLs and URI query parameters. It also deconstructs the decoded URL into structured components (protocol, hostname, port, pathname, search query, hash fragment, and key-value parameter pairs).

Core Concepts

Understanding URL percent-decoding mechanics:

• Hexadecimal Unescaping: Converts %XX hexadecimal sequences into corresponding UTF-8 characters (e.g. %2F becomes /, %3F becomes ?, and %26 becomes &).
• Form-Urlencoded Plus Decoding: Translates + characters in query strings into whitespace ( ) according to standard application/x-www-form-urlencoded conventions.
• Hierarchical URI Parsing: Deconstructs the decoded address into standard WHATWG URL components and parses search queries into key-value parameter objects.

How to use the tool?

1. Enter Encoded URL: Paste your percent-encoded URL or query parameter string into the input box or click Load Sample.
2. Execute Decode: Click Decode URL String to restore original UTF-8 characters and parse query parameters.
3. Inspect & Copy: Review the decoded plain-text URL and component breakdown, then click Copy or Download.

Related Developer Utilities

If you work with web URLs, query parameters, and entity decoders, explore these complementary tools:

• URL Encoder: Percent-encode URLs and URI query parameters.
• HTML Entity Decoder: Unescape HTML character entities into clean UTF-8 text.
• HTML Entity Encoder: Convert reserved characters into XML/HTML entities.
• Base64 Decoder: Decode standard and URL-safe Base64 strings.

REST API Integration

Blueutils provides a free REST API endpoint (POST https://blueutils.com/api/url/url-decoder) to programmatically decode percent-encoded URI strings and parse search query parameters.

API Request Parameters

API Request Payload Examples

cURL

curl -X POST https://blueutils.com/api/url/url-decoder \
  -H "Content-Type: application/json" \
  -d '{
    "rawText": "https%3A%2F%2Fblueutils.com%2Fsearch%3Fq%3Dhello%2520world",
    "options": { "decodePlusAsSpace": true }
  }'

Python

import requests

url = "https://blueutils.com/api/url/url-decoder"
payload = {
    "rawText": "https%3A%2F%2Fblueutils.com%2Fsearch%3Fq%3Dhello%2520world",
    "options": {"decodePlusAsSpace": True}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String jsonPayload = """
            {
                "rawText": "https%3A%2F%2Fblueutils.com%2Fsearch%3Fq%3Dhello%2520world",
                "options": { "decodePlusAsSpace": true }
            }
            """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://blueutils.com/api/url/url-decoder"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

API Response Parameters

API Response Payload Examples

Success Response (HTTP 200 OK)

{
  "isValid": true,
  "input": "https%3A%2F%2Fblueutils.com%2Fsearch%3Fq%3Dhello%2520world",
  "decodedText": "https://blueutils.com/search?q=hello world",
  "components": {
    "href": "https://blueutils.com/search?q=hello%20world",
    "protocol": "https:",
    "hostname": "blueutils.com",
    "port": "443",
    "pathname": "/search",
    "search": "?q=hello%20world",
    "queryParams": {
      "q": "hello world"
    },
    "queryParamCount": 1
  }
}

Validation Failure Response (HTTP 400 Bad Request)

{
  "isValid": false,
  "error": "Invalid input: Percent-encoded URL payload cannot be empty."
}

Rate Limit Exceeded Response (HTTP 429 Too Many Requests)

{
  "error": "API rate limit exceeded. Please wait or contact support@blueutils.com."
}

Why use an API to decode URLs?

Integrating the URL Decoder API into log monitoring agents, OAuth callback routers, or AI agent tool calling provides key benefits:

• Rapid Script Validation: Unescapes nested query strings and OAuth redirect URIs from HTTP server logs automatically.
• Optimized Token Efficiency for AI Agents: LLMs frequently misinterpret percent-escaped URLs and fail to parse nested query parameters. Invoking the API parses components deterministically without token hallucinations.
• Deterministic Accuracy Without Hallucinations: Ensures 100% strict UTF-8 decoding and safe malformed character handling.

Native Usage

How to percent-decode URLs locally in terminal environments or scripts:

Windows (CMD / PowerShell)

# Percent-decode URL string in PowerShell
[System.Uri]::UnescapeDataString('https%3A%2F%2Fblueutils.com%2Fsearch%3Fq%3Dhello%2520world')

Linux / Unix (Bash)

# Percent-decode URL string using jq in Linux
jq -rr --arg x "https%3A%2F%2Fblueutils.com%2Fsearch%3Fq%3Dhello%2520world" '$x | @uri'

Python

Using Python urllib.parse:

import urllib.parse

encoded_url = "https%3A%2F%2Fblueutils.com%2Fsearch%3Fq%3Dhello%2Bworld"
decoded = urllib.parse.unquote_plus(encoded_url)
print("Decoded:", decoded)

Java

Using Java URLDecoder:

import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;

public class UrlDecoderExample {
    public static void main(String[] args) throws Exception {
        String encoded = "https%3A%2F%2Fblueutils.com%2Fsearch%3Fq%3Dhello%2Bworld";
        String decoded = URLDecoder.decode(encoded, StandardCharsets.UTF_8.toString());
        System.out.println("Decoded: " + decoded);
    }
}