Documentation
¶
Overview ¶
Package api is the demografix CLI's standalone HTTP client for the three Demografix services (genderize.io, agify.io, nationalize.io). It mirrors the SDK's wire contract but is independent of it: the User-Agent is injected (so CLI traffic is distinguishable in the logs) and an API key is required on every request — there is no keyless mode.
Index ¶
- Constants
- type AgifyPrediction
- type AuthError
- type Client
- func (c *Client) Agify(ctx context.Context, names []string, countryID string) ([]AgifyPrediction, Quota, error)
- func (c *Client) Genderize(ctx context.Context, names []string, countryID string) ([]GenderizePrediction, Quota, error)
- func (c *Client) Nationalize(ctx context.Context, names []string) ([]NationalizePrediction, Quota, error)
- func (c *Client) RateLimit(ctx context.Context) (RateLimit, Quota, error)
- type DemografixError
- type Error
- type GenderizePrediction
- type NationalizeCountry
- type NationalizePrediction
- type Quota
- type RateLimit
- type RateLimitError
- type SubscriptionError
- type TransportError
- type ValidationError
Constants ¶
const ( // GenderizeBaseURL, AgifyBaseURL and NationalizeBaseURL are the three // service hosts. The account is shared across all of them. GenderizeBaseURL = "https://api.genderize.io/" AgifyBaseURL = "https://api.agify.io/" NationalizeBaseURL = "https://api.nationalize.io/" // DefaultTimeout is the per-request timeout when none is given. DefaultTimeout = 10 * time.Second // MaxBatch is the largest number of names allowed in one request. MaxBatch = 100 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgifyPrediction ¶
type AgifyPrediction struct {
Name string `json:"name"`
Age *int `json:"age"`
Count int `json:"count"`
CountryID string `json:"country_id,omitempty"`
}
AgifyPrediction is one agify.io result. Age is nil when the API returns null.
type AuthError ¶
type AuthError struct{ DemografixError }
AuthError is a 401 (invalid or missing API key).
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client calls the three services. It is safe for concurrent use.
func New ¶
New builds a Client. apiKey is required; an empty key makes every call fail with a *ValidationError before any HTTP request. userAgent is sent on every request. A non-positive timeout falls back to DefaultTimeout.
func (*Client) Agify ¶
func (c *Client) Agify(ctx context.Context, names []string, countryID string) ([]AgifyPrediction, Quota, error)
Agify predicts the age for up to 100 names, returned in input order.
func (*Client) Genderize ¶
func (c *Client) Genderize(ctx context.Context, names []string, countryID string) ([]GenderizePrediction, Quota, error)
Genderize predicts the gender for up to 100 names, returned in input order.
func (*Client) Nationalize ¶
func (c *Client) Nationalize(ctx context.Context, names []string) ([]NationalizePrediction, Quota, error)
Nationalize predicts the nationality for up to 100 names, returned in input order. The service does not accept a country parameter.
type DemografixError ¶
DemografixError is the base error for every API failure. Status is the HTTP status (0 for client-side or transport failures); Quota is the rate-limit view parsed from the response headers, when present.
func (*DemografixError) Base ¶
func (e *DemografixError) Base() *DemografixError
Base returns the embedded base error. It lets callers reach the status, message, and quota of any typed error via errors.As(err, &apiErr) where apiErr is an Error.
func (*DemografixError) Error ¶
func (e *DemografixError) Error() string
type Error ¶
type Error interface {
error
Base() *DemografixError
}
Error is implemented by every Demografix SDK error (the base and each typed variant), exposing the underlying DemografixError.
type GenderizePrediction ¶
type GenderizePrediction struct {
Name string `json:"name"`
Gender string `json:"gender"`
Probability float64 `json:"probability"`
Count int `json:"count"`
CountryID string `json:"country_id,omitempty"`
}
GenderizePrediction is one genderize.io result. Gender is "male", "female", or "" when the API returns null. CountryID is set only when the request was scoped to a country.
type NationalizeCountry ¶
type NationalizeCountry struct {
CountryID string `json:"country_id"`
Probability float64 `json:"probability"`
}
NationalizeCountry is one candidate country for a nationalize.io result.
type NationalizePrediction ¶
type NationalizePrediction struct {
Name string `json:"name"`
Country []NationalizeCountry `json:"country"`
Count int `json:"count"`
}
NationalizePrediction is one nationalize.io result. Country holds up to five candidates in descending probability and is empty on no match.
type Quota ¶
type Quota struct {
Limit int `json:"limit"`
Remaining int `json:"remaining"`
Reset int `json:"reset"`
}
Quota is the remaining-quota view carried on every response via the x-rate-limit-* headers. Reset is the number of seconds until the window resets.
type RateLimit ¶
type RateLimit struct {
Limit int `json:"limit"`
Remaining int `json:"remaining"`
Reset int `json:"reset"`
Tier string `json:"tier"`
}
RateLimit is the body of the undocumented GET /rate_limit endpoint. The same numbers are also carried on the x-rate-limit-* headers.
type RateLimitError ¶
type RateLimitError struct{ DemografixError }
RateLimitError is a 429. Quota is always populated and Quota.Reset carries the seconds until the window resets.
type SubscriptionError ¶
type SubscriptionError struct{ DemografixError }
SubscriptionError is a 402 (subscription inactive or expired).
type TransportError ¶
type TransportError struct {
DemografixError
Err error
}
TransportError wraps a network, timeout, or non-JSON-body failure.
func (*TransportError) Unwrap ¶
func (e *TransportError) Unwrap() error
type ValidationError ¶
type ValidationError struct{ DemografixError }
ValidationError is a 422 from the server, or a client-side validation failure (Status 0) raised before any HTTP call.
Source Files