Parse a URL

Parses a URL exactly as browsers and Cloudflare Workers do (WHATWG URL Standard) and returns every component: scheme, username, host in ASCII and Unicode forms, port and default port, origin, path segments decoded, query parameters as an ordered list (duplicates kept), and fragment. It classifies the host (domain, IPv4, IPv6, localhost, private or other special-purpose range) without resolving DNS. A password, if present, is never returned: hasPassword is true and href shows *** instead. With base, a relative reference is resolved first.

Browser version (runs locally): URL Parser.

Parameters

Also accepted on every endpoint: format (json | text). Parameters may come from the query string, a JSON object body, an urlencoded or multipart form, or (for input) a text/plain body.

Response 200 application/json

Text output (format=text, text/plain): The normalized href (password redacted).

Errors

Errors are JSON: {"error": "<message>", "code": "<code>", "param": "<name>"?}.

Behaviour

• Idempotent: the same arguments always return the same result.
• Requires a client ID and secret (authentication). Each call is recorded as one metadata row against your client ID; inputs and outputs are never stored or logged. Responses carry cache-control: no-store.
• CORS: any origin may call this endpoint from a browser, using your credentials.

Examples

Responses below were produced by running each request through this code at build time. Long strings are shortened.

curl 'https://util.caruana.me/api/url/parse?input=https%3A%2F%2Fuser%40Example.COM%3A443%2Fa%2520b%2Fc%3Ftag%3Dx%26tag%3Dy%26q%3Dcaf%25C3%25A9%2Bau%2Blait%23top'

{
  "href": "https://[email protected]/a%20b/c?tag=x&tag=y&q=caf%C3%A9+au+lait#top",
  "hrefRedacted": false,
  "resolvedAgainstBase": false,
  "protocol": "https:",
  "scheme": "https",
  "special": true,
  "username": {
    "raw": "user",
    "decoded": "user"
  },
  "hasPassword": false,
  "host": "example.com",
  "hostname": "example.com",
  "hostnameUnicode": "example.com",
  "hostType": "domain",
  "idn": false,
  "ip": null,
  "isLocalhost": false,
  "isPrivate": false,
  "isPublic": null,
  "port": null,
  "defaultPort": 443,
  "effectivePort": 443,
  "origin": "https://example.com",
  "pathname": "/a%20b/c",
  "opaquePath": false,
  "pathSegments": [
    {
      "raw": "a%20b",
      "decoded": "a b"
    },
    {
      "raw": "c",
      "decoded": "c"
    }
  ],
  "search": "?tag=x&tag=y&q=caf%C3%A9+au+lait",
  "query": [
    {
      "name": "tag",
      "value": "x",
      "rawName": "tag",
      "rawValue": "x"
    },
    {
      "name": "tag",
      "value": "y",
      "rawName": "tag",
      "rawValue": "y"
    },
    {
      "name": "q",
      "value": "café au lait",
      "rawName": "q",
      "rawValue": "caf%C3%A9+au+lait"
    }
  ],
  "hash": "#top",
  "fragment": {
    "raw": "top",
    "decoded": "top"
  },
  "warnings": [
    "The URL contains a username (userinfo).",
    "The explicit port 443 is the default for https: and was removed from the normalized URL."
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "url_parse",
    "arguments": {
      "input": "https://[email protected]:443/a%20b/c?tag=x&tag=y&q=caf%C3%A9+au+lait#top"
    }
  }
}

curl 'https://util.caruana.me/api/url/parse?input=..%2Fimg%2Flogo.png%3Fv%3D2&base=https%3A%2F%2Fexample.com%2Fdocs%2Fguide%2F'

{
  "href": "https://example.com/docs/img/logo.png?v=2",
  "hrefRedacted": false,
  "resolvedAgainstBase": true,
  "protocol": "https:",
  "scheme": "https",
  "special": true,
  "username": {
    "raw": "",
    "decoded": ""
  },
  "hasPassword": false,
  "host": "example.com",
  "hostname": "example.com",
  "hostnameUnicode": "example.com",
  "hostType": "domain",
  "idn": false,
  "ip": null,
  "isLocalhost": false,
  "isPrivate": false,
  "isPublic": null,
  "port": null,
  "defaultPort": 443,
  "effectivePort": 443,
  "origin": "https://example.com",
  "pathname": "/docs/img/logo.png",
  "opaquePath": false,
  "pathSegments": [
    {
      "raw": "docs",
      "decoded": "docs"
    },
    {
      "raw": "img",
      "decoded": "img"
    },
    {
      "raw": "logo.png",
      "decoded": "logo.png"
    }
  ],
  "search": "?v=2",
  "query": [
    {
      "name": "v",
      "value": "2",
      "rawName": "v",
      "rawValue": "2"
    }
  ],
  "hash": "",
  "fragment": null,
  "warnings": []
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "url_parse",
    "arguments": {
      "input": "../img/logo.png?v=2",
      "base": "https://example.com/docs/guide/"
    }
  }
}

curl 'https://util.caruana.me/api/url/parse?input=http%3A%2F%2F%5Bfd00%3A%3A1%5D%3A8080%2Fadmin'

{
  "href": "http://[fd00::1]:8080/admin",
  "hrefRedacted": false,
  "resolvedAgainstBase": false,
  "protocol": "http:",
  "scheme": "http",
  "special": true,
  "username": {
    "raw": "",
    "decoded": ""
  },
  "hasPassword": false,
  "host": "[fd00::1]:8080",
  "hostname": "[fd00::1]",
  "hostnameUnicode": "[fd00::1]",
  "hostType": "ipv6",
  "idn": false,
  "ip": {
    "version": 6,
    "address": "fd00::1",
    "expanded": "fd00:0000:0000:0000:0000:0000:0000:0001",
    "range": "unique-local",
    "mappedIpv4": null
  },
  "isLocalhost": false,
  "isPrivate": true,
  "isPublic": false,
  "port": 8080,
  "defaultPort": 80,
  "effectivePort": 8080,
  "origin": "http://[fd00::1]:8080",
  "pathname": "/admin",
  "opaquePath": false,
  "pathSegments": [
    {
      "raw": "admin",
      "decoded": "admin"
    }
  ],
  "search": "",
  "query": [],
  "hash": "",
  "fragment": null,
  "warnings": []
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "url_parse",
    "arguments": {
      "input": "http://[fd00::1]:8080/admin"
    }
  }
}