genderize

README

Genderize

Go client for the Genderize.io web service.

Full API documentation is available on GoDocs.

Basic usage

Simple interface with minimal configuration.

Code

responses, err := Get([]string{"James", "Eva", "Thunderhorse"})
if err != nil {
    panic(err)
}
for _, response := range responses {
    fmt.Printf("%s: %s\n", response.Name, response.Gender)
}

Output

James: male
Eva: female
Thunderhorse:

Advanced usage

Client with custom API key and user agent, query with language and country IDs.

Code

client, err := NewClient(Config{
    UserAgent: "GoGenderizeDocs/0.0",
    // Note that you'll need to use your own API key.
    APIKey: "",
})
if err != nil {
    panic(err)
}
responses, err := client.Get(Query{
    Names:      []string{"Kim"},
    CountryID:  "dk",
    LanguageID: "da",
})
if err != nil {
    panic(err)
}
for _, response := range responses {
    fmt.Printf("%s: %s\n", response.Name, response.Gender)
}

Output

Kim: male

Release checklist

1. Generate a new version number: major.minor.micro. It should be compatible with SemVer 2.0.0.
2. Update Version in genderize.go.
3. Add a changelog entry and date for the new version in CHANGES.md.
4. Commit the changes. This may be done as part of another change.
5. Tag the commit with git tag major.minor.micro.
6. Push the tag to GitHub with git push origin major.minor.micro.

Documentation

Overview

Package genderize provides a client for the Genderize.io web service.

Index

• Constants
• type Client
  • func NewClient(config Config) (*Client, error)
  • func (client *Client) Get(query Query) ([]Response, error)
• type Config
• type Query
• type RateLimit
• type Response
  • func Get(names []string) ([]Response, error)
• type ServerError
  • func (serverError ServerError) Error() string

Examples

• Client.Get
• Get

Constants

const (
	Male    = "male"
	Female  = "female"
	Unknown = ""
)

Gender string constants.

const Version = "0.2.0"

Version of this library. Used to form the default user agent string.

Types

type Client

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

Client for the Genderize API.

func NewClient

func NewClient(config Config) (*Client, error)

NewClient constructs a Genderize client from a Config.

func (*Client) Get

func (client *Client) Get(query Query) ([]Response, error)

Get gender info for names with optional country and language IDs.

Example

Client with custom API key and user agent, query with language and country IDs.

client, err := NewClient(Config{
	UserAgent: "GoGenderizeDocs/0.0",
	// Note that you'll need to use your own API key.
	APIKey: "",
})
if err != nil {
	panic(err)
}
responses, err := client.Get(Query{
	Names:      []string{"Kim"},
	CountryID:  "dk",
	LanguageID: "da",
})
if err != nil {
	panic(err)
}
for _, response := range responses {
	fmt.Printf("%s: %s\n", response.Name, response.Gender)
}

Output:

Kim: male

type Config

type Config struct {
	UserAgent  string
	APIKey     string
	Server     string
	HTTPClient *http.Client
}

Config for a Genderize client.

type Query

type Query struct {
	Names      []string
	CountryID  string
	LanguageID string
}

A Query is a list of names with optional country and language IDs.

type RateLimit

type RateLimit struct {
	// The number of names allotted for the current time window.
	Limit int64
	// The number of names left in the current time window.
	Remaining int64
	// Seconds remaining until a new time window opens.
	Reset int64
}

RateLimit holds info on API quotas from rate limit headers. See https://genderize.io/#rate-limiting for details.

type Response

type Response struct {
	Name string
	// Gender can be "male", "female", or empty,
	// in which case Probability and Count should be ignored.
	Gender      string
	Probability float64
	Count       int64
}

A Response is a name with gender and probability information attached.

func Get

func Get(names []string) ([]Response, error)

Get gender info for names, using the default client and country/language IDs.

Example

Simple interface with minimal configuration.

responses, err := Get([]string{"James", "Eva", "Thunderhorse"})
if err != nil {
	panic(err)
}
for _, response := range responses {
	fmt.Printf("%s: %s\n", response.Name, response.Gender)
}

Output:

James: male
Eva: female
Thunderhorse:

type ServerError

type ServerError struct {
	Message    string `json:"error"`
	StatusCode int
	RateLimit  *RateLimit
}

A ServerError contains a message from the Genderize API server.

func (ServerError) Error

func (serverError ServerError) Error() string

Error returns the error message.