First Names

Autocomplete first names by prefix. Returns the most popular names matching the query, sorted by frequency.

Try it

—

Endpoint

GET/v1/first-name/<query>

Base URL: https://autocomplete.namedone.com

SDK Usage

firstNames()

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

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 first names endpoint
7curl "https://autocomplete.namedone.com/v1/first-name/jo?token=<jwt>"

Response Format

JSON

{
  "results": [
    {
      "id": "first-name-0",
      "text": "John",
      "type": "first-name"
    }
  ],
  "query": "jo"
}

API Query Parameters

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

Parameter	Type	Default	Description
token	string	—	JWT obtained from the token API. Required for authentication.

SDK Options

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

Option	Type	Default	Description
limit	number	10	Maximum number of results (1–50). Applied client-side by the SDK.
simple	boolean	false	Simplify response: deduplicate by text and strip to {text, type}.

Examples

Query: jo

{
  "results": [
    {
      "id": "first-name-0",
      "text": "John",
      "type": "first-name"
    },
    {
      "id": "first-name-1",
      "text": "Joseph",
      "type": "first-name"
    },
    {
      "id": "first-name-2",
      "text": "Jonathan",
      "type": "first-name"
    },
    {
      "id": "first-name-3",
      "text": "Joshua",
      "type": "first-name"
    },
    {
      "id": "first-name-4",
      "text": "Jordan",
      "type": "first-name"
    }
  ],
  "query": "jo"
}

Query: ab

{
  "results": [
    {
      "id": "first-name-0",
      "text": "Abdul",
      "type": "first-name"
    },
    {
      "id": "first-name-1",
      "text": "Abigail",
      "type": "first-name"
    },
    {
      "id": "first-name-2",
      "text": "Abraham",
      "type": "first-name"
    },
    {
      "id": "first-name-3",
      "text": "Abbie",
      "type": "first-name"
    },
    {
      "id": "first-name-4",
      "text": "Abdullah",
      "type": "first-name"
    }
  ],
  "query": "ab"
}

Notes

Names are sorted by popularity (frequency in the living UK population), not alphabetically.
The prefix-list architecture pre-computes the top 50 names for each prefix, so even common prefixes like "jo" return instantly.
1–2 character queries are served directly from CloudFront KVS without hitting Lambda or DynamoDB.
Middle names: if you need to collect a middle name, use a separate optional field with its own firstNames() autocomplete. Do not label it as "optional" — the GOV.UK Design System recommends allowing empty fields without calling them out. Alternatively, use a single "Full name" field with fullNames() and let the user type their full name naturally.