Formal Names

Autocomplete formal names by prefix. Returns title + name combinations like "Mr Jones", "Sir Paul", and "Duke of Edinburgh" from a curated list of titles, popular surnames, and famous people. The SDK's formalNames() method enhances this endpoint by automatically switching to the first-name, last-name, or towns endpoints once a title is complete — enabling patterns like "Mr John Smith" (title + first + last) and "Duke of Edinburgh" (title + of + place) that aren't available from the raw API alone.

Try it

Endpoint

SDK Usage

1import { createClient } from "@namedone/autocomplete"
2​
3const nd = createClient("nd_...")
4const { results } = await nd.formalNames("m")

curl

1# Exchange your API key for a token
2curl -X POST https://token.namedone.com/v1 \
3  -H "Content-Type: application/json" \
4  -d '{"apiKey":"nd_..."}'
5​
6# Query the formal names endpoint
7curl "https://autocomplete.namedone.com/v1/formal-name/m?token=<jwt>"

Response Format

{
  "results": [
    {
      "id": "formal-name-0",
      "text": "Marquess of Bath",
      "type": "formal-name"
    }
  ],
  "query": "m"
}

API Query Parameters

Sent as query string parameters on the HTTP request to the API.

SDK Options

Passed to the SDK methods (e.g. firstNames(query, opts)). These are processed client-side and never sent to the API.

Examples

{
  "results": [
    {
      "id": "formal-name-0",
      "text": "Marquess of Bath",
      "type": "formal-name"
    },
    {
      "id": "formal-name-1",
      "text": "Marquess of Salisbury",
      "type": "formal-name"
    },
    {
      "id": "formal-name-2",
      "text": "Mr Adams",
      "type": "formal-name"
    },
    {
      "id": "formal-name-3",
      "text": "Mrs Anderson",
      "type": "formal-name"
    },
    {
      "id": "formal-name-4",
      "text": "Miss Allen",
      "type": "formal-name"
    }
  ],
  "query": "m"
}

{
  "results": [
    {
      "id": "formal-name-0",
      "text": "Mr Jones",
      "type": "formal-name"
    },
    {
      "id": "formal-name-1",
      "text": "Mr Johnson",
      "type": "formal-name"
    },
    {
      "id": "formal-name-2",
      "text": "Mr Jackson",
      "type": "formal-name"
    },
    {
      "id": "formal-name-3",
      "text": "Mr Jenkins",
      "type": "formal-name"
    },
    {
      "id": "formal-name-4",
      "text": "Mr Jordan",
      "type": "formal-name"
    }
  ],
  "query": "mr j"
}

{
  "results": [
    {
      "id": "formal-name-0",
      "text": "Sir Paul McCartney",
      "type": "formal-name"
    },
    {
      "id": "formal-name-1",
      "text": "Sir Patrick Stewart",
      "type": "formal-name"
    },
    {
      "id": "formal-name-2",
      "text": "Sir Peter",
      "type": "formal-name"
    }
  ],
  "query": "sir p"
}

{
  "results": [
    {
      "id": "formal-name-0",
      "text": "Duke of Edinburgh",
      "type": "formal-name"
    },
    {
      "id": "formal-name-1",
      "text": "Duke of Exeter",
      "type": "formal-name"
    }
  ],
  "query": "duke of e"
}

Notes

• Formal names are built from a curated list of ~75 UK titles combined with the most popular surnames and first names, plus ~700 famous people from across the British Isles.
• Most titles pair with surnames (Mr Jones, Dr Smith, Lord Sugar). Some titles pair with first names (Sir Paul, Prince William, Dame Judi).
• Famous people (e.g. Prince William, Sir Elton John, Duke of Edinburgh) are included in the results and appear first when they match the query.
• The SDK's formalNames() method offers additional patterns beyond the raw API endpoint by switching to other endpoints once a title is detected:
• "Mr j" → calls /v1/last-name/ and prepends "Mr" (e.g. Mr Jones, Mr Johnson). "Sir p" → calls /v1/first-name/male/ and prepends "Sir" (e.g. Sir Paul, Sir Peter).
• "Mr john s" → calls /v1/first-name/male/ and /v1/last-name/ in parallel, combining as "Mr John Smith". "Duke of e" → calls /v1/town/ and prepends "Duke of" (e.g. Duke of Edinburgh).
• Gendered titles automatically use the corresponding gendered name endpoint: Sir, King, Prince, Mr, Duke, Lord, etc. search male names; Dame, Queen, Princess, Mrs, Miss, Lady, Duchess, etc. search female names. Gender-neutral titles (Dr, Prof, Rev, HRH, Saint) use the combined first-name endpoint.
• Use the pattern option to restrict results: "auto" (default) allows all patterns; "title-last" for title + surname only (e.g. teacher fields); "title-first" for title + first name only; "title-first-last" for full formal names only.