URL Encoding: O que é, Como Funciona e Quando Usar
Se você já viu %20 no lugar de um espaço em uma URL ou %C3%A1 no lugar de "á", você encontrou URL encoding em ação. Este guia explica tudo sobre percent-encoding e como trabalhar com URLs corretamente.
Índice
- O que é URL encoding?
- Por que é necessário?
- Como funciona
- Caracteres que precisam ser codificados
- encodeURI vs encodeURIComponent
- Exemplos práticos
- Erros comuns
- Perguntas Frequentes
- Ferramentas relacionadas
O que é URL encoding?
URL encoding (ou percent-encoding) é o mecanismo de substituir caracteres não seguros em uma URL por uma representação com % seguido de dois dígitos hexadecimais representando o byte UTF-8.
Espaço → %20
& → %26
á → %C3%A1
ç → %C3%A7
Está definido na RFC 3986 e é parte fundamental de como a web funciona.
Por que é necessário?
URLs têm uma estrutura definida com caracteres especiais que têm significados reservados:
?separa o path dos query parameters&separa parâmetros entre si=separa chave de valor#indica um fragmento (anchor)/separa segmentos do path
Se um valor de parâmetro contém um desses caracteres, ele precisa ser codificado para não quebrar a estrutura da URL.
Sem encoding:
https://site.com/busca?q=café & leite
O navegador interpretaria "café " como o valor de q e " leite" como lixo.
Com encoding:
https://site.com/busca?q=caf%C3%A9%20%26%20leite
Agora o valor completo "café & leite" é preservado.
Como funciona
O algoritmo é simples:
- Converta o caractere para bytes UTF-8
- Para cada byte, escreva
%seguido do valor hexadecimal
Exemplo com "ã":
- "ã" em UTF-8 = bytes
C3 A3 - Resultado:
%C3%A3
Exemplo com espaço:
- Espaço em ASCII = byte
20 - Resultado:
%20
Caracteres que precisam ser codificados
Caracteres seguros (NÃO precisam de encoding)
A-Z a-z 0-9 - _ . ~
Esses são chamados "unreserved characters" e podem aparecer em qualquer parte da URL sem codificação.
Caracteres reservados (dependem do contexto)
: / ? # [ ] @ ! $ & ' ( ) * + , ; =
Devem ser codificados quando usados como dados (ex: dentro de um valor de query parameter), mas não quando usados com seu significado estrutural.
Tudo mais → codificar
Acentos, espaços, caracteres especiais, emojis — tudo que não está nas duas listas acima precisa de encoding.
encodeURI vs encodeURIComponent
JavaScript oferece duas funções, e escolher a errada é um erro comum:
encodeURI
Codifica uma URL completa, preservando a estrutura:
encodeURI("https://site.com/path?q=olá mundo")
// "https://site.com/path?q=ol%C3%A1%20mundo"
// Note: : / ? não são codificados
Use quando: você tem uma URL completa e quer codificar apenas os caracteres inseguros dentro dela.
encodeURIComponent
Codifica TUDO exceto A-Z a-z 0-9 - _ . ~ ! ' ( ) *:
encodeURIComponent("olá mundo & foo=bar")
// "ol%C3%A1%20mundo%20%26%20foo%3Dbar"
// Note: & e = TAMBÉM são codificados
Use quando: você está codificando um VALOR que será inserido dentro de uma URL (query param, path segment).
Regra prática
// CORRETO: codificar cada valor separadamente
const url = `https://api.com/search?q=${encodeURIComponent(userInput)}&lang=pt`;
// ERRADO: codificar a URL inteira
const url = encodeURI(`https://api.com/search?q=${userInput}&lang=pt`);
// Se userInput contiver "&", a URL quebra!
Exemplos práticos
Links de compartilhamento
const title = "Meu artigo: como usar APIs";
const url = "https://meusite.com/artigo?id=123";
const shareUrl = `https://twitter.com/intent/tweet?text=${encodeURIComponent(title)}&url=${encodeURIComponent(url)}`;
Parâmetros de busca
const query = "preço > 100 & categoria = eletrônicos";
const apiUrl = `https://api.com/search?q=${encodeURIComponent(query)}`;
// https://api.com/search?q=pre%C3%A7o%20%3E%20100%20%26%20categoria%20%3D%20eletr%C3%B4nicos
Redirecionamentos
const returnUrl = "https://meusite.com/dashboard?tab=settings";
const loginUrl = `https://auth.com/login?redirect=${encodeURIComponent(returnUrl)}`;
Erros comuns
1. Double encoding
// ERRADO: codificar duas vezes
const encoded = encodeURIComponent(encodeURIComponent("olá"));
// "ol%25C3%25A1" — o % do primeiro encoding foi codificado novamente!
2. Não codificar valores de query
// ERRADO
const url = `https://api.com?q=${userInput}`;
// Se userInput = "a&b=c", a URL se torna https://api.com?q=a&b=c (quebrado!)
3. Codificar a URL inteira com encodeURIComponent
// ERRADO
encodeURIComponent("https://site.com/path?q=hello")
// "https%3A%2F%2Fsite.com%2Fpath%3Fq%3Dhello" — inutilizável como URL!
4. Usar + em vez de %20
O caractere + como espaço é uma convenção de formulários HTML (application/x-www-form-urlencoded), não do URL encoding padrão. %20 é a forma correta no path e em APIs modernas.
Perguntas Frequentes
%20 ou + para espaço?
%20 é o padrão RFC 3986. O + é uma convenção específica de application/x-www-form-urlencoded (formulários HTML). Para APIs e URLs em geral, use %20.
URL encoding é reversível?
Sim, é 100% reversível. Use decodeURIComponent() para reverter.
Emojis funcionam em URLs?
Sim, após encoding. O emoji 🎉 vira %F0%9F%8E%89 (4 bytes UTF-8). Navegadores modernos mostram o emoji na barra de endereço mas enviam a versão codificada ao servidor.
Ferramentas relacionadas
- URL Encoder/Decoder — Codifique e decodifique URLs online
- Base64 Encoder/Decoder — Codifique dados em Base64
- Gerador de Slug — Gere slugs amigáveis para URLs
- Removedor de Acentos — Normalize texto para URLs