openalex

Documentation

Overview

Package openalex is the library behind the openalex command line: the HTTP client, request shaping, and the typed data models for openalex.

The Client here is the spine every command shares. It sets a real User-Agent, paces requests so a busy session stays polite, and retries the transient failures (429 and 5xx) that any public site throws under load.

Index

• Constants
• type Author
• type Client
  • func NewClient(cfg Config) *Client
  • func (c *Client) GetPage(ctx context.Context, p string) (*Page, error)
  • func (c *Client) GetWork(ctx context.Context, id string) (*Work, error)
  • func (c *Client) PageLinks(ctx context.Context, p string, limit int) ([]*Page, error)
  • func (c *Client) SearchAuthors(ctx context.Context, query string, limit int) ([]Author, error)
  • func (c *Client) SearchInstitutions(ctx context.Context, query string, limit int) ([]Institution, error)
  • func (c *Client) SearchJournals(ctx context.Context, query string, limit int) ([]Journal, error)
  • func (c *Client) SearchTopics(ctx context.Context, query string, limit int) ([]Topic, error)
  • func (c *Client) SearchWorks(ctx context.Context, query string, limit int, year int) ([]Work, error)
• type Config
  • func DefaultConfig() Config
• type Domain
  • func (Domain) Classify(input string) (uriType, id string, err error)
  • func (Domain) Info() kit.DomainInfo
  • func (Domain) Locate(uriType, id string) (string, error)
  • func (Domain) Register(app *kit.App)
• type Institution
• type Journal
• type Page
• type Topic
• type Work

Constants

const BaseURL = "https://" + Host

BaseURL is the root every request is built from.

const DefaultEmail = "tamnd87@gmail.com"

DefaultEmail is the polite-pool email sent as mailto= on every request.

const DefaultUserAgent = "openalex-cli/0.1 (tamnd87@gmail.com)"

DefaultUserAgent identifies the client to OpenAlex.

const Host = "api.openalex.org"

Host is the site this client talks to.

Types

type Author

type Author struct {
	Rank         int    `json:"rank"`
	ID           string `json:"id" kit:"id"` // OpenAlex ID e.g. A27320202
	Name         string `json:"name"`
	WorksCount   int    `json:"works_count"`
	CitedByCount int    `json:"cited_by_count"`
	HIndex       int    `json:"h_index"`     // from summary_stats.h_index
	Institution  string `json:"institution"` // last_known_institutions[0].display_name
	Concepts     string `json:"concepts"`    // comma-join first 3 x_concepts
}

Author is an individual researcher with career statistics.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client talks to OpenAlex over HTTP.

func NewClient

func NewClient(cfg Config) *Client

NewClient returns a Client with the given config.

func (*Client) GetPage

func (c *Client) GetPage(ctx context.Context, p string) (*Page, error)

GetPage fetches one page by its path.

func (*Client) GetWork

func (c *Client) GetWork(ctx context.Context, id string) (*Work, error)

GetWork fetches a single work by OpenAlex ID or DOI.

func (*Client) PageLinks

func (c *Client) PageLinks(ctx context.Context, p string, limit int) ([]*Page, error)

PageLinks is kept for the kit domain driver.

func (*Client) SearchAuthors

func (c *Client) SearchAuthors(ctx context.Context, query string, limit int) ([]Author, error)

SearchAuthors queries the OpenAlex /authors endpoint and returns up to limit results.

func (*Client) SearchInstitutions

func (c *Client) SearchInstitutions(ctx context.Context, query string, limit int) ([]Institution, error)

SearchInstitutions queries the OpenAlex /institutions endpoint.

func (*Client) SearchJournals

func (c *Client) SearchJournals(ctx context.Context, query string, limit int) ([]Journal, error)

SearchJournals queries the OpenAlex /sources endpoint and returns up to limit results.

func (*Client) SearchTopics

func (c *Client) SearchTopics(ctx context.Context, query string, limit int) ([]Topic, error)

SearchTopics queries the OpenAlex /topics endpoint.

func (*Client) SearchWorks

func (c *Client) SearchWorks(ctx context.Context, query string, limit int, year int) ([]Work, error)

SearchWorks queries the OpenAlex /works endpoint and returns up to limit results. If year > 0 it adds a publication_year filter.

type Config

type Config struct {
	BaseURL   string
	UserAgent string
	Email     string
	Rate      time.Duration
	Timeout   time.Duration
	Retries   int
}

Config holds all tunables for the client.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults for the OpenAlex API.

type Domain

type Domain struct{}

Domain is the openalex driver. It carries no state; the per-run client is built by the factory Register hands kit.

func (Domain) Classify

func (Domain) Classify(input string) (uriType, id string, err error)

Classify turns any accepted input into the canonical (type, id).

func (Domain) Info

func (Domain) Info() kit.DomainInfo

Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.

func (Domain) Locate

func (Domain) Locate(uriType, id string) (string, error)

Locate is the inverse: the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

type Institution

type Institution struct {
	Rank      int    `json:"rank"`
	ID        string `json:"id" kit:"id"` // OpenAlex ID e.g. I63966007
	Name      string `json:"name"`
	Country   string `json:"country"` // country_code
	Type      string `json:"type"`
	Works     int    `json:"works_count"`
	Citations int    `json:"cited_by_count"`
	URL       string `json:"url,omitempty"` // homepage_url
}

Institution is a research institution (university, lab, etc.).

type Journal

type Journal struct {
	Rank      int    `json:"rank"`
	ID        string `json:"id" kit:"id"` // OpenAlex ID e.g. S137773608
	Name      string `json:"name"`
	Publisher string `json:"publisher"` // host_organization_name
	Works     int    `json:"works_count"`
	Citations int    `json:"cited_by_count"`
	IsOA      bool   `json:"is_oa"`
}

Journal is a publication venue (journal, conference, repository, etc.).

type Page

type Page struct {
	ID    string `json:"id" kit:"id"`
	URL   string `json:"url"`
	Title string `json:"title,omitempty"`
	Body  string `json:"body,omitempty" kit:"body"`
}

Page is used by the kit domain driver as the URI-addressable resource.

type Topic

type Topic struct {
	Rank        int    `json:"rank"`
	ID          string `json:"id" kit:"id"` // OpenAlex ID e.g. T12345
	Name        string `json:"name"`
	WorksCount  int    `json:"works_count"`
	Description string `json:"description,omitempty"`
	Field       string `json:"field,omitempty"` // subfield display name
}

Topic is a research topic cluster.

type Work

type Work struct {
	Rank         int      `json:"rank"`
	ID           string   `json:"id" kit:"id"` // OpenAlex ID e.g. W2741809807
	DOI          string   `json:"doi"`
	Title        string   `json:"title"`
	Year         int      `json:"year"`
	Type         string   `json:"type"` // article, preprint, book, etc.
	OpenAccess   bool     `json:"open_access"`
	CitedByCount int      `json:"cited_by_count"`
	Authors      []string `json:"authors"`       // first 3 author display names
	PrimaryVenue string   `json:"primary_venue"` // journal or source name
	URL          string   `json:"url"`           // doi URL or landing page
}

Work is a single scholarly work (paper, preprint, book, dataset, etc.).