wikidataclient

README

go-wikidata-client

A small Go client for the Wikidata Query Service SPARQL endpoint — free, keyless, but it 403s a request with no identifying User-Agent (Wikimedia's own UA policy).

Install

go get github.com/olehmushka/go-wikidata-client

Usage

c := wikidataclient.New(nil, wikidataclient.WithUserAgent("myapp/1.0 (contact@example.com)"))

result, err := c.Query(ctx, `
    SELECT ?org ?orgLabel WHERE {
        ?org wdt:P31 wd:Q7278.
        SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
    }
`)
for _, row := range result.Rows {
    row["org"].Value      // the entity URI
    row["orgLabel"].Value // the label literal
}

Scope

This client decodes the standard SPARQL 1.1 Query Results JSON Format generically — it has no knowledge of any particular query's projected variables or what they mean. Turning a result row into an application's own domain type is the caller's job. Because the format is a W3C standard, this client works against any conformant SPARQL endpoint, not only Wikidata's (WithEndpoint).

Notes

Built on go-govapi-core for the JSON-fetch helper and User-Agent conventions. The request shape mirrors an already-shipped, already-verified integration against this same endpoint in go-oikumenea's internal/hermenea/fetcher/fetcher.go (the generic HTTP fetcher used for Wikidata SPARQL sources) and internal/hermenea/wikidataorgs/mapper.go (its D-ExternalOrgs / M30 consumer) — this package is that integration's fetch+decode layer, extracted and generalized to the standard format rather than one caller's projected fields.

License

Apache 2.0 — see LICENSE.

Documentation

Overview

Package wikidataclient is a small client for the Wikidata Query Service SPARQL endpoint (https://query.wikidata.org/sparql) — free, keyless, but it 403s a request with no identifying User-Agent (Wikimedia's own UA policy).

It decodes the standard SPARQL 1.1 Query Results JSON Format (https://www.w3.org/TR/sparql11-results-json/) — `head.vars` + `results.bindings` — generically: this package has no knowledge of any particular query's projected variables or what they mean. Turning a result row into an application's own domain type (e.g. an organization record) is the caller's job.

The request shape (endpoint, format=json, query param, Accept header, User-Agent requirement) mirrors an already-shipped, already-verified integration against this same endpoint: https://github.com/olehmushka/go-oikumenea/blob/main/internal/hermenea/fetcher/fetcher.go (its generic HTTP fetcher, used for the Wikidata SPARQL source) and https://github.com/olehmushka/go-oikumenea/blob/main/internal/hermenea/wikidataorgs/mapper.go (D-ExternalOrgs / M30, which reads this exact JSON shape) — this package is that integration's fetch+decode layer, extracted and generalized to the standard format rather than one caller's projected fields.

Index

• Constants
• type Client
  • func New(httpClient *http.Client, opts ...Option) *Client
  • func (c *Client) Query(ctx context.Context, query string) (Result, error)
• type Option
  • func WithEndpoint(endpoint string) Option
  • func WithUserAgent(userAgent string) Option
• type Result
• type Value

Constants

const DefaultEndpoint = "https://query.wikidata.org/sparql"

DefaultEndpoint is the public Wikidata Query Service SPARQL endpoint.

const DefaultUserAgent = "go-wikidata-client/0.1 (+https://github.com/olehmushka/go-wikidata-client)"

DefaultUserAgent identifies this client when UserAgentEnv is unset. Wikimedia's UA policy expects a real contact for anything beyond casual use — an operator embedding this client in their own product should set UserAgentEnv to their own.

const UserAgentEnv = "WIKIDATA_CLIENT_USER_AGENT"

UserAgentEnv lets an operator override the outbound User-Agent with their own contact, as Wikimedia's UA policy requires for sustained use.

Types

type Client

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

Client is a Wikidata SPARQL query client. The zero value is not usable — construct one with New.

func New

func New(httpClient *http.Client, opts ...Option) *Client

New constructs a Wikidata SPARQL client. httpClient nil defaults to a client bounded by defaultTimeout (govapicore.NewHTTPClient).

func (*Client) Query

func (c *Client) Query(ctx context.Context, query string) (Result, error)

Query issues one SPARQL query against the endpoint and decodes the standard JSON result format.

type Option

type Option func(*Client)

Option configures a Client constructed via New.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint overrides DefaultEndpoint — e.g. to point at a different SPARQL endpoint entirely (Wikidata's own JSON shape is the standard SPARQL 1.1 format, so this client works against any conformant endpoint, not only Wikidata's).

func WithUserAgent

func WithUserAgent(userAgent string) Option

WithUserAgent overrides the default/env-resolved User-Agent.

type Result

type Result struct {
	Vars []string
	Rows []map[string]Value
}

Result is one SPARQL query's decoded result set. Vars are the projected variable names (SELECT ?org ?orgLabel ... -> ["org", "orgLabel", ...]); Rows are one map[varName]Value per result row. A variable absent from a given row (SPARQL OPTIONAL) is simply absent from that row's map.

type Value

type Value struct {
	Type     string
	Value    string
	DataType string
}

Value is one SPARQL JSON result binding's value — the {"type": ..., "value": ...} pair the standard format uses for every literal/uri/bnode (Type is e.g. "uri", "literal", "typed-literal"; DataType carries a literal's datatype IRI when present).