Go · Gender prediction
Predict gender from names in Go with net/http
The gender name endpoint wraps its prediction in a data object, so the Go example decodes into a small envelope struct with a Prediction inside. Fields like result_status and confidence_kind use snake_case, which is where json struct tags earn their keep. Gender is a pointer so a JSON null becomes nil, which matches how the API represents unknown results, while Reason is a plain string that stays empty for identified names.
The country hint is optional and accepts any ISO 3166-1 alpha-2 code in any case. The program compares Andrea in Italy and the United States, then sends a made-up name to show the unknown path. When result_status is unknown, Gender is nil and Reason explains why. Treat that as a normal outcome, not an error, since it is a successful and charged lookup.
Steps
- 1
Export FINOWL_API_KEY and save the program as main.go.
- 2
Pass a two-letter country code with each name, and drop the key from the payload when you have no reliable country.
- 3
Check ResultStatus before dereferencing Gender, which is nil for unknown results.
- 4
Persist Confidence and Source with each prediction for later filtering.
package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
"strconv"
"time"
)
type Prediction struct {
ResultStatus string `json:"result_status"`
Gender *string `json:"gender"`
Confidence float64 `json:"confidence"`
Source string `json:"source"`
Country string `json:"country"`
Reason string `json:"reason"`
}
var client = &http.Client{Timeout: 10 * time.Second}
func predict(name, country string) (*Prediction, error) {
body, _ := json.Marshal(map[string]string{"name": name, "country": country})
for attempt := 0; attempt < 3; attempt++ {
req, _ := http.NewRequest(http.MethodPost, "https://api.finowl.co/v1/gender/name", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("FINOWL_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
return nil, err
}
var out struct {
Data *Prediction
Error struct{ Code string }
}
_ = json.NewDecoder(resp.Body).Decode(&out)
resp.Body.Close()
switch {
case resp.StatusCode == http.StatusOK:
return out.Data, nil
case resp.StatusCode == http.StatusBadRequest, resp.StatusCode == http.StatusUnauthorized:
return nil, fmt.Errorf("request rejected (%d): %s", resp.StatusCode, out.Error.Code)
case resp.StatusCode == http.StatusTooManyRequests && out.Error.Code == "rate_limited":
secs, _ := strconv.Atoi(resp.Header.Get("Retry-After"))
time.Sleep(time.Duration(max(secs, 1)) * time.Second)
default:
return nil, fmt.Errorf("finowl error %d: %s", resp.StatusCode, out.Error.Code)
}
}
return nil, fmt.Errorf("still rate limited")
}
func main() {
for _, in := range [][2]string{{"Andrea", "IT"}, {"Andrea", "US"}, {"Qwzx", "GB"}} {
p, err := predict(in[0], in[1])
if err != nil {
log.Fatal(err)
}
if p.ResultStatus == "unknown" {
fmt.Printf("%s [%s]: unknown, reason=%s\n", in[0], in[1], p.Reason)
continue
}
fmt.Printf("%s [%s]: %s confidence=%.2f source=%s country=%s\n", in[0], in[1], *p.Gender, p.Confidence, p.Source, p.Country)
}
}IN PRODUCTION
Production tips
For bulk jobs, post up to 50 items to /v1/gender/batch in a single request. It counts once against the rate limit and returns results in the order you sent them.
Always check ResultStatus, or test Gender for nil, before dereferencing it. A nil pointer panic inside a worker goroutine can take down the whole process, not just one lookup.
Keep predictions out of eligibility, pricing or access decisions. Use them for aggregate reporting or light personalization, and let people correct their own gender in your product.
Each lookup costs 1 credit (3 when it requests AI), with 100 free credits every month. See pricing and error codes.
A FEW GOOD QUESTIONS
Common questions
Related guides
- Check email breaches in Go with net/http
- Check breached passwords in Go before storing them
- Predict gender from names in Python
- Predict gender from a name in Node.js
- Batch gender prediction in TypeScript
- Predict gender from names in Java 17
- Gender analytics from names for fintech audiences
- Gender insights from names for e-commerce analytics
- Gender estimates for SaaS user research and analytics
Predict gender from names in Go with net/http
Grab an API key, paste the example and run it. 100 free credits every month.