Quickstart Guide| Global Name

Introduction

Global Name API can be used to:

Recognize over 6,000,000 last names and 4,000,000 first names across different countries and languages.
Split dual names (ex. Mr and Mrs John and Mary Jones)
Assign gender based on known first names and prefixes.
Output preferred output Salutation name parts.

Basic Order of Operations

Create an instance of the request object
Populate the request element CustomerID with your product license key
Add input Names to the “Records” array with anywhere from 1 to 100 records
Call the method and pass in the request to the service using the WEB endpoint for JSON requests
Examine and parse the response from the reply object back from the service
Interpret the result codes

Input Request

NOTE: It expects UTF-8 character encoding. Be on the lookout for question marks (?), squares (▖) or other weird characters like �. They may be an indication of encoding issues and may result in data loss. Bad encoding or character loss is not something our service can correct for you.

Real Time

With a REST request, you can include all the input along with the URL for an easy and quick way of sending a single record.

curl –X GET https://globalName.melissadata.net/V3/WEB/GlobalName/doGlobalName?id=LICENSE_KEY &full=Doktor Enna Schäfer&ctry=DE&t=Global Name CurlExample

You can also put the URL without the "curl -X GET" command directly into your browser. You can also toggle between getting XML or JSON back using the format input parameter. As you can see, in this example, we are asking for JSON back.

Batch

You can send batch requests of up to 100 records per batch that are sent using HTTPS POST. This means you cannot send it in a browser like with HTTPS GET.

Header

The following values are required in the header:

Content-Type: application/json
Accept: application/json

Body

{
  "TransmissionReference":"Global Name Request Test",
  "CustomerID":"LICENSE_KEY_HERE",
  "Options":"",
  "Records":[{
    "RecordID":"1",
    "Company":"",
    “Country”: “US”,
    "FullName":"Mary J Jones"
  },
  {
    "RecordID":"2",
    "Company":"",
    “Country”: “Germany”,
    "FullName":"Doktor Enna Schäfer"
  }]
}

Input Fields

Batch Input REST Input Description REQUIRED

TransmissionReference t This is a string value that serves as a unique identifier for this set of records. It is returned as sent. NO

CustomerID id The License Key issued by Melissa. YES

Options

opt

CorrectFirstName

Code	Description
OFF	Default. Preserve first name spellings; no correction allowed.
ON	Allows first name misspelling corrections.

NameHint

Code	Description
DefinitelyFull	Name will always be treated as normal name order regardless of formatting or punctuation.
Varying	Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order.
DefinitelyInverse	Name will always be treated as inverse name order, regardless of formatting or punctuation.

GenderPopulation

Code	Description
Male	Bias toward male.
Mixed	Default. No bias toward either gender.
Female	Bias toward female.

GenderAggression

Code	Description
Aggressive	Aggressive name genderizing.
Neutral	Default. Neutral name genderizing.
Conservative	Conservative name genderizing.

Salutation

Code	Description
Formal	Default. Contains the name prefix, last name, and suffix. Ex: `Mr. Smith MD`
Informal	Contains the first name. Ex: `John`
FirstLast	Contains the fist name and last name. Ex: `John Smith`
Blank	Returns <blank>. Ex: `<blank>`

Company comp Company name to be standardized (Optional; Required if FullName is not inputted) YES/NO

FullName full Full name to be genderized, standardized, and parsed (Optional; Required if Company is not inputted) YES/NO

Country ctry The Country ISO2, ISO3, or spelled out name. (Optional; default is US) NO

Input Best Practices

Single Record vs Batch Processing

Melissa Data cloud services are capable of both single record real-time processing and batch processing. The difference is simply in the number of records sent in each request. Melissa Data cloud services take an array of records. This array can contain a single record or 100 records. For a real time process like a web form entry or a call center application, send in a request with one record. For batch processing scenario like a database, send requests of up to 100 records until all the records are processed.

Error Handling

Since Melissa Data uses multiple clustered servers, in the unlikely event that one server is temporarily overloaded or down, it is very likely that another server is up and running. For this reason, it is best to catch any errors returned by the service and retry. We recommend retrying up to 5 times.

int Retry = 0;
bool ReqRet = false;
do
{
  try
  {
    // Perform Name doLookup and store results to the Response
    httpGlobalNameResponse = (HttpWebResponse)httpGlobalName_doLookUp.GetResponse();
    ReqRet = true;
  }
  catch (Exception ex)
  {
    MessageBox.Show(ex.ToString());
    Retry++;
  }
} while ((ReqRet == false) && (Retry < 5))

Output Response

JSON Response

Here is a sample response of the real-time request from above.

{
    "Version": "4.0.0.24",
    "TransmissionReference": "GlobalNameWSExample",
    "TransmissionResults": "",
    "TotalRecords": "1",
    "Records": [
        {
            "RecordID": "1",
            "Results": "NS01,NS05,NS06",
            "Company": "",
            "NamePrefix": "Doktor",
            "NameFirst": "Enna",
            "NameMiddle": "",
            "NameLast": "Schäfer",
            "NameSuffix": "",
            "NameNickname": "",
            "NameProfTitle": "",
            "Gender": "U",
            "NamePrefix2": "",
            "NameFirst2": "",
            "NameMiddle2": "",
            "NameLast2": "",
            "NameSuffix2": "",
            "Gender2": "",
            "NameNickname2": "",
            "NameProfTitle2": "",
            "Salutation": "Doktor Schäfer"
        }
    ]
}

JSON Batch Response

Here is a sample response of the batch request.

{
  "Version": "4.0.0.24",
    "TransmissionReference": "GlobalNameWSExample",
    "TransmissionResults": "",
    "TotalRecords": "2",
    "Records": [
        {
            "RecordID": "1",
            "Results": "NS01,NS05,NS06",
            "Company": "",
            "NamePrefix": "",
            "NameFirst": "Mary",
            "NameMiddle": "J",
            "NameLast": "Jones",
            "NameSuffix": "",
            "NameNickname": "",
            "NameProfTitle": "",
            "Gender": "F",
            "NamePrefix2": "",
            "NameFirst2": "",
            "NameMiddle2": "",
            "NameLast2": "",
            "NameSuffix2": "",
            "Gender2": "",
            "NameNickname2": "",
            "NameProfTitle2": "",
            "Salutation": "Mary"
        },
        {
            "RecordID": "2",
            "Results": "NS01,NS05,NS06",
            "Company": "",
            "NamePrefix": "Doktor",
            "NameFirst": "Enna",
            "NameMiddle": "",
            "NameLast": "Schäfer",
            "NameSuffix": "",
            "NameNickname": "",
            "NameProfTitle": "",
            "Gender": "U",
            "NamePrefix2": "",
            "NameFirst2": "",
            "NameMiddle2": "",
            "NameLast2": "",
            "NameSuffix2": "",
            "Gender2": "",
            "NameNickname2": "",
            "NameProfTitle2": "",
            "Salutation": "Doktor Schäfer"
        }
    ]
}

Output Fields

Response (Base Level)

Output Name	Description
`Version`	The current service version
`TransmissionReference`	Optional request identifier
`TransmissionResults`	Service and General Transmission Errors
`Total Records`	The total number of records returned.
`Records`	The returned array of records.

Record Level

Output Name	Description
`RecordID`	A unique identifier for the current record if one was sent in the request. Use this element to match a request record and the corresponding response record.
`Results`	Comma delimited status, error codes, and change codes for the record.
`Company`	The standardized company name.
`NamePrefix`	The first identified prefix from the input full name.
`NameFirst`	The first identified first name from the input full name.
`NameMiddle`	The first identified middle name from the input full name.
`NameLast`	The first identified last from the input full name.
`NameSuffix`	The first identified suffix from the input full name.
`NameNickname`	The first identified nickname from the input full name.
`NameProfTitle`	The first professional title from the input full name.
`Gender`	A one-character string value indicating the gender of the first name from the input.
`NamePrefix2`	The second identified prefix from the input full name.
`NameFirst2`	The second identified first name from the input full name
`NameMiddle2`	The second identified middle name from the input full name.
`NameLast2`	The second identified last from the input full name.
`NameSuffix2`	The second identified suffix from the input full name.
`NameNickname2`	The second identified nickname from the input full name.
`NameProfTitle2`	The second professional title from the input full name.
`Gender2`	A one-character string value indicating the gender of the second name from the input.
`Salutation`	The first identified name properties which you can use to create the desired salutation format.

Interpreting Results

Melissa products use a result code system to indicate data quality; the status and any errors. These result codes are four-character codes (two letters followed by two numbers), delimited by commas. Result code definitions are shared among Melissa products. Instead of looking at multiple properties and methods to determine status, you can look at the output of the results parameter.

Example

This example input: ‘Mr John and Mrs Mary Jones’ will return the result code string:

NS01, NS05, NS06, NS07, NS08

From these Result codes you can determine that the disposition of the Name is:

Code	Description	Recommendation
`NS01`	Name Parsing Successful	Medium
`NS03`	First Name 1 Spelling Corrected	Medium
`NS04`	First Name 2 Spelling Corrected	Medium
`NS05`	First Name 1 Found	Good
`NS06`	Last Name 1 Found	Good
`NS07`	First Name 2 Found	Good
`NS08`	Last Name 2 Found	Good
`NS02`	Error Detected. Check name error codes.	Bad
`NE03`	Vulgar Detected	Bad
`NE04`	Suspicious Word Detected	Bad

For a list of the common transmission errors, see the General Info - Response Level Errors page.

For the full list of all possible result codes, please visit our Result Wiki page at Global Name Result Code Details.