encoding/url

This package works with whole web addresses. Parse splits a URL such as https://user@shop.example.co.uk:8443/path?page=2#top into a URL struct with the fields scheme, userinfo, host, port, path, raw_query and fragment, and String puts it back together. Around that come helpers to edit query parameters, resolve relative links with Join, and find the registrable domain of a host.

Use it whenever you have a full address. For the a=1&b=2 part on its own, such as a form body, use encoding/query; for percent-encoding a single string, encoding.URLEncode in encoding; to fetch the address, net/http.

Raw and decoded parts

The fields hold the text exactly as it appeared, percent escapes included, so String(Parse(x)) normally gives back x. Read the human form with DecodedPath, DecodedUserinfo or Query. When you set a field yourself, put encoded text in it: escape path segments with EncodePathSegment and build queries with SetQuery.

What trips people up

• Parse never fails. It does no validation: a port that is not a number becomes 0, and text without :// (including mailto:sara@example.com) has no scheme or host and lands whole in path. Check scheme and host yourself before trusting an address from a user.
• Nothing is lowercased. HTTPS://Shop.Example.COM keeps its case in scheme and host, and Domain returns Example.COM. Lowercase with str.Lower before you compare hosts or domains.
• Editing one parameter rewrites the whole query. RemoveParam, SetParam and KeepParams decode the query and encode it again: %20 becomes +, characters such as * get escaped, a bare flag becomes flag=, and repeated keys are grouped together. The meaning stays the same; the text may not.
• Join with only ?query or #fragment loses the file name of the base, unlike a browser. See the links guide.

Guide: strip tracking parameters

Links copied from email and social media carry utm_ and click id parameters that only serve analytics. Before you store or compare links, parse them, drop those parameters with RemoveParam, clear the fragment and print the result with String. The parameters that stay keep their order.

import encoding.url

func clean(raw: str): str:
    mut u := url.Parse(raw)
    names := url.ParamNames(u)
    each n in names:
        if n.starts_with("utm_") or n == "fbclid" or n == "gclid":
            _ := url.RemoveParam(u, n)
        end
    end
    u.fragment = ""
    ret url.String(u)
end

func main:
    println clean("https://shop.example/item/42?color=red&utm_source=news&utm_medium=email#reviews")
    println clean("https://blog.example/post?fbclid=IwAR0abc")
    println clean("https://example.com/search?q=salam%20lang&utm_campaign=fall&page=2&debug")
end

ParamNames returns a copy of the names, so removing parameters inside the loop is safe. The fields of URL are plain strings you can set directly, as u.fragment = "" does. The last line shows the rewrite described above: salam%20lang comes out as salam+lang and the bare debug as debug=. Both mean the same to a server, but if you use the cleaned link as a cache or database key, clean every link the same way so equal links give equal text.

Guide: resolve the links of a page

A crawler or a link checker finds relative links like ../api/json.html in a page and needs the full address. Join resolves a reference against the page's own URL the way a browser does: ./ and ../ move through the folders, a leading / starts at the site root, //host keeps the scheme, and a full URL replaces everything.

import encoding.url

func main:
    page := url.Parse("https://docs.example.com/guide/start/index.html?lang=en")
    hrefs := ["install.html", "./setup/linux.html", "../api/json.html", "/blog/", "https://other.example/x", "//cdn.example.com/app.js"]
    each h in hrefs:
        println h, "->", url.String(url.Join(page, h))
    end
end

