NameAPI is a web API
to handle people's names
in your software.



Version 5.3 Deployed

New version 5.3 available.


Version 5.3 release candidate is online

More names, more cultures and a new web service: Risk Detector.


Version 5.2 Deployed

As announced, the new version has been installed.


Version 5.2 release candidate is online

More names, more cultures.


Version 5.1 Deployed

As announced, the new version has been installed.



We're developers too. And so we strive to make your experience as pleasant as it can be. But enough with the marketing palaver - show me some code.

Creating a Context

With the context you may pass information about your execution environment to help the server understand you better, and to control the server's behavior for your call. The context is sent along with every request to the server.

Context myContext = new ContextBuilder()
$context = Context::builder()
"context" : {
    "priority" : "REALTIME",
    "properties" : [ ]

Sending a Ping

The most simple service, to check if all is set up correctly.

PingCommand command = new PingCommand();
String pong = executor.execute(command, mode, null).get();
$pinger = $serviceFactory->systemServices()->pinger();
$pong = $pinger->ping();

Parsing a name

Splitting the name into its parts goes like this:

PersonNameParserCommand command = new PersonNameParserCommand();
InputPersonName name = NameBuilders.western().fullname("John F. Kennedy")
InputPerson inputPerson = new NaturalInputPersonBuilder().name(name)
PersonNameParserResult result = executor.execute(command, mode, inputPerson)
$personNameParser = serviceFactory->parserServices()->personNameParser();
$inputPerson = NaturalInputPerson::builder()
        ->fullname( "John Doe" )
$parseResult = $personNameParser->parse($inputPerson);
curl -H "Content-Type: application/json" -X POST -d '{"inputPerson":{"type":"NaturalInputPerson","personName":{"nameFields":[{"string":"Peter van der Sar","fieldType":"FULLNAME"}]}}}'

Detecting the Gender

Finding the gender for a person's name is as easy as that:

PersonGenderizerCommand command = new PersonGenderizerCommand();
NaturalInputPerson person = new NaturalInputPersonBuilder()
  .name(NameBuilders.western().fullname("John Doe").build())
GenderizerResult result = executor.execute(command, mode, person).get();
boolean isMale = result.getGender().isMale();//must be true
$personGenderizer = $serviceFactory->genderizerServices()->personGenderizer();
$inputPerson = NaturalInputPerson::builder()
        ->fullname( "John Doe" )
$personGenderResult = $personGenderizer->assess($inputPerson);
echo $personGenderResult->getGender()->toString(); //will print 'MALE'
curl -H "Content-Type: application/json" -X POST -d '{"inputPerson":{"type":"NaturalInputPerson","personName":{"nameFields":[{"string":"Peter van der Sar","fieldType":"FULLNAME"}]}}}'

Matching two people

Comparing two people and their names:

PersonMatcherCommand command = new PersonMatcherCommand();
NaturalInputPerson person1 = new NaturalInputPersonBuilder()
  .name(NameBuilders.western().fullname("John F. Kennedy").build())
NaturalInputPerson person2 = new NaturalInputPersonBuilder()
  .name(NameBuilders.western().fullname("Jack Kennedy").build())
PersonMatcherArgument argument = new PersonMatcherArgument(person1, person2);
PersonMatcherResult result = executor.execute(command, mode, argument).get();
$personMatcher = $serviceFactory->matcherServices()->personMatcher();
$inputPerson1 = NaturalInputPerson::builder()
        ->fullname( "John F. Kennedy" )
$inputPerson2 = NaturalInputPerson::builder()
        ->fullname( "Jack Kennedy" )
$personMatchResult = $personMatcher->match($inputPerson1, $inputPerson2);
echo $personMatchResult->getPersonMatchType()->toString(); //prints 'MATCHING'
curl -H "Content-Type: application/json" -X POST -d '{"inputPerson1":{"type":"NaturalInputPerson","personName":{"nameFields":[{"string":"Frau Angela Merkel","fieldType":"FULLNAME"}]}}, "inputPerson2":{"type":"NaturalInputPerson","personName":{"nameFields":[{"string":"Angela Dorothea Merkel","fieldType":"FULLNAME"}]}}}'

Formatting a name

Need to fix upper/lower case, or have the surname first for sorted output? Use the name formatter:

PersonNameFormatterCommand command = new PersonNameFormatterCommand();
NaturalInputPerson person = new NaturalInputPersonBuilder()
  .name( NameBuilders.western().fullname("john f. kennedy").build() )
FormatterProperties properties = new FormatterProperties(true);
PersonNameFormatterArgument argument = 
  new PersonNameFormatterArgument(person, properties);
FormatterResult formatterResult = executor.execute(command, mode, argument)
$personNameFormatter = $serviceFactory->formatterServices()->personNameFormatter();
$inputPerson = NaturalInputPerson::builder()
        ->fullname( "john kennedy" )
$formatterResult = $personNameFormatter->format($inputPerson, new FormatterProperties());
echo $formatterResult->getFormatted(); //prints 'John Kennedy'
curl -H "Content-Type: application/json" -X POST -d '{"inputPerson":{"type":"NaturalInputPerson","personName":{"nameFields":[{"string":"PETER VAN DER SAR","fieldType":"FULLNAME"}]}}}'

Parsing the name from an email address

Like so:

EmailNameParserCommand command = new EmailNameParserCommand();
EmailNameParserResult result = executor.execute(command, mode, "").get();
curl ''

Identifying disposable emails

Need to block trash email addresses?

DisposableEmailAddressDetectorCommand command = new DisposableEmailAddressDetectorCommand();
DisposableEmailAddressDetectorResult result = executor.execute(command, mode, "").get();
$deaDetector = $serviceFactory->emailServices()->disposableEmailAddressDetector();
$result = $deaDetector->isDisposable("");
curl ''

Getting a Service

A request is made through a service.

In the Java client library each request is made through a command. The executor service runs the command in a certain mode. This lets you enable cross-cutting concern features as command interceptors like - for example logging and failover - with just one line.
CommandExecutor executor = CommandExecutors.createExecutor();
Mode mode = NameApiModeFactory.minimal("your-api-key")
PingCommand command = new PingCommand();
To target another host or another api version, customize like so:
Mode mode = NameApiModeFactory.withContext(
  new Host("", Protocol.HTTP), 
The service factory returns the same services for your context on each call.
$serviceFactory = new ServiceFactory($context);
$pingService = $serviceFactory->systemServices()->pinger();
To target another host or another api version, customize like so:
new ServiceFactory($context, Host::http(""), '5.0');

Next Step

Got it? Download a kit and start hacking!