A new pkg.go.dev API for Go

by Ethan Lee, Jonathan Amsterdam & Hana Kim, Go Team

Access to Go metadata has been an everpresent need for the Go community. Since its launch, pkg.go.dev has served as a central hub for Go package documentation and discovery. While we initially prioritized providing this comprehensive access via a web interface, the need for streamlined programmatic access has become increasingly clear.

Structured API access has been one of the most highly requested features for pkg.go.dev for a while now. Developers building tools, IDE integrations, automated workflows, and other systems have had to rely on inconsistent and fragile scraping methods. By providing a formal API, we can provide fast and efficient access to required data. This foundation also sets Go up for the future of AI-assisted coding. Large language models and agents can access the context necessary to reason about the Go ecosystem with greater precision and accuracy.

Empowering Tool Builders

Our goal with this API is to reduce the technical churn for builders and innovators. By offering structured JSON metadata, we address the following use cases:

• Search and Discovery: The API enables fast and efficient search across the entire Go module ecosystem.
• Driving AI Innovation: As AI-assisted coding evolves, LLMs and agents need precise context. This API provides the data required for agents and models to reason deterministically about Go packages.

The Service Interface

Built for stability and efficient caching, the API uses a stateless, GET-only architecture. Primary endpoints are currently hosted under the v1beta path. Following a period of feedback from the Go community and confirmed stability, we intend to transition toward a formal v1 release.

For a complete interactive reference of all endpoints, query parameters, and response shapes, see pkg.go.dev/api. The machine-readable API contract is also published directly at pkg.go.dev/v1beta/openapi.yaml.

Endpoint	Description
/v1beta/imported-by/{path}	Paths of packages importing the package at {path}.
/v1beta/module/{path}	Information about the module at {path}.
/v1beta/package/{path}	Information about the package at {path}.
/v1beta/packages/{path}	Information about packages of the module at {path}.
/v1beta/search/search?q={query}	Search results for a given query.
/v1beta/symbols/{path}	List of symbols declared by the package at {path}.
/v1beta/versions/{path}	Versions of the module at {path}.
/v1beta/vulns/{path}	Vulnerabilities of the module or package at {path}.

An example of retrieving package information is shown below:

curl https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp | jq
{
  "modulePath": "github.com/google/go-cmp",
  "version": "v0.7.0",
  "isLatest": true,
  "isStandardLibrary": false,
  "goos": "all",
  "goarch": "all",
  "path": "github.com/google/go-cmp/cmp",
  "name": "cmp",
  "synopsis": "Package cmp determines equality of values.",
  "isRedistributable": true
}

A Reference Implementation

To demonstrate how to interact with our API, we are providing a reference CLI implementation: pkgsite-cli. This implementation serves as a practical example for developers looking to build their own integrations, showing how to handle the data directly from the terminal. Note, as the API continues to evolve, the interface and behavior of this CLI may change.

You can use it to search for packages or inspect symbols without leaving your shell:

go install golang.org/x/pkgsite/cmd/internal/pkgsite-cli@latest

pkgsite-cli search "uuid"
github.com/google/uuid
  Module:   github.com/google/uuid@v1.6.0
  Synopsis: Package uuid generates and inspects UUIDs.
... more


pkgsite-cli package github.com/google/go-cmp/cmp
github.com/google/go-cmp/cmp
  Name:      cmp
  Module:    github.com/google/go-cmp
  Version:   v0.7.0 (latest)
  Synopsis:  Package cmp determines equality of values.

pkgsite-cli package --symbols github.com/google/go-cmp/cmp
github.com/google/go-cmp/cmp
  Name:     cmp
  Module:   github.com/google/go-cmp
  Version:  v0.7.0 (latest)
  Synopsis: Package cmp determines equality of values.

Symbols:
  type Indirect struct{}
  type MapIndex struct{}
  type Option interface{}
  ... more

Looking Ahead

While we prioritize stability for our new /v1beta endpoints, we are eager to hear how open source communities use these resources to solve real-world problems.

We look forward to your feedback via our issue tracker and to seeing the tools you’ll build next.