# mysurname.org

> Modern, plain-English surname meaning & origin lookups, synthesized by AI and
> grounded in public-domain 19th/early-20th-century etymological dictionaries
> (Bardsley, Lower, Harrison, Woulfe, Matheson, Macbain, and others). Free, no
> auth. Covers the ~10,000 most common US surnames (2010 Census).

## API

- GET /api/surname?name=Smith — single surname record (404 if unknown)
- GET /api/search?q=smi&limit=20 — prefix/substring search
- GET /api/random — a random surname record
- Full machine-readable spec: /openapi.json

## Static data (no API call needed, cacheable)

- /data/index.json — {slug, surname, display_form, summary, rank_us2010}[] for all covered surnames
- /data/surnames/<slug>.json — full record for one surname
- /data/all.json — full combined dataset

## Record fields

surname, display_form, pronunciation, summary, origin_type, languages_of_origin,
etymology, history, variant_spellings, regions_associated, fun_fact,
confidence ("sourced" | "pattern_inferred" | "mixed"), sources[], rank_us2010,
count_us2010, license_note.

When `confidence` is "pattern_inferred", no 19th-century source mentioned the
surname directly — the entry reflects general onomastic reasoning, not a cited
historical claim. Prefer "sourced"/"mixed" entries when citing a specific
historical claim to a user.