Documentation
¶
Overview ¶
Package openverse is the library behind the openverse command line: the HTTP client, request shaping, and the typed data models for the OpenVerse API at api.openverse.org.
OpenVerse is WordPress's index of Creative Commons licensed images and audio. Anonymous access is free and works without an API key; each query returns up to 240 results (20 per page, 12 pages).
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 API throws under load.
Index ¶
Constants ¶
const BaseURL = "https://api.openverse.org/v1"
BaseURL is the versioned API root every request is built from.
const DefaultUserAgent = "openverse-cli/0.1 (tamnd87@gmail.com)"
DefaultUserAgent identifies the client to OpenVerse.
const Host = "api.openverse.org"
Host is the API hostname.
Variables ¶
var ErrNotFound = fmt.Errorf("not found")
ErrNotFound is returned when the API responds with 404.
var ErrRateLimited = fmt.Errorf("rate limited")
ErrRateLimited is returned when the API responds with 429 after all retries.
Functions ¶
This section is empty.
Types ¶
type Audio ¶
type Audio struct {
ID string `json:"id" kit:"id" table:"id"`
Title string `json:"title" table:"title"`
Creator string `json:"creator,omitempty" table:"creator"`
CreatorURL string `json:"creator_url,omitempty" table:"-"`
URL string `json:"url" table:"url,url"`
Thumbnail string `json:"thumbnail,omitempty" table:"-"`
DetailURL string `json:"detail_url,omitempty" table:"-"`
ForeignLandingURL string `json:"foreign_landing_url,omitempty" table:"-"`
License string `json:"license" table:"license"`
LicenseVersion string `json:"license_version,omitempty" table:"-"`
LicenseURL string `json:"license_url,omitempty" table:"-"`
Provider string `json:"provider" table:"provider"`
Source string `json:"source,omitempty" table:"-"`
Duration int `json:"duration,omitempty" table:"duration"`
BitRate int `json:"bit_rate,omitempty" table:"bit_rate"`
SampleRate int `json:"sample_rate,omitempty" table:"-"`
Tags []string `json:"tags,omitempty" table:"tags"`
}
Audio is one Creative Commons licensed audio track from OpenVerse.
type AudioSearchParams ¶
AudioSearchParams holds the optional filters for audio search.
type Client ¶
type Client struct {
HTTP *http.Client
UserAgent string
BaseURL string
// Rate is the minimum gap between requests. Zero means no pacing.
Rate time.Duration
Retries int
// contains filtered or unexported fields
}
Client talks to the OpenVerse API over HTTP.
func NewClient ¶
func NewClient() *Client
NewClient returns a Client with sensible defaults: a 15s timeout, a 500ms minimum gap between requests, and three retries on transient errors.
func (*Client) Get ¶
Get fetches rawURL and returns the response body. It paces and retries according to the client's settings. The caller owns nothing extra; the body is read fully and closed here.
func (*Client) SearchAudio ¶
func (c *Client) SearchAudio(ctx context.Context, query string, p AudioSearchParams) ([]*Audio, error)
SearchAudio queries the /v1/audio/ endpoint and returns the results.
func (*Client) SearchImages ¶
func (c *Client) SearchImages(ctx context.Context, query string, p ImageSearchParams) ([]*Image, error)
SearchImages queries the /v1/images/ endpoint and returns the results.
type Domain ¶
type Domain struct{}
Domain is the openverse driver. It carries no state; the per-run client is built by the factory Register hands to kit.
func (Domain) Classify ¶
Classify turns any accepted input (a UUID or a full API URL) into the canonical (type, id) pair so `ant resolve` and `ant url` touch no network.
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.
type Image ¶
type Image struct {
ID string `json:"id" kit:"id" table:"id"`
Title string `json:"title" table:"title"`
Creator string `json:"creator,omitempty" table:"creator"`
CreatorURL string `json:"creator_url,omitempty" table:"-"`
URL string `json:"url" table:"url,url"`
Thumbnail string `json:"thumbnail,omitempty" table:"-"`
DetailURL string `json:"detail_url,omitempty" table:"-"`
ForeignLandingURL string `json:"foreign_landing_url,omitempty" table:"-"`
License string `json:"license" table:"license"`
LicenseVersion string `json:"license_version,omitempty" table:"-"`
LicenseURL string `json:"license_url,omitempty" table:"-"`
Provider string `json:"provider" table:"provider"`
Source string `json:"source,omitempty" table:"-"`
Width int `json:"width,omitempty" table:"width"`
Height int `json:"height,omitempty" table:"height"`
Tags []string `json:"tags,omitempty" table:"tags"`
}
Image is one Creative Commons licensed image from OpenVerse.
type ImageSearchParams ¶
ImageSearchParams holds the optional filters for image search.
type License ¶
type License struct {
Code string `json:"code" table:"code"`
Name string `json:"name" table:"name"`
URL string `json:"url" table:"url,url"`
Commercial bool `json:"commercial" table:"commercial"`
Derivatives string `json:"derivatives" table:"derivatives"` // "yes", "no", "share-alike"
}
License describes a Creative Commons license type.
func KnownLicenses ¶
func KnownLicenses() []*License
KnownLicenses returns the static list of Creative Commons license types that OpenVerse supports. No API call is made.
Source Files