Name

Generates a single first name or last name for one or more countries, from real names.

Use it for a column that contains one name, such as a contact's last name, an author or a signatory. Names are selected in proportion to how common they are, so the result matches the names of a real population. Names can be limited by sex, by popularity, by first letter and by length.

For a person, with a first name, last name, sex and date of birth that are consistent with each other, use Person. Two Name fields in the same table are not related to each other.

Sub-field: value

Every row has exactly one name. Unlike String, Name never combines several names, so it has no minWords or maxWords.

Every JSON block on this page is a single field object, one entry in a table's fields array. See Building a Request for the full request structure.

Properties

Property	Type	Default	Description
`beginsWith`	`string[]?`	none	Limits names to those that start with one of these letters. Each entry must be a single character.
`caseOutput`	`CaseOutput`	`"None"`	The case of the generated name.
`countries`	`NameCountryWeight[]`	required	The countries the names are from, each with a relative weight. See Weighted countries.
`map`	`object`	required	Maps the `value` sub-field to a destination column, which must be a text column. See Building a Request.
`maxLength`	`integer?`	none	The longest name length.
`minLength`	`integer?`	none	The shortest name length.
`nullPercentageMax`	`number`	`0`	Upper bound (0-100) of the percentage of rows that should be null. See `nullPercentageMin`.
`nullPercentageMin`	`number`	`0`	Lower bound (0-100) of the percentage of rows that should be null. The rate is fixed once for the whole field from this range, not recalculated per row. Set equal to `nullPercentageMax` for an exact rate.
`part`	`"FirstName"` / `"LastName"`	`"FirstName"`	Whether to generate a first name or a last name.
`popularityMax`	`number?`	none	Upper bound (0-100) of a name's popularity rank in its country. See `popularityMin`.
`popularityMin`	`number?`	none	Lower bound (0-100) of a name's popularity rank in its country, where 0 is the least common and 100 the most common.
`popularityRamp`	`number`	`0`	From 0 to 100, how strongly the selection is weighted toward the more common names within `popularityMin` to `popularityMax`. At `0`, every name in that range is equally likely.
`races`	`NameRaceWeight[]?`	none	Limits names to those whose largest race or Hispanic-origin category is one of these, each with a relative weight. `us` only. See Race and Hispanic origin.
`seed`	`integer`	random	Per-field seed, overriding the request's own `seed` for this field only.
`sex`	`"Male"` / `"Female"`	none	Limits first names to those most often given to this sex. For last names, see Male and female surnames.
`unique`	`boolean`	`false`	Whether every generated name must differ from the others. Limited by the number of names that match the filters. A request for more unique rows than the field can produce is rejected before any data is generated, stating how many are available.

Every property except races applies to each country separately in a multi-country list. With popularityMin set to 90 and two countries, the names are from the most common 10% of each country's names, not from a combined ranking.

Weighted countries

countries contains one or more { country, weight } entries, with at most one entry per country. country is a two-letter code such as us or gb, in upper or lower case. See GET /v1/names/countries for the countries available.

{
  "type": "Name",
  "countries": [
    { "country": "us", "weight": 2 },
    { "country": "gb", "weight": 1 }
  ],
  "part": "FirstName",
  "map": { "value": { "column": "first_name", "dataType": "VarChar" } }
}

first_name
Arcangel
Adrey
Natoshia
Nem
Joalice
Rolanda

For each row, a country is selected by weight, and then a name from that country. Weights are relative, so 2 and 1 give the same distribution as 20 and 10. An entry with no weight has a weight of 1.

Options by country

Most properties apply to every country. Three depend on the country:

races is only accepted when every entry in countries is us. A list with any other country is rejected. See Race and Hispanic origin.
sex on a last name applies only to pl, cz, gr and ie, whose surnames have separate male and female forms. See Male and female surnames.
Script can be set only for gr, jp and kr, whose names are available in more than one writing system. See Script.

sex on a first name, beginsWith, minLength, maxLength, popularityMin, popularityMax and popularityRamp apply to every country.

A combination of filters that no name in a country matches is rejected, and the error identifies the country.

Script

Names for three countries are available in more than one writing system. The script is set on the country's entry in countries, and is accepted only for that country. Each entry has one script, so use two Name fields for names in two scripts.

Country	Property	Values	Default
`gr`	`greekScript`	`true` (Greek alphabet) / `false` (Latin alphabet)	`false`
`jp`	`japaneseScript`	`"Romaji"` / `"Kanji"` / `"Hiragana"`	`"Romaji"`
`kr`	`koreanScript`	`true` (Hangul) / `false` (Latin alphabet)	`false`

A Japanese last name in kanji:

{
  "type": "Name",
  "countries": [{ "country": "jp", "japaneseScript": "Kanji" }],
  "part": "LastName",
  "seed": 5,
  "map": { "value": { "column": "last_name", "dataType": "VarChar" } }
}

last_name
ユン
深田
吉村
松野
白川
嵯峨

Surnames of foreign origin are written in katakana, such as ユン (Yun) in the first row.

A Korean first name in Hangul:

{
  "type": "Name",
  "countries": [{ "country": "kr", "koreanScript": true }],
  "part": "FirstName",
  "map": { "value": { "column": "first_name", "dataType": "VarChar" } }
}

first_name
혜연
경순
영근
기창
종오
찬식

Male and female surnames

In four countries, pl, cz, gr and ie, a surname can have separate male and female forms, and both are included as separate names. sex can be set on a LastName field when countries includes at least one of these four. It limits the surnames of those countries to the male or female forms, and has no effect on the surnames of other countries in the list. For a list with none of these four, sex on a last name is rejected.

A Person field uses the matching surname form for each person's sex automatically.

A Polish surname in its male form:

{
  "type": "Name",
  "countries": [{ "country": "pl" }],
  "part": "LastName",
  "sex": "Male",
  "map": { "value": { "column": "last_name", "dataType": "VarChar" } }
}

last_name
Jóźwiak
Mierzwicki
Żabiński
Zwierzyński
Swora
Aziz

Race and Hispanic origin

races applies to US names only. It has six categories: five race categories, White, Black, AmericanIndianAlaskaNative, AsianPacificIslander and TwoOrMoreRaces, and Hispanic, which is a Hispanic or Latino origin category rather than a race.

Every US name has a percentage breakdown across the six categories, from the people who have that name. A name's plurality is its category with the largest percentage, and races selects names by their plurality.

Weighting the categories

races contains one or more { race, weight } entries, with at most one entry per category.

{
  "type": "Name",
  "countries": [{ "country": "us" }],
  "part": "FirstName",
  "races": [
    { "race": "White", "weight": 3 },
    { "race": "Hispanic", "weight": 1 }
  ],
  "map": { "value": { "column": "first_name", "dataType": "VarChar" } }
}

first_name
Merikay
Priscila
Mariem
Jaycen
Efrat
Reveriano

For each row, a category is selected by weight, and then a name whose plurality is that category. Weights are relative, so 3 and 1 give the same distribution as 30 and 10. An entry with no weight has a weight of 1. Every weight must be greater than 0.

The weights set the distribution of rows, not of the names available. In the example above, about three quarters of the rows have a name whose plurality is White, whatever the number of names in each category.

races and countries weights can be used together, and the rows are distributed across every combination. races requires every country to be us, so in practice only the race weights vary.

Plurality is not the only category

A name's plurality is its largest category, not its only one. A name with a Hispanic plurality also has percentages in the other five categories.

This affects the race and ethnicity sub-fields of a Person field. Those values are generated from the name's full breakdown across all six categories, not only its plurality, so a Person field limited to names with a Hispanic plurality can produce a non-Hispanic race or ethnicity on some rows.

Name has no race or ethnicity sub-field. To generate a race or ethnicity value with a name, map race or ethnicity on a Person field.

Examples

Each example below is a single field object, one entry in a table's fields array within a full request, not a complete request on its own. See Building a Request for how it fits into a full DatasetRequest.

A first name

{
  "type": "Name",
  "countries": [{ "country": "us" }],
  "part": "FirstName",
  "map": { "value": { "column": "first_name", "dataType": "VarChar" } }
}

first_name
Dequarius
Latyra
Umang
Kelliann
Jahnya
Nubar

Common Spanish surnames starting with "G"

Weighted toward the most common names.

{
  "type": "Name",
  "countries": [{ "country": "es" }],
  "part": "LastName",
  "beginsWith": ["G"],
  "popularityMin": 80,
  "popularityRamp": 60,
  "map": { "value": { "column": "last_name", "dataType": "VarChar" } }
}

last_name
Gaitan
Galbis
Guaman
Gordo
Gimenez
Guerrero

A Greek surname in Greek script, in its female form

{
  "type": "Name",
  "countries": [{ "country": "gr", "greekScript": true }],
  "part": "LastName",
  "sex": "Female",
  "map": { "value": { "column": "last_name", "dataType": "VarChar" } }
}

last_name
Γρηγοριου
Αραμπατζή
Καρρα
Βασιλοπουλου
Γεωργιου
Λωλη

Three English-speaking countries, weighted toward the US

{
  "type": "Name",
  "countries": [
    { "country": "us", "weight": 5 },
    { "country": "gb", "weight": 2 },
    { "country": "au", "weight": 1 }
  ],
  "part": "FirstName",
  "map": { "value": { "column": "first_name", "dataType": "VarChar" } }
}

first_name
Baneen
Lazarus
Deliana
Parla
Manjari
Darragh

The country of each row is selected separately by weight, so about five rows in eight have a US name.

US first names with a Hispanic plurality

{
  "type": "Name",
  "countries": [{ "country": "us" }],
  "part": "FirstName",
  "races": [{ "race": "Hispanic" }],
  "map": { "value": { "column": "first_name", "dataType": "VarChar" } }
}

first_name
Ortiz
Karyna
Elis
Gumaro
Jeancarlo
Cilvia

A short, common Japanese first name in hiragana

{
  "type": "Name",
  "countries": [{ "country": "jp", "japaneseScript": "Hiragana" }],
  "part": "FirstName",
  "maxLength": 4,
  "popularityMin": 70,
  "map": { "value": { "column": "first_name", "dataType": "VarChar" } }
}

first_name
あいり
ともひこ
つよし
あつし
ひとみ
まき

Table of Contents