NameGender Rust
[]
= "0.4"
= { = "1", = ["macros", "rt-multi-thread"] }
use ;
async
An async client built on reqwest with rustls; no OpenSSL needed. Get an API
key from the namegender.com dashboard and keep it on
the server.
Lookups
use ;
client.name.await?;
client.email.await?;
client.username.await?;
// Up to 100 values per request, results in the same order
let bulk = client.bulk.await?;
for r in &bulk.results
Every value costs one credit, unknown results included. gender is None
when the API does not know; check probability and sample_size before
trusting an answer.
Options
| Field | Meaning |
|---|---|
country |
Two-letter country code. Andrea is male in Italy and female in Germany. |
locale |
Language tag such as it-IT; its region is the country when country is absent. en sets none. |
ip |
End user IP address; its country is used when neither of the above applies. Not stored. |
best_guess |
Return the more likely gender even when the evidence is weak. |
ai_fallback |
Ask a language model when the dataset has no answer. Requires AI lookups to be enabled on the account. |
country_source on a response says which one set the country: "country",
"locale", "ip" or None.
Errors
A non-2xx response becomes Error::Api with the HTTP status and the API's
reason code. Branch on the code, not the message:
match client.name.await
Salutation
The opening line of a letter or email, in the recipient's language. One credit per name.
use SalutationOptions;
let de = SalutationOptions ;
let r = client.salutation.await?;
println!; // Sehr geehrte Frau Dr. Müller,
let tr = SalutationOptions ;
let r = client.salutation.await?;
println!; // Sayın Ahmet Bey,
// First and last name stored separately; they are not parsed
let r = client.salutation_by_parts.await?;
// Up to 100 names, results in the same order
let bulk = client.salutation_bulk.await?;
println!;
SalutationOptions has language, country, locale, ip, gender
(male, female or neutral; overrides the lookup), min_probability
(50-100, default 90) and title (Dr.). When the gender is not certain the
salutation uses the neutral form: form (gendered, neutral,
organization) and reason say why. salutation.neutral is always the
gender-free line and parts holds the pieces of the formal one. best_guess
does not apply here. An unsupported language is an Error::Api with
invalid_input and HTTP 422.
Name check
Whether a name typed into a form looks like a real person's name, with the reasons. One credit per name.
use NameCheckOptions;
let none = default;
let r = client.name_check.await?;
println!; // implausible 0
let r = client.name_check_by_parts.await?;
println!; // plausible
// Up to 100 names, results in the same order
let bulk = client.name_check_bulk.await?;
println!;
assessment is plausible, suspicious or implausible, score is 0-100
and signals lists the reasons (code, severity, part, value).
NameCheckOptions has country, locale and ip. It never calls a name
fake: use it to flag records for a closer look, not to reject people
automatically. Surnames are judged by their shape only; evidence says what
the database knows about the first name.
Age from name
The typical age of the people who carry a first name, from birth records. One credit per name.
use AgeOptions;
let none = default;
let r = client.age.await?;
println!; // Some(36), the median
if let Some = &r.age_range
// Up to 100 names, results in the same order
let bulk = client.age_bulk.await?;
age_range_80 is the middle 80%; a result also has birth_year,
sample_size, births, country, country_source, source, series and
reference_year. AgeOptions has gender (male or female; narrows the
estimate to that gender's records), country, locale and ip. With no hint
US data is used and country_source is default.
It covers the US, France and Norway. A name with no estimate is a normal
result, not an error: age is None and reason is not_found,
insufficient_data or country_not_covered (any other country; no credit
charged). It describes a group, not a person: never use it for decisions about
an individual.
Country distribution and account
let dist = client.countries.await?;
println!;
let account = client.account.await?; // costs nothing
println!;
countries reports which countries a name is recorded in. It is not a
country-of-origin or ethnicity inference: registrations is counted volume
from the countries that publish counted birth statistics, and attested_in is
presence with no weight attached. Show basis["note"] next to any percentage.
License
MIT