no

Intelligence in names.

You are here: Home > Technical Information > REST APIs

REST APIs

REST APIs with JSON. Either use our client implementation, or roll your own.

Client Libraries

Available for:

OpenAPI Specification

Discover and interact with our RESTful APIs:

https://api.nameapi.org/rest/swagger-ui/

Links

➡️ openapis.org
➡️ swagger.io/specification

With this Swagger UI, you can easily navigate through available endpoints, understand their functionality, and make test requests right from your browser.

Integrating the API

Here’s how to call our APIs from your code.

Creating a Context

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

"context" : {
    "priority" : "REALTIME",
    "properties" : [ ]
}
Context myContext = new ContextBuilder()
    .priority(Priority.REALTIME)
    .build();
$context = Context::builder()
    ->priority(Priority::REALTIME())
    ->build();

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());

To target another host or another api version, customize like so:

Mode mode = NameApiModeFactory.withContext(
  "your-api-key",
  myContext, 
  new Host("api.example.com", Protocol.HTTPS), 
  NameApiPortUrlFactory.version5_3()
);
$serviceFactory = new ServiceFactory($context);

To target another host or another api version, customize like so:

new ServiceFactory($context, Host::http("api.nameapi.org"), '5.3');

Use your REST framework to set things up.

Sending a Ping

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

Context myContext = new ContextBuilder()
    .priority(Priority.REALTIME)
    .build();
    
CommandExecutor executor = CommandExecutors.createExecutor();
Mode mode = NameApiModeFactory.minimal("your-api-key");

PingCommand command = new PingCommand();
String pong = executor.execute(command, mode, null).get();
client = NameApiClient(None)
response = client.ping() # return the string 'pong'
$context = Context::builder()
    ->priority(Priority::REALTIME())
    ->build();
    
$serviceFactory = new ServiceFactory($context);

$pinger = $serviceFactory->systemServices()->pinger();
$pong = $pinger->ping();

Parsing a name

Splitting the name into its parts:

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();
api_key = None  # Set your api_key here
client = NameApiClient(api_key)

name_object = WesternInputPersonNameBuilder().fullname("John F. Kennedy").build()
input_person = NaturalInputPersonBuilder().name(name_object).build()

response = client.person_name_parser(input_person)
$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

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
api_key = None  # Set your api_key here
client = NameApiClient(api_key)

name_object = WesternInputPersonNameBuilder().fullname("John F. Kennedy").build()
input_person = NaturalInputPersonBuilder().name(name_object).build()

response = client.person_genderizer(input_person)
$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

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();
api_key = None  # Set your api_key here
client = NameApiClient(api_key)

name_object_1 = WesternInputPersonNameBuilder().fullname("John F. Kennedy").build()
input_person_1 = NaturalInputPersonBuilder().name(name_object).build()

name_object_2 = WesternInputPersonNameBuilder().fullname("Jack Kennedy").build()
input_person_2 = NaturalInputPersonBuilder().name(name_object).build()

response = client.person_matcher(input_person_1, input_person_2)
$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

Identifying disposable emails

Need to block trash email addresses?

DisposableEmailAddressDetectorCommand command = 
  new DisposableEmailAddressDetectorCommand();
DisposableEmailAddressDetectorResult result = 
  executor.execute(command, mode, "blahblah@10minutemail.com").get();
api_key = None  # Set your api_key here
client = NameApiClient(api_key)

email_address="someone@10minutemail.com"
response = client.disposable_email_detector(email_address)
$deaDetector = $serviceFactory->emailServices()->disposableEmailAddressDetector();
$result = $deaDetector->isDisposable("abcdefgh@10minutemail.com");
curl 'https://api.nameapi.org/rest/v5.3/email/disposableemailaddressdetector?apiKey=YOUR_API_KEY&emailAddress=abcdefgh%4010minutemail.com'

Next Step

Integrate a client library, or start from the REST endpoint, and start building.