GoAlex

GoAlex is a Go client library for the OpenAlex API.

OpenAlex is a fully open catalog of the global research system, created by the nonprofit organization OurResearch. It's named after the ancient Library of Alexandria.

Features

• Provides Go structs for OpenAlex entities: works, authors, sources, institutions, concepts, and venues

• Lightweight and easy-to-use API client

• Supports:

  • Pagination (standard and cursor)
  • Filtering and full-text search
  • Sorting, field selection, and random sampling
  • Grouping and aggregation
  • Autocomplete

• Polite pool support for higher rate limits

• Authentication support for premium access

Roadmap

The project is in active development. The following features have been implemented:

• Core data structures
• Polite pool support
• Basic API client
• Authentication support
• Pagination support
• Filtering and searching
• Sorting, selecting, and sampling
• Random result retrieval
• Grouping support
• Cursor pagination
• Autocomplete support
• N-gram support (Not yet available in OpenAlex)

Community contributions are welcome!

Installation

go get -u github.com/Sunhill666/goalex

Usage

Client Initialization

Create a new client with:

client := goalex.NewClient()

You can customize the client with options:

client := goalex.NewClient(goalex.WithRetry(3, 2 * time.Second), goalex.WithTimeout(10 * time.Second))

To use a custom HTTP client, you can pass it as an option:

client := goalex.NewClient(goalex.WithHTTPClient(&http.Client{ Timeout: 10 * time.Second }))

To use the polite pool (recommended for higher rate limits), provide an email:

client := goalex.NewClient(goalex.PolitePool("[email protected]"))

To use authentication (for premium features):

client := goalex.NewClient(goalex.Auth("your_api_key"))

---

Fetch a Single Entity

Retrieve a work by ID:

work, err := client.Works().Get("W2741809807")

---

Fetch a Random Entity

Get a random work:

work, err := client.Works().GetRandom()

---

List Entities

Fetch a list of works:

works, err := client.Works().List()

With pagination:

works, err := client.Works().Page(1).PerPage(10).List()

With metadata:

resultWithMeta, err := client.Works().ListWithMeta()
results, meta := resultWithMeta.Results, resultWithMeta.Meta

---

Cursor Pagination

For large result sets:

works, nextCursor, err := client.Works().Filter("publication_year", 2020).PerPage(100).Cursor()

To get the next page:

nextWorks, _, err := client.Works().Filter("publication_year", 2020).PerPage(100).Cursor(nextCursor)

---

Filtering and Searching

Filtering

works, err := client.Works().FilterMap(map[string]any{
    "institutions.country_code": "fr+gb",
    "authors_count":             ">2",
}).List()

Searching

works, err := client.Works().Search("machine learning").List()

Combined Search + Filter

works, err := client.Works().SearchFilter(map[string]string{
    "display_name": "surgery",
    "title":        "surgery",
}, true).List()

---

Sorting, Selecting, and Sampling

Sorting

works, err := client.Works().SortMap(map[string]bool{
    "publication_year": true,
    "relevance_score":  true,
}).List()

Selecting Fields

works, err := client.Works().Select("id", "doi", "display_name").List()

Sampling

works, err := client.Works().Sample(2).Seed(42).List()

---

Grouping

grouped, err := client.Works().GroupBy("authorships.countries", true).ListGroupBy()

---

Autocomplete

Institutions

results, err := client.Institutions().AutoComplete("flori").List()

Works with filter and search

results, err := client.Works().
    Filter("publication_year", 2010).
    Search("frogs").
    AutoComplete("greenhouse").
    List()

---

License

Licensed under the MIT License.

Issues & Contributions

Found a bug or have a feature request? Feel free to open an issue or submit a PR on the GitHub repo.