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.
1. Swagger Integration
We have integrated Swagger directly into our API, providing you with a comprehensive interface to interact with our endpoints. With Swagger, you can easily navigate through available endpoints, understand their functionality, and make test requests right from your browser.
Visit https://api.nameapi.org/rest/swagger-ui/ to explore and experiment with our API endpoints.
2. Interacting with our Services through Code
Below, we provide code snippets in various languages to demonstrate how you can access our services directly from your code.
2.1 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.
2.2 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();
WSDL: https://api.nameapi.org/soap/v4.0/system/pinger?wsdl
2.3 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"}]}}}' https://api.nameapi.org/rest/v5.3/parser/personnameparser?apiKey=YOUR_API_KEY
WSDL: https://api.nameapi.org/soap/v4.0/parser/personnameparser?wsdl
2.4 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"}]}}}' https://api.nameapi.org/rest/v5.3/genderizer/persongenderizer?apiKey=YOUR_API_KEY
https://api.nameapi.org/soap/v4.0/genderizer/persongenderizer?wsdl
2.5 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"}]}}}' https://api.nameapi.org/rest/v5.3/matcher/personmatcher?apiKey=YOUR_API_KEY
https://api.nameapi.org/soap/v4.0/matcher/personmatcher?wsdl
2.6 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"}]}}}' https://api.nameapi.org/rest/v5.3/formatter/personnameformatter?apiKey=YOUR_API_KEY
https://api.nameapi.org/soap/v4.0/formatter/personnameformatter?wsdl
2.7 Parsing the Name from an Email Address
Like so:
EmailNameParserCommand command = new EmailNameParserCommand(); EmailNameParserResult result = executor.execute(command, mode, "[email protected]").get();
...
curl 'https://api.nameapi.org/rest/v5.3/email/emailnameparser?apiKey=YOUR_API_KEY&emailAddress=john.doe%40example.org'
https://api.nameapi.org/soap/v5.0/email/emailnameparser?wsdl
2.8 Identifying Disposable Emails
Need to block trash email addresses?
DisposableEmailAddressDetectorCommand command = new DisposableEmailAddressDetectorCommand(); DisposableEmailAddressDetectorResult result = executor.execute(command, mode, "[email protected]").get();
$deaDetector = $serviceFactory->emailServices()->disposableEmailAddressDetector();
$result = $deaDetector->isDisposable("[email protected]");
curl 'https://api.nameapi.org/rest/v5.3/email/disposableemailaddressdetector?apiKey=YOUR_API_KEY&emailAddress=abcdefgh%4010minutemail.com'
https://api.nameapi.org/soap/v5.0/email/disposableemailaddressdetector?wsdl
2.9 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("api.nameapi.org", Protocol.HTTP),
NameApiPortUrlFactory.version5_3()
);
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("api.nameapi.org"), '5.3');
2.10 Next Step
Got it? Download a kit and start hacking!