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

News

28.04.2016

Version 5 release candidate is online

This is the time to test your installations.


14.03.2016

Faster server failure detection

When one server is on strike, it is removed from the pool instantly.


17.02.2016

Faster trash email domain detection

New domains are caught as soon as they appear.


09.02.2016

Version 5 preview is online

Test the new REST API, give early feedback.


10.11.2015

Announcing Version 5

The next major version will bring a brand new REST API.


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!