Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Networking and the Web

Go net/url package

Reference for Go net/url: Parse, URL fields, Values for query strings, QueryEscape, PathEscape, JoinPath and ResolveReference, with edge cases and examples.

The package net/url parses URLs into their parts, builds them back into strings, and handles the percent-encoding that URLs require. The central type is url.URL, a struct with fields such as Scheme, Host, Path and RawQuery. The second important type is url.Values, a map from query keys to lists of values.

Building a URL by gluing strings together is a common source of bugs (unescaped &, spaces, non-ASCII text). Use url.Values.Encode for queries and url.JoinPath for paths so escaping happens in one place.

Go
u, err := url.Parse("https://example.com:8443/docs/a%20b?q=go&page=2#top")
fmt.Println(u.Host, u.Path, u.Query().Get("q"))

Try it

Go Parsing and inspecting a URL

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Building queries and joining paths

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
func Parse(rawURL string) (*URL, error)
func ParseRequestURI(rawURL string) (*URL, error)
func ParseQuery(query string) (Values, error)
func QueryEscape(s string) string
func QueryUnescape(s string) (string, error)
func PathEscape(s string) string
func PathUnescape(s string) (string, error)
func JoinPath(base string, elem ...string) (string, error)
func User(username string) *Userinfo
func UserPassword(username, password string) *Userinfo

func (u *URL) Query() Values
func (u *URL) String() string
func (u *URL) Hostname() string
func (u *URL) Port() string
func (u *URL) IsAbs() bool
func (u *URL) ResolveReference(ref *URL) *URL
func (u *URL) JoinPath(elem ...string) *URL
func (u *URL) EscapedPath() string
func (u *URL) RequestURI() string
func (u *URL) Redacted() string

func (v Values) Get(key string) string
func (v Values) Set(key, value string)
func (v Values) Add(key, value string)
func (v Values) Del(key string)
func (v Values) Has(key string) bool
func (v Values) Encode() string
Name Description
rawURL The text to parse. It may be absolute (https://...), a path, or a reference like ../x.
elem Path elements to append; they are joined with / and cleaned (.. and . resolved).
Values map[string][]string. Get returns the first value or "", Add appends, Set replaces.

Returns: Parse returns a *URL or a *url.Error that wraps the cause. Query() ignores malformed pairs silently; use ParseQuery if you need the error.

Usage notes

  • Parse accepts relative references. example.com/path has no scheme, so it is parsed entirely as Path. For absolute-URL validation check u.Scheme != "" && u.Host != "", or use IsAbs.
  • ParseRequestURI is stricter: it expects an absolute URI or an absolute path, as in an HTTP request line, and does not accept fragments.
  • Path is decoded, RawPath is the original when the encoding is not the default. Use EscapedPath() for the right form to send.
  • Query escaping vs path escaping. QueryEscape turns a space into +; PathEscape turns it into %20 and also escapes /. Use the one that matches the position.
  • Encode sorts by key, so output is deterministic, but the order of values for one key stays as added.
  • Port-only hosts. Parse("localhost:8080/x") fails with first path segment in URL cannot contain colon, because localhost looks like a scheme. Write http://localhost:8080/x.
  • Copy before mutating. URL holds pointers (User); copy the struct (u2 := *u) before you change a shared URL.
  • Secrets. Redacted() replaces the password with xxxxx so URLs can go into logs.