--- title: "application/x-www-form-urlencodedとは？application/jsonとの違いと使い分け" url: "https://www.issoh.co.jp/tech/details/4610/" published: 2024-12-23 updated: 2026-09-27 categories: ["API"] publisher: "株式会社一創" --- # application/x-www-form-urlencodedとは？application/jsonとの違いと使い分け application/x-www-form-urlencoded は、キーと値を `=` と `&` でつなぎ、空白を `+`、英数字と \*-.\_ 以外の文字を、既定では UTF-8 のバイト列として `%XX` に置き換えて送る Content-Type です。HTML フォームを JavaScript なしで送信したときの既定値でもあります。application/json は数値・真偽値・null・配列・オブジェクトの型を保ったまま送れる形式で、API 通信の標準になっています。この記事では、両者の書式を仕様に沿って説明したうえで、同じデータを両方の形式で送ったときに何が変わるかを Node.js・Express・Axios・PHP で実際に動かした結果で比べ、どちらを選ぶべきかの判断基準を示します。 ## まとめ：form-urlencodedとJSONの違いと選び方 form-urlencoded は文字列のキーと値の並びしか表せず、数値も真偽値も文字列で届きます。JSON は型とネストをそのまま運べます。 | 比較項目 | application/x-www-form-urlencoded | application/json | | ----------- | --------------------------------- | -------------------------- | | 本文の例 | `name=taro&age=20` | `{"name":"taro","age":20}` | | 値の型 | 文字列のみ | 文字列・数値・真偽値・null・配列・オブジェクト | | ネスト・配列 | 仕様なし（括弧記法は慣習） | 仕様で定義 | | HTMLフォームの既定 | 既定値 | 送れない（JavaScriptが必要） | | CORSのプリフライト | 条件を満たせば不要 | 別オリジンでは原則必要 | | 主な用途 | HTMLフォーム・OAuth 2.0のトークン取得 | REST API・SPAからの通信 | 選び方は3行で済みます。自分で設計する API は JSON にする。HTML フォームの素の送信と OAuth 2.0 のトークンエンドポイントのように仕様が form-urlencoded を指定している相手には form-urlencoded で送る。ファイルを含むなら multipart/form-data を使う。 ## application/x-www-form-urlencodedの書式とエンコード規則 ### キーと値を=と&でつなぐ本文の形 form-urlencoded の本文は、URL のクエリ文字列と同じ見た目をしています。違いは置き場所で、GET ではこの文字列が URL の `?` 以降に付き、POST ではリクエスト本文に入ります。 ``` POST /login HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded Content-Length: 50 user=taro&q=a+b%26c&jp=%E3%83%86%E3%82%B9%E3%83%88 ``` 書式を定めているのは WHATWG の [URL Standard](https://url.spec.whatwg.org/#application/x-www-form-urlencoded) です。キーと値を `=` で結び、組同士を `&` で区切ります。同じキーを複数回書くことは許されていて、受信側がそれを配列として扱うかどうかは実装が決めます。 ### 空白は+、記号と日本語はUTF-8の%XX エンコード規則は URL Standard の application/x-www-form-urlencoded シリアライザで決まっています。既定では文字列をまず UTF-8 のバイト列にし、英数字と `*-._` 以外のバイトを `%XX` にし、空白（0x20）だけは `+` にします。Node.js 26.5.0 の `URLSearchParams` で確かめると次のようになりました。 ``` new URLSearchParams({ q: 'a b&c=d', jp: 'テスト', sym: "*-._~!'()" }).toString() // q=a+b%26c%3Dd&jp=%E3%83%86%E3%82%B9%E3%83%88&sym=*-._%7E%21%27%28%29 encodeURIComponent('a b&c=d') // a%20b%26c%3Dd encodeURIComponent("*-._~!'()") // *-._~!'() ``` ここに落とし穴が2つあります。1つ目は、`encodeURIComponent` が form-urlencoded のエンコーダではないことです。空白を `%20` にし、`~!'()` をそのまま残します。受信側の多くはどちらも同じ値に戻せますが、本文の文字列そのものを比較するテストや、受信した生の本文でハッシュを計算する処理では別物として扱われます。form-urlencoded の本文は `URLSearchParams` で組み立てるのが確実です。 2つ目はデコード側です。`new URLSearchParams('q=a+b%2Bc').get('q')` は `a b+c` を返し、`+` を空白に戻します。一方 `decodeURIComponent('a+b')` は `a+b` のままです。form-urlencoded の本文を `decodeURIComponent` で自前分解すると、空白が `+` のまま残ります。値に `+` そのもの（電話番号の国番号など）を入れたいときは、送信側で `%2B` にする必要があります。 ### HTMLフォームの既定値とmultipart/form-data・text/plain [HTML Standard](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fs-enctype) では、`
` の `enctype` 属性が取れる値は application/x-www-form-urlencoded・multipart/form-data・text/plain の3つで、省略時と不正な値のときの既定は application/x-www-form-urlencoded です。application/json は含まれていないため、フォームから JSON を送るには JavaScript で `fetch` を書く必要があります。 form-urlencoded はファイルの中身を送れません。`` を含むフォームは `enctype="multipart/form-data"` を指定します。multipart は項目ごとに境界文字列（boundary）で区切り、バイナリをそのまま載せます。Node.js の `fetch` に `FormData` を渡すと、Content-Type は `multipart/form-data; boundary=----formdata-undici-…` になりました。text/plain は仕様上エンコードが曖昧で、機械で読み戻す用途には使いません。 ## application/jsonの書式とデータ型 ### JSONが持つ6つの型とネスト application/json は [RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.html) が定めるテキスト形式で、値は文字列・数値・真偽値（true／false）・null・配列・オブジェクトのいずれかです。配列とオブジェクトは入れ子にできるので、注文と明細、ユーザーと住所のような階層をそのまま表せます。 ``` { "name": "taro", "age": 20, "active": true, "tags": ["a", "b"], "addr": { "city": "Tokyo" }, "note": null } ``` 数値の精度には注意が要ります。RFC 8259 は数値の範囲を実装に委ねており、JavaScript の `JSON.parse` は IEEE 754 の倍精度で読むため、絶対値が253−1を超える整数 ID は、値によって丸めが発生し、正確な保持を保証できません。Node.js 26.5.0 では `JSON.parse('9007199254740993')` が 9007199254740992 を返しました。大きな ID は文字列で送るのが安全です。型の詳細と TypeScript での扱いは[JSONの型定義とデータ型一覧](/tech/details/2682/)で解説しています。コメントを書けない点については[JSONのコメントアウトとJSONC・JSON5](/tech/details/17784/)を参照してください。 ### charsetパラメータとapplication/\*+json RFC 8259 は、閉じたエコシステムの外で交換する JSON に UTF-8 を要求しており、application/json の登録に charset パラメータは定義されていません。`application/json; charset=utf-8` と付けても準拠した受信側には効果がありません。付いていても害はないので、既存の API が付けていれば外す必要もありません。 `application/ld+json`（JSON-LD）や `application/problem+json`（RFC 9457 のエラー応答）のように、`+json` で終わる型は「中身は JSON で、その上に独自の意味づけがある」ことを示します。受信側のパーサーが `application/json` と完全一致でしか判定していないと、これらを読み飛ばします。Express の `express.json()` も既定の `type` は `application/json` なので、`+json` を受けるなら `type` オプションで追加します。 ## 同じデータを両形式で送った結果の比較 型とネストの違いは、同じオブジェクトを両形式で送ると一目で分かります。Axios 1.20.0 から Express 5.2.1 のサーバーへ、`{ name: 'taro', age: 20, flag: true, n: null, tags: ['a','b'], addr: { city: 'Tokyo' } }` を送った結果です。 | 値 | JSONで届いた値 | form-urlencodedの本文 | Express 5の既定で届いた値 | | ----------------- | ---------------- | --------------------------- | ----------------------- | | age: 20 | 20（数値） | `age=20` | “20”（文字列） | | flag: true | true（真偽値） | `flag=true` | “true”（文字列） | | n: null | null | 項目ごと消える | キー自体が無い | | tags: \[‘a’,’b’\] | \[“a”,”b”\] | `tags%5B%5D=a&tags%5B%5D=b` | “tags\[\]”: \[“a”,”b”\] | | addr.city | {“city”:”Tokyo”} | `addr%5Bcity%5D=Tokyo` | “addr\[city\]”: “Tokyo” | form-urlencoded 側で起きていることは3つです。数値と真偽値は文字列になり、受信側で `Number()` や `=== 'true'` の変換を書かない限り `"20" + 1` が `"201"` になります。null は Axios のシリアライザが項目ごと落とすため、「値を null で上書きする」更新 API を form-urlencoded で作ると、未送信と null の区別がつきません。配列とネストは `[]` を使った括弧記法になりますが、これは PHP や qs ライブラリ由来の慣習で、URL Standard には定義がありません。受信側が括弧記法を解釈しなければ、`"tags[]"` という名前のキーとして届きます。 この表の「Express 5の既定」の列がまさにその状態です。ネストを送る必要が出た時点で JSON に切り替えるのが、変換コードを両端に書き続けるより確実です。 ## 送信側の書き方：fetch・Axios・curl・Python ### fetchのbody型とContent-Typeの自動設定 ブラウザと Node.js の `fetch` は、`body` に渡した値の種類から、Content-Typeが未指定の場合にその値を自動設定します。Node.js 26.5.0 で実測した値は次のとおりです。 ``` // URLSearchParams → application/x-www-form-urlencoded;charset=UTF-8 await fetch(url, { method: 'POST', body: new URLSearchParams({ a: '1' }) }); // 文字列 → text/plain;charset=UTF-8（JSON文字列でも application/json にはならない） await fetch(url, { method: 'POST', body: JSON.stringify({ a: 1 }) }); // JSONとして送るならヘッダーを明示する await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ a: 1 }), }); ``` 2つ目のパターンはよくある不具合の原因です。ヘッダーを付け忘れると text/plain で届き、Express 5 の `express.json()` は処理を飛ばすため `req.body` は `undefined` になります。サーバーのコードを疑う前に、ブラウザの開発者ツールで実際の Content-Type を確かめてください。通信をそのまま再現する手順は[Chrome検証ツールのCopy as cURL](/tech/details/12635/)にまとめています。 ### Axiosの入力値・ヘッダーと送信形式の切り替え Axios 1.20.0 は、プレーンなオブジェクトを渡すと JSON に変換して `application/json` で送ります。`URLSearchParams` を渡すと `application/x-www-form-urlencoded;charset=utf-8` で送ります。 ``` import axios from 'axios'; // JSONで送る（既定） await axios.post('/api/users', { name: 'taro', age: 20 }); // form-urlencodedで送る（方法1：URLSearchParams） await axios.post('/login', new URLSearchParams({ user: 'taro', pass: 'secret' })); // form-urlencodedで送る（方法2：ヘッダー指定でオブジェクトを自動変換） await axios.post('/login', { user: 'taro', pass: 'secret' }, { headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, }); ``` 方法2は手軽ですが、前章の表のとおり配列は `tags[]=`、ネストは `addr[city]=` に変換され、null は消えます。送り先が括弧記法を読めるか分からないときは、方法1でフラットなキーだけを組み立てる方が結果を予測できます。 ### curlとPythonのrequestsでの指定 curl 8.7.1 の `-d` は Content-Type を application/x-www-form-urlencoded にしますが、値をエンコードしません。`-d 'q=a b'` は空白が生のまま `q=a b` として届きました。値に空白や `&` を含むなら `--data-urlencode` を使います。JSON は `--json`（curl 7.82.0 以降）で、Content-Type と Accept の両方が application/json になります。 ``` curl -d 'name=taro' https://example.com/login curl --data-urlencode 'q=a b&c' https://example.com/search # q=a+b%26c で届く curl --json '{"name":"taro"}' https://example.com/api/users ``` Python の requests 2.32.5 では、`data=` に辞書を渡すと form-urlencoded、`json=` に渡すと application/json になります。リストは `tags=a&tags=b` と同じキーの繰り返しで送られ、括弧は付きません。標準ライブラリの `urllib.parse.urlencode` でリストを送るときは `doseq=True` が必要で、付け忘れると `tags=%5B%27a%27%2C+%27b%27%5D`（Python のリスト表記の文字列）が1つの値として届きます。 ``` import requests requests.post(url, data={'q': 'a b', 'tags': ['a', 'b']}) # q=a+b&tags=a&tags=b requests.post(url, json={'q': 'a b', 'n': None}) # {"q": "a b", "n": null} ``` GUI で試すなら、Postman の Body タブで x-www-form-urlencoded と raw（JSON）を切り替えます（[Postmanとは？APIテスト自動化とNewmanでのCI組み込み](/tech/details/17392/)）。 ## 受信側の読み方：Express・PHP ### Express 5のexpress.urlencodedとextendedの既定値 Express では、形式ごとに別のミドルウェアが本文を読みます。`express.urlencoded()` が form-urlencoded、`express.json()` が JSON です。どちらも Content-Type が一致しないリクエストは素通りさせ、Express 5 ではその場合 `req.body` が `undefined` のままです。 ``` const express = require('express'); const app = express(); app.use(express.urlencoded()); // Express 5 の既定は extended: false app.use(express.json()); app.post('/echo', (req, res) => res.json(req.body)); app.listen(3000, '127.0.0.1'); ``` Express 4 から移行するときに影響するのが `extended` の既定値です。Express 5（body-parser 2 系）では false になり、Node.js の `querystring` 相当で解析します。`user[name]=taro&tags[]=a&tags[]=b` を送ると、既定では `{"user[name]":"taro","tags[]":["a","b"]}` と括弧がキー名に残りました。`extended: true` にすると qs ライブラリで解析され、`{"user":{"name":"taro"},"tags":["a","b"]}` とネストに戻ります。Express 5 への移行全体は[Express.jsとは？Express 5対応のバックエンド入門](/tech/details/3857/)で解説しています。 extended: true にはネストの深さの上限があり、body-parser 2.3.0 の既定は 32 段です。33 段のキーを送ると 400 エラー「The input exceeded the depth」で拒否されました。深い構造を form-urlencoded で受ける設計そのものに無理があるので、ネストを受ける API は JSON で受けてスキーマで検証する方が扱いやすくなります。 ### PHPの$\_POSTの対応形式とJSON本文の読み取り PHP の `$_POST` が埋まるのは、Content-Type が application/x-www-form-urlencoded か multipart/form-data のときだけです。PHP 8.5.8 の組み込みサーバーで確かめると、form-urlencoded の `b[]=x&b[]=y&c[d]=e` は `$_POST` で配列とネストに展開され、JSON を送ると `$_POST` は空配列でした。JSON は本文を直接読みます。 ``` )（株式会社一創）