URL Encoding: Por Que %20 Aparece nas Suas URLs

URL Encoding: Tornando URLs Seguras para a Web

Você já copiou uma URL e viu %20 onde deveria ter um espaço, ou %C3%A9 onde tinha um caractere acentuado. Isso é URL encoding (também chamado percent-encoding), e existe porque URLs só podem conter um conjunto específico de caracteres ASCII.

Por Que URLs Precisam de Encoding

URLs têm caracteres reservados com significados especiais:

Se seus dados contêm esses caracteres, você deve codificá-los para evitar ambiguidade. Caso contrário o navegador não consegue saber se & é parte dos seus dados ou um separador de query.

Como o Encoding Funciona

Cada caractere inseguro é substituído por % seguido do seu valor hex de dois dígitos:

Caracteres não-ASCII (acentos, CJK, emoji) são primeiro convertidos para bytes UTF-8, depois cada byte é percent-encoded.

JavaScript: encodeURI vs encodeURIComponent

Essa é a API mais confusa do JavaScript:

// encodeURI — codifica uma URL COMPLETA
// NÃO codifica: : / ? # [ ] @ ! $ & ' ( ) * + , ; =
encodeURI('https://example.com/path with spaces?q=hello world')
// "https://example.com/path%20with%20spaces?q=hello%20world"

// encodeURIComponent — codifica um COMPONENTE (valor)
// CODIFICA: : / ? # @ ! $ & ' ( ) * + , ; =
encodeURIComponent('price=10¤cy=USD')
// "price%3D10%26currency%3DUSD"

Regra de ouro:

• Use encodeURIComponent() para valores de parâmetros query
• Use encodeURI() apenas para codificar uma URL completa que já tem a estrutura correta
• Melhor ainda: use as APIs URL e URLSearchParams — elas fazem o encoding automaticamente

O Jeito Moderno: URL e URLSearchParams

// Construa URLs de forma segura — sem encoding manual
const url = new URL('https://api.example.com/search');
url.searchParams.set('q', 'café & croissant');
url.searchParams.set('page', '1');
console.log(url.toString());
// "https://api.example.com/search?q=caf%C3%A9+%26+croissant&page=1"

// Parse URLs existentes
const parsed = new URL('https://example.com/path?name=Jo%C3%A3o');
console.log(parsed.searchParams.get('name'));
// "João" — decodificado automaticamente

Erros Comuns de Encoding

Double encoding: Codificar uma string já codificada. %20 vira %2520. Acontece quando você chama encodeURIComponent em um valor que já foi codificado.

Não codificar: Passar input cru do usuário em URLs. Se o nome de alguém é "O'Brien & Sons", sua URL quebra.

Usar + para espaços: Em query strings, + significa espaço (do encoding de formulários HTML). Mas em segmentos de caminho, + é um sinal de mais literal. %20 sempre significa espaço em todo lugar.

# Python
from urllib.parse import quote, unquote, urlencode

quote('café & croissant')         # 'caf%C3%A9%20%26%20croissant'
unquote('caf%C3%A9')              # 'café'

# Construir query strings
urlencode({'q': 'hello world', 'lang': 'pt'})
# 'q=hello+world&lang=pt'

// Go
import "net/url"

encoded := url.QueryEscape("café & croissant")
// "caf%C3%A9+%26+croissant"

decoded, _ := url.QueryUnescape(encoded)
// "café & croissant"

Quando Codificar o Quê

Codifique/decodifique agora: Codificador/Decodificador URL — cole qualquer texto ou URL, codifique ou decodifique instantaneamente.