URL.toJSON() — Methode · JavaScript-Referenz

Signatur

URL.prototype.toJSON()

Beschreibung

Die Methode toJSON() eines URL-Objekts liefert die komplette URL als String. Das Ergebnis ist exakt dasselbe wie bei url.href oder url.toString(), also die normalisierte, prozentkodierte Form der URL.

Ihr eigentlicher Zweck: JSON.stringify() ruft automatisch toJSON() auf, wenn ein Objekt diese Methode besitzt. Dadurch landen URL-Instanzen in JSON als einfache Strings statt als leeres Objekt {}. Das ist praktisch, wenn Konfigurationsobjekte, API-Payloads oder Log-Einträge URL-Objekte enthalten.

Selbst ruft man toJSON() selten direkt auf – für die String-Darstellung ist href lesbarer. Wichtig: Beim Einlesen mit JSON.parse() entsteht wieder nur ein String. Ein URL-Objekt musst du selbst neu erzeugen, z. B. mit einer Reviver-Funktion.

Beispiele

Direkter Aufruf im Vergleich zu href

const url = new URL('https://example.com/suche?q=kaffee bohnen#treffer');

console.log(url.toJSON());
console.log(url.toJSON() === url.href);
console.log(url.toJSON() === url.toString());

https://example.com/suche?q=kaffee%20bohnen#treffer true true

URL-Objekte in einem API-Payload serialisieren

const payload = {
  name: 'Webhook Bestellung',
  endpoint: new URL('/hooks/order', 'https://api.example.com'),
  aktiv: true
};

// JSON.stringify ruft automatisch endpoint.toJSON() auf
console.log(JSON.stringify(payload));

{"name":"Webhook Bestellung","endpoint":"https://api.example.com/hooks/order","aktiv":true}

Rückweg: URL-Objekte mit einem Reviver wiederherstellen

const json = '{"homepage":"https://example.com/","api":"https://api.example.com/v2"}';

const config = JSON.parse(json, (key, value) =>
  typeof value === 'string' && /^https?:\/\//.test(value) ? new URL(value) : value
);

console.log(config.api instanceof URL);
console.log(config.api.pathname);

true /v2

Array von URLs speichern (z. B. im localStorage)

const verlauf = [
  new URL('https://example.com/artikel/1'),
  new URL('https://example.com/artikel/2?ref=news')
];

const gespeichert = JSON.stringify(verlauf);
console.log(gespeichert);

const geladen = JSON.parse(gespeichert).map((s) => new URL(s));
console.log(geladen[1].searchParams.get('ref'));

["https://example.com/artikel/1","https://example.com/artikel/2?ref=news"] news

// Wichtig · Fallstricke

Keine Umkehrung: JSON.parse() gibt nur einen String zurück, kein URL-Objekt. Erzeuge es selbst mit new URL() oder einer Reviver-Funktion.
Normalisierung: Die Ausgabe ist die normalisierte Form. Leerzeichen werden z. B. zu %20, der Hostname wird kleingeschrieben und ein fehlender Pfad wird zu /. Der String kann deshalb von der ursprünglichen Eingabe abweichen.
Sensible Daten: Zugangsdaten (username/password) und Token in Query-Parametern stehen mit im Ergebnis. Entferne sie vor dem Loggen oder Übertragen.
Kein Einfluss auf andere Objekte: URLSearchParams hat kein toJSON() und wird von JSON.stringify() zu {}. Nutze dort toString() oder Object.fromEntries().
Kompatibilität: Wird von allen modernen Browsern und Node.js unterstützt, nicht aber vom Internet Explorer.

Siehe auch

URL.href URL.toString() URL JSON.stringify() JSON.parse() URLSearchParams PerformanceTiming.toJSON()