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

News

16.03.2017

Version 5.2 Deployed

As announced, the new version has been installed.


02.03.2017

Version 5.2 release candidate is online

More names, more cultures.


01.11.2016

Version 5.1 Deployed

As announced, the new version has been installed.


18.10.2016

Version 5.1 release candidate is online

More names, more cultures.


12.05.2016

Version 5.0 Deployed

As announced, the new version has been installed.


Developer

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()
    .priority(Priority.REALTIME)
    .build();
$context = Context::builder()
    ->priority(Priority::REALTIME)
    ->build();
"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();
Endpoint: http://rc50-api.nameapi.org/rest/v5.0/system/ping
Method: GET
Example: http://rc50-api.nameapi.org/rest/v5.0/system/ping?apiKey=YOUR_API_KEY
WSDL: http://api.nameapi.org/soap/v4.0/system/pinger?wsdl

Parsing a name

Splitting the name into its parts goes like this:

PersonNameParserCommand command = new PersonNameParserCommand();
InputPersonName name = NameBuilders.western().fullname("John F. Kennedy")
  .build();
InputPerson inputPerson = new NaturalInputPersonBuilder().name(name)
  .build();
PersonNameParserResult result = executor.execute(command, mode, inputPerson)
  .get();
$personNameParser = serviceFactory->parserServices()->personNameParser();
$inputPerson = NaturalInputPerson::builder()
    ->name(InputPersonName::westernBuilder()
        ->fullname( "John Doe" )
        ->build())
    ->build();
$parseResult = $personNameParser->parse($inputPerson);
var_dump($parseResult);
curl -H "Content-Type: application/json" -X POST -d '{"inputPerson":{"type":"NaturalInputPerson","personName":{"nameFields":[{"string":"Peter van der Sar","fieldType":"FULLNAME"}]}}}' http://rc50-api.nameapi.org/rest/v5.0/parser/personnameparser?apiKey=YOUR_API_KEY
Endpoint: http://rc50-api.nameapi.org/rest/v5.0/parser/personnameparser?apiKey=YOUR_API_KEY
Method: POST
Content-Type: application/json
(you must set the content-type as http header)

Example inputPerson JSON: 

{
  "inputPerson" : {
    "type" : "NaturalInputPerson",
    "personName" : {
      "nameFields" : [ {
        "string" : "Petra",
        "fieldType" : "GIVENNAME"
      }, {
        "string" : "Meyer",
        "fieldType" : "SURNAME"
      } ]
    },
    "gender" : "UNKNOWN"
  }
}
WSDL: http://api.nameapi.org/soap/v4.0/parser/personnameparser?wsdl

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())
  .build();
GenderizerResult result = executor.execute(command, mode, person).get();
boolean isMale = result.getGender().isMale();//must be true
$personGenderizer = $serviceFactory->genderizerServices()->personGenderizer();
$inputPerson = NaturalInputPerson::builder()
    ->name(InputPersonName::westernBuilder()
        ->fullname( "John Doe" )
        ->build())
    ->build();
$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"}]}}}' http://rc50-api.nameapi.org/rest/v5.0/genderizer/persongenderizer?apiKey=YOUR_API_KEY
Endpoint: http://rc50-api.nameapi.org/rest/v5.0/genderizer/persongenderizer?apiKey=YOUR_API_KEY
Method: POST
Content-Type: application/json
(you must set the content-type as http header)
http://api.nameapi.org/soap/v4.0/genderizer/persongenderizer?wsdl

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())
  .build();
NaturalInputPerson person2 = new NaturalInputPersonBuilder()
  .name(NameBuilders.western().fullname("Jack Kennedy").build())
  .build();
PersonMatcherArgument argument = new PersonMatcherArgument(person1, person2);
PersonMatcherResult result = executor.execute(command, mode, argument).get();
$personMatcher = $serviceFactory->matcherServices()->personMatcher();
$inputPerson1 = NaturalInputPerson::builder()
    ->name(InputPersonName::westernBuilder()
        ->fullname( "John F. Kennedy" )
        ->build())
    ->build();
$inputPerson2 = NaturalInputPerson::builder()
    ->name(InputPersonName::westernBuilder()
        ->fullname( "Jack Kennedy" )
        ->build())
    ->build();
$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"}]}}}' http://rc50-api.nameapi.org/rest/v5.0/matcher/personmatcher?apiKey=YOUR_API_KEY
Endpoint: http://rc50-api.nameapi.org/rest/v5.0/matcher/personmatcher?apiKey=YOUR_API_KEY
Method: POST
Content-Type: application/json
(you must set the content-type as http header)
http://api.nameapi.org/soap/v4.0/matcher/personmatcher?wsdl

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() )
  .build();
FormatterProperties properties = new FormatterProperties(true);
PersonNameFormatterArgument argument = 
  new PersonNameFormatterArgument(person, properties);
FormatterResult formatterResult = executor.execute(command, mode, argument)
  .get();
$personNameFormatter = $serviceFactory->formatterServices()->personNameFormatter();
$inputPerson = NaturalInputPerson::builder()
    ->name(InputPersonName::westernBuilder()
        ->fullname( "john kennedy" )
        ->build())
    ->build();
$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"}]}}}' http://rc50-api.nameapi.org/rest/v5.0/formatter/personnameformatter?apiKey=YOUR_API_KEY
Endpoint: http://rc50-api.nameapi.org/rest/v5.0/formatter/personnameformatter?apiKey=YOUR_API_KEY
Method: POST
Content-Type: application/json
(you must set the content-type as http header)
http://api.nameapi.org/soap/v4.0/formatter/personnameformatter?wsdl

Parsing the name from an email address

Like so:

EmailNameParserCommand command = new EmailNameParserCommand();
EmailNameParserResult result = executor.execute(command, mode, "john.doe@gmail.com").get();
...
curl 'http://rc50-api.nameapi.org/rest/v5.0/email/emailnameparser?apiKey=YOUR_API_KEY&emailAddress=john.doe%40example.org'
Endpoint: http://rc50-api.nameapi.org/rest/v5.0/email/emailnameparser?apiKey=YOUR_API_KEY&emailAddress=THE_EMAIL_ADDRESS
Method: GET
http://api.nameapi.org/soap/v5.0/email/emailnameparser?wsdl

Identifying disposable emails

Need to block trash email addresses?

DisposableEmailAddressDetectorCommand command = new DisposableEmailAddressDetectorCommand();
DisposableEmailAddressDetectorResult result = executor.execute(command, mode, "blahblah@10minutemail.com").get();
$deaDetector = $serviceFactory->emailServices()->disposableEmailAddressDetector();
$result = $deaDetector->isDisposable("abcdefgh@10minutemail.com");
curl 'http://rc50-api.nameapi.org/rest/v5.0/email/disposableemailaddressdetector?apiKey=YOUR_API_KEY&emailAddress=abcdefgh%4010minutemail.com'
Endpoint: http://rc50-api.nameapi.org/rest/v5.0/email/disposableemailaddressdetector?apiKey=YOUR_API_KEY&emailAddress=THE_EMAIL_ADDRESS
Method: GET
http://api.nameapi.org/soap/v5.0/email/disposableemailaddressdetector?wsdl

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")
  .with(StdoutLoggingExtension.enabled());
PingCommand command = new PingCommand();
To target another host or another api version, customize like so:
Mode mode = NameApiModeFactory.withContext(
  "your-api-key",
  myContext, 
  new Host("rc50-api.nameapi.org", Protocol.HTTP), 
  NameApiPortUrlFactory.version5_0()
);
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("rc50-api.nameapi.org"), '5.0');

Next Step

Got it? Download a kit and start hacking!