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

News

12.04.2024

Bosnian names: Echoes of Diversity and Heritage

Bosnia and Herzegovina stands out in Europe for its remarkable diversity, being a country where...


29.03.2024

Larger Name Database

We are pleased to announce a new update to our database, which now features a broader range of...


01.03.2024

Diving Deeper into Latin American Names

From the indigenous communities of the Andes to the Afro-Caribbean rhythms of the Caribbean coast,...


16.02.2024

Swagger-UI: The New and Improved Way to Use Our REST API

We are happy to announce that we have added a new feature to our REST API: Swagger-UI, which allows...


09.02.2024

Software Version 10.2.0 Deployed

A software update has been installed on our servers which can handle more personal names and detect...


   

Context

       
The context defining the caller's environment for the execution.
            
All web services (even the simple ping service) use this object as a parameter.
        The context includes:
cultural information such as the geographic region
character sets and character ranges (script, case)
custom properties sent to the server    
       
partially
       
<context><geo>DE</geo><textCase>MIXED</textCase></context>

apiKey

The api-key also known as user-id.
Authentication and accounting is performed on the server for this key.
Do not make this key public unless you have to, for example when used by JavaScript Ajax requests in a website. It's possible to restrict the hosts that are allowed to use this api-key in your admin panel.
Format: The 32 hexa-digits md5 of the base account (such as "9e107d9d372bb6826bd81d3542a419d6") plus the user account specific suffix separated by hyphen, resulting in something like "9e107d9d372bb6826bd81d3542a419d6-defaultuser".
true
<apiKey>9e107d9d372bb6826bd81d3542a419d6-defaultuser</apiKey>

geo

The geographic area from where the request is coming.
This helps the server to better understand and classify the incoming data. Example: the given name "Andrea" is female in Germany but male in Italy.
If the request is made in behalf of another company then the geo may be adjusted to that. However, it is not meant to be set for the target customer. Example: Your company mainly operates in France (FR), and is the service provider for another company in Italy (IT), and the customer used in this web service request happens to be from Austria (AT), then the geo should be set to "IT".
Value: A geographic code such as an ISO-3166 two letter country code, for example "FR" for France.
If the request is made in behalf of another company then the geo may be adjusted to that. However, it is not meant to be set for the target customer. Example: Your company mainly operates in France (FR), and is the service provider for another company in Italy (IT), and the customer used in this web service request happens to be from Austria (AT), then the geo should be set to "IT".
false
<geo>DE</geo>

textCase

Tells in what case of writing (upper, lower ...) the data is in general.
This is not about a single record, it's about all data in general. Most data sources use MIXED case, but some legacy systems still use all UPPER case writings.
            
       

The strings are written with respect to case, for example proper names usually start with an initial upper case.
Data sources that [mostly] use a case-less writing system such as Chinese should use this value too, unless all Latin script (where used) is in single case.
When the data is mostly in mixed case, but for example one record uses all lower case spellings, then this may indicate low data quality for that one record.

       

All data is in lower case only. (It is very unlikely that you need this option.)

       

All data is in upper case only. Such data formats still exist in legacy systems.

       

This really should not be used. You as the developer should know in what format and writing case the data is.

   
false (defaults to UNKNOWN)
<textCase>MIXED</textCase>

properties

Arguments to send to the server.
This is of no use to you unless you received special documentation about its use.
false
(todo: add xml example.)