Skip to content
Finowl

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. 1

    Export FINOWL_API_KEY and save the program as main.go.

  2. 2

    Pass a two-letter country code with each name, and drop the key from the payload when you have no reliable country.

  3. 3

    Check ResultStatus before dereferencing Gender, which is nil for unknown results.

  4. 4

    Persist Confidence and Source with each prediction for later filtering.

Predict gender from names in Go with net/http
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

Predict gender from names in Go with net/http

Grab an API key, paste the example and run it. 100 free credits every month.