URLエンコードの使いどころ — APIデバッグ・日本語URLの文字化け解決

APIを呼び出したらクエリパラメータがうまく渡らない、日本語のURLをコピペしたら記号だらけの文字列に化けた——こうしたトラブルの正体はたいていURLエンコード（パーセントエンコーディング）です。仕組みを知らなくても困らない場面は多いですが、デバッグの現場では避けて通れません。

この記事ではURLエンコードが実際に必要になる場面を中心に、URLエンコード/デコードツールを使った確認方法とあわせて紹介します。

URLエンコードとは

URLエンコード（パーセントエンコーディング）は、URLの中で特別な意味を持つ文字や、ASCII範囲外の文字を ”%” に続く16進数2桁で表現する方式です。RFC 3986で定義されています。

たとえばスペースは “%20”、”&” は “%26” に変換されます。これは ”&” がURLのクエリパラメータの区切り文字として予約されているため、パラメータの値の中にそのまま ”&” を含めると区切り位置を誤認識されてしまうからです。エンコードすることで「これはただの文字データです」とURLに伝えられます。

シーン1: API呼び出しのクエリパラメータ

APIのクエリパラメータに検索キーワードやユーザー入力をそのまま渡すと、値に含まれる記号がURLの構文と衝突することがあります。

https://api.example.com/search?q=A&B

このURLは “q=A” と “B” という2つのパラメータに分割されてしまい、意図した「A&B」という検索語として渡りません。値の部分を事前にエンコードすれば正しく渡せます。

https://api.example.com/search?q=A%26B

JavaScriptで動的にURLを組み立てる場合は encodeURIComponent() を使うのが基本です。パス全体を組み立てる encodeURI() とは対象文字が異なるため、クエリパラメータの値単体をエンコードする場合は encodeURIComponent() を使います。手元で結果を素早く確認したいときは、URLエンコード/デコードツールに値を貼り付ければ変換後の文字列がすぐ得られます。

シーン2: 日本語URLの文字化け

日本語を含むURLをブラウザのアドレスバーからコピーすると、次のように記号だらけの文字列になることがあります。

https://ja.wikipedia.org/wiki/%E6%97%A5%E6%9C%AC

これは「日本」という文字列がUTF-8のバイト列に変換されたうえでパーセントエンコードされた結果です。ブラウザのアドレスバー表示では読みやすいように日本語のまま表示されますが、実際に送信されるURLはこのエンコード済みの形式です。

チャットやドキュメントにURLを貼るとき、コピー元によって日本語表示のURLとエンコード済みURLのどちらが渡されるかが変わります。文字化けして見えても実際のリンク先は変わらないケースが多いですが、手動でURLを組み立てたり編集したりする場合は、エンコード後の文字列を確認しておくとトラブルを避けられます。

シーン3: フォームデータの送信

HTMLのフォームを application/x-www-form-urlencoded 形式で送信する場合、入力値はURLエンコードされてリクエストボディに載ります。

name=%E5%B1%B1%E7%94%B0&age=20

この形式ではスペースが “%20” ではなく ”+” に変換される点が通常のURLエンコードと異なります。フォーム送信のデバッグでリクエストボディをそのまま見ると記号だらけで読みにくいため、デコードして元の値に戻すと確認しやすくなります。

よく化ける文字一覧

URLエンコードで頻繁に登場する主要記号は次のとおりです。

文字	エンコード結果	用途
スペース	%20（フォーム送信時は ”+“）	区切り
&	%26	クエリパラメータの区切り
#	%23	フラグメント識別子
=	%3D	キーと値の区切り
+	%2B	URLエンコードされたスペースと区別するため
?	%3F	クエリ文字列の開始
/	%2F	パスの区切り
:	%3A	プロトコルの区切り
@	%40	ユーザー情報の区切り
%	%25	パーセント自体