A reference that is only a query (?lang=fa) or only a fragment (#top) does not keep the file name of the base yet, so resolve those yourself by setting raw_query or fragment on a copy of the base.

Guide: is it the same site?

To allow redirects only within your own site, or to group links by owner, compare the registrable domain instead of the host name. Domain is the part a person registers, such as example.co.uk; PublicSuffix is the part under which anyone can register; Subdomain is what is left on the left. An address made of an IP has no domain, so compare the host name there. Host names are not case sensitive but the package keeps their case, so the program lowercases both addresses before parsing them.

import encoding.url
import str

func same_site(a: str, b: str): bool:
    ua := url.Parse(str.Lower(a))
    ub := url.Parse(str.Lower(b))
    if url.IsIP(ua) or url.IsIP(ub):
        ret url.Hostname(ua) == url.Hostname(ub)
    end
    ret url.Domain(ua) == url.Domain(ub)
end

func main:
    u := url.Parse("https://api.eu.shop.example.co.uk:8443/v1/orders")
    println "host:", url.Hostname(u), "port:", u.port
    println "domain:", url.Domain(u), "suffix:", url.PublicSuffix(u), "sub:", url.Subdomain(u)

    println same_site("https://www.example.com/a", "https://login.example.com/b")
    println same_site("https://WWW.Example.com/", "https://example.com/cart")
    println same_site("https://example.com/", "https://example.org/")
    println same_site("http://10.0.0.5:8080/", "http://10.0.0.5/")
end

The package knows the common public suffixes such as com, co.uk and com.au, not the complete Public Suffix List, so hosting platforms that give every customer a subdomain may count as one site. Check those hosts by name when it matters.

Guide: build a URL from user input

When parts of the address come from users, escape each path segment with EncodePathSegment, which also escapes / so a file name cannot add folders. Put the parameters in a QueryMap and attach it with SetQuery; Add allows the same key more than once.

import encoding.url
import encoding.query

func main:
    folder := "My Files"
    name := "report 2026/Q3.pdf"
    mut u := url.Parse("https://files.example.com")
    u.path = "/users/sara/" + url.EncodePathSegment(folder) + "/" + url.EncodePathSegment(name)

    mut q := query.NewQueryMap()
    query.Set(q, "download", "1")
    query.Add(q, "tag", "finance")
    query.Add(q, "tag", "سه‌ماهه")
    url.SetQuery(u, q)

    full := url.String(u)
    println full

    back := url.Parse(full)
    println "path:", url.DecodedPath(back)
    println "tags:", query.GetAll(back.raw_query, "tag")
end

DecodedPath gives the readable path but turns %2F back into /, so it cannot tell a slash inside a name from a folder boundary. Split u.path at / first and decode each segment when you need the names exactly.

Types

struct URL

import encoding.url
import encoding.query

func main:
    mut u := url.Parse("https://user%20a:pw@shop.example.co.uk:8443/books/%D8%B3%D9%84%D8%A7%D9%85?page=2&sort=new#top")
    println u.scheme, u.host, u.port, u.path, u.raw_query, u.fragment
    println url.Hostname(u), url.HostPort(u), url.IsIP(u)
    println url.Labels(u), url.PublicSuffix(u), url.Domain(u), url.Subdomain(u)
    println url.DecodedPath(u), url.DecodedUserinfo(u)
    println url.ParamNames(u), query.Size(url.Query(u))
    url.SetParam(u, "page", "3")
    println url.RemoveParam(u, "sort"), url.String(u)
    mut keep := Vector {} as Vector<str>
    keep.push("page")
    url.KeepParams(u, keep)
    mut q := query.NewQueryMap()
    query.Add(q, "q", "hello world")
    url.SetQuery(u, q)
    println url.String(u)
    url.ClearQuery(u)
    println url.String(u)
    println url.String(url.Join(u, "../img/a.png")), url.EncodePathSegment("a b/c")
    println url.IsIP(url.Parse("http://127.0.0.1/"))
end

Functions

func Hostname(u: URL): str

func IsIP(u: URL): bool

func Labels(u: URL): Vector<str>

func PublicSuffix(u: URL): str

func Domain(u: URL): str

func Subdomain(u: URL): str

func RemoveParam(u &: URL, key: str): bool

func SetParam(u &: URL, key: str, val: str)

func KeepParams(u &: URL, keep: Vector<str>)

func ClearQuery(u &: URL)

func ParamNames(u: URL): Vector<str>

func Parse(raw: str): URL

func HostPort(u: URL): str

func String(u: URL): str

func DecodedPath(u: URL): str

func DecodedUserinfo(u: URL): str

func EncodePathSegment(s: str): str

func Query(u: URL): query.QueryMap

func SetQuery(u &: URL, q: query.QueryMap)

func Join(base: URL, ref: str): URL