API documentation

What it is

A JSON API over the same data the site uses: given a first name, it returns the likely gender, a male probability, a per-country breakdown and ready-made English and German salutations. No account, no key, no rate-limit headers to configure — just call it.

GET /api/check — look up one name

Pass the name as a query parameter. Works with Latin-script and Chinese names.

GET https://dearwho.vercel.app/api/check?name=Andrea

Example response

{
  "query": "Andrea",
  "kind": "latin",
  "canonicalSlug": "andrea",
  "record": {
    "name": "Andrea",
    "verdict": "country_dependent",
    "p": 0.31,
    "confidence": "high",
    "countries": [
      {
        "cc": "it",
        "f": 12,
        "p": 0.98
      },
      {
        "cc": "de",
        "f": 9,
        "p": 0.02
      },
      {
        "cc": "us",
        "f": 8,
        "p": 0.013
      }
    ]
  },
  "greeting": {
    "en": "Dear Andrea Rossi,",
    "de": "Guten Tag Andrea Rossi,"
  },
  "url": "https://dearwho.vercel.app/name/andrea",
  "urlDe": "https://dearwho.vercel.app/de/name/andrea",
  "source": "DearWho - nam_dict (GFDL) + US SSA. Cite: https://dearwho.vercel.app/name/andrea"
}

POST /api/check — bulk lookup

Send up to 200 names at once and get a compact verdict for each, in the same order.

POST https://dearwho.vercel.app/api/check
Content-Type: application/json

{"names": ["Andrea", "Kim", "Wei"]}

POST /api/greeting — generate a salutation

Send a full name, a target language and a formality level; get back a ready-to-use salutation plus the alternates for the other genders.

POST https://dearwho.vercel.app/api/greeting
Content-Type: application/json

{"fullName": "Andrea Rossi", "lang": "en", "formality": "formal", "gender": "auto"}

Copy-paste clients

The same lookup in four tools people actually use.

curl "https://dearwho.vercel.app/api/check?name=Andrea"

fetch("https://dearwho.vercel.app/api/check?name=Andrea")
  .then((res) => res.json())
  .then((data) => console.log(data.record.verdict, data.source));

import requests

response = requests.get("https://dearwho.vercel.app/api/check", params={"name": "Andrea"})
data = response.json()
print(data["record"]["verdict"], data["source"])

=IMPORTDATA("https://dearwho.vercel.app/api/check?name=" & A1)

Rate limits and fair use

There is no hard rate limit today, but this runs on a single small server: keep bulk requests at or under the 200-name cap, cache results on your side rather than re-checking the same name repeatedly, and set a real User-Agent so we can reach you if something needs attention. Heavy or abusive traffic may get throttled without notice.

Licence and attribution

The underlying name data is derived from the nam_dict project and is licensed under the GNU Free Documentation License (GFDL); US figures are blended with public-domain Social Security Administration statistics. If you redistribute or display results at scale, credit DearWho and link back to the corresponding name page — every response already includes that link in its "source" field. Full attribution and source list:

Machine-readable spec

The full OpenAPI 3.1 document, if you want to generate a client or wire up a Custom GPT Action.

MCP server

A read-only MCP server wrapping this API is on the way, for use directly inside Claude and ChatGPT.