GoLang bindings for Tranco List

This is a GoLang bindings for Tranco List. It can be used as a cli tool or a GoLang module.

Docker Usage

docker pull ghcr.io/wangyihang/tranco-go-package:main

echo google.com | docker run -i -v $HOME/.tranco:/root/.tranco ghcr.io/wangyihang/tranco-go-package:main

Download the list for a certain date (e.g. 2024-10-01).

docker run -v .:/root/.tranco/ \
    ghcr.io/wangyihang/tranco-go-package:main \
    --date 2024-10-01

$ ls 2024-10-01_sld_full_XJNYN.csv
2024-10-01_sld_full_XJNYN.csv

$ wc -l 2024-10-01_sld_full_XJNYN.csv
 4452127 2024-10-01_sld_full_XJNYN.csv

$ head 2024-10-01_sld_full_XJNYN.csv
1,google.com
2,amazonaws.com
3,microsoft.com
4,facebook.com
5,akamai.net
6,apple.com
7,root-servers.net
8,a-msedge.net
9,youtube.com
10,azure.com

Cli Installation

go install github.com/WangYihang/tranco-go-package/cmd/tranco@latest

Cli Usage

Usage:
  tranco [OPTIONS]

Application Options:
  -i, --input-filepath=     input filepath (default: -)
  -d, --date=               date of the list (default: 2022-01-01)
      --include-subdomains  use the full (subdomain-inclusive) list instead of
                            second-level-domains only
  -v, --version             display version
  -c, --cache-folder=       cache folder (default: .tranco)

Help Options:
  -h, --help                Show this help message

By default, tranco queries the second-level-domain list (smaller, faster). Pass --include-subdomains to query the full subdomain-inclusive list instead.

$ cat input.txt                                                    
google.com
baidu.com
tsinghua.edu.cn
pku.edu.cn

$ cat input.txt | tranco -d 2023-10-10
{"domain":"google.com","rank":1,"date":"2023-10-10"}
{"domain":"baidu.com","rank":138,"date":"2023-10-10"}
{"domain":"tsinghua.edu.cn","rank":5302,"date":"2023-10-10"}
{"domain":"pku.edu.cn","rank":4338,"date":"2023-10-10"}

A domain that isn't found in the list doesn't stop the batch - it's reported with an error field instead of rank, and the remaining domains still get processed:

$ echo "not-a-real-domain-example.invalid" | tranco -d 2023-10-10
{"date":"2023-10-10","domain":"not-a-real-domain-example.invalid","error":"domain not found in tranco list: not-a-real-domain-example.invalid"}

Server Installation

go install github.com/WangYihang/tranco-go-package/cmd/tranco-server@latest

Module Installation

go get github.com/WangYihang/tranco-go-package

Module Usage

package main

import (
	"fmt"
	tranco "github.com/WangYihang/tranco-go-package"
)

func main() {
	list, err := tranco.NewTrancoList("2019-04-30", false, "1000", ".tranco")
	if err != nil {
		panic(err)
	}
	rank, err := list.Rank("google.com")
	if err != nil {
		panic(err)
	}
	fmt.Println(rank)
}

Acknowledgement

Special thanks to the authors of the Tranco List and the tranco-python-package for their work, which inspired the creation of this GoLang project.