Como codificar e decodificar URLs

Se você já viu %20 em uma URL onde deveria haver um espaço, ou %C3%A9 onde um caractere acentuado deveria estar, você encontrou a codificação de URL. É uma parte fundamental de como a web funciona, e entendê-la ajuda a depurar links quebrados, problemas de API e envios de formulário.

O que a codificação de URL faz

URLs só podem conter um conjunto limitado de caracteres com segurança: letras (A-Z, a-z), dígitos (0-9) e alguns caracteres especiais (-, _, ., ~). Todo o resto — espaços, caracteres acentuados, emojis e símbolos como &, =, #, ? — deve ser convertido para um formato seguro.

A codificação de URL (também chamada de percent-encoding) substitui caracteres inseguros por um % seguido de seus valores hexadecimais. Exemplos: espaço vira %20, & vira %26, = vira %3D, # vira %23, ? vira %3F, / vira %2F, @ vira %40.

Quando você precisa de codificação de URL

• Parâmetros de consulta com caracteres especiais — uma busca como preço > 100 & categoria = sapatos precisa de codificação para funcionar em uma URL
• Caracteres não-ingleses em URLs — nomes, cidades ou conteúdo em outros idiomas devem ser codificados
• Requisições de API — ao construir chamadas de API manualmente, valores de parâmetros frequentemente precisam de codificação
• Depuração — quando uma URL não está funcionando, decodificá-la revela quais são os valores reais

Como codificar e decodificar

1. Escolha codificar ou decodificar — selecione a direção. Escolha encodeURIComponent para parâmetros de consulta ou encodeURI para URLs completas. 2. Cole sua entrada — insira o texto ou URL. O resultado é atualizado instantaneamente. 3. Copie a saída — use o resultado no seu código, requisição de API ou navegador.

Dicas

• Codifique valores, não URLs inteiras — se você codifica uma URL inteira, as barras e dois-pontos que estruturam a URL também serão codificados, quebrando-a. Codifique apenas os valores dentro dos parâmetros de consulta.
• Codificação dupla — codificar uma string já codificada produz coisas como %2520 (o % é codificado como %25). Se sua URL parece errada, verifique se algo está sendo codificado duas vezes.
• Decodifique para depurar — quando uma requisição de API falha ou uma URL parece confusa, decodifique-a para ver os valores reais dos parâmetros. Isso frequentemente revela o problema imediatamente.
• Use funções integradas da sua linguagem — em código de produção, sempre use encodeURIComponent() (JavaScript), urllib.parse.quote() (Python) ou URLEncoder.encode() (Java) em vez de codificar manualmente.