Global Name:Request
(Redirected from Global Name Web Service:Request)
Jump to navigation
Jump to search
Global Name Navigation | |||||||
---|---|---|---|---|---|---|---|
| |||||||
| |||||||
| |||||||
| |||||||
Sample Code |
A request consists of a protocol to make a call detailing desired elements. The minimum required elements in a request are your Customer ID (License Key) and at least a full name or company name.
Global Name supports JSON, JSONP, REST, SOAP, and XML protocols.
URL
REST, XML, JSON, etc.
Header
HTTP headers need to match the protocols and formats being used.
Global Name requires the values of Content-Type
and Accept
.
Example JSON Request Header
{ "Content-Type": "application/json; charset=utf-8", "Accept": "application/json" }
Field Names
This is a list of the request field names and their protocol naming conventions.
Field Name | Level | REST | JSON/XML |
---|---|---|---|
Transmission Reference | Request | t | TransmissionReference |
License Key | id | CustomerID | |
Options | opt | Options | |
Format | format | Format | |
Record ID | Record | RecordID | |
Company | comp | Company | |
Full Name | full | FullName | |
Country | ctry | Country |
Request Elements
The following elements set the basic options for each request. These apply to the entire request, not the individual records.
Transmission Reference
- Optional.
- This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
Protocol Syntax JSON "TransmissionReference":"string"
REST ?t = string
SOAP/XML <TransmissionReference>string</TransmissionReference>
License Key
- Required.
- This is a string value containing the License Key issued to the customer by Melissa Data for Global Name.
- If this element is absent, the Cloud Service will return an error. To receive a License Key, please contact your Melissa Data sales representative at 1-800-MELISSA.
Protocol Syntax JSON "CustomerID":"string"
REST &id = string
SOAP/XML <CustomerID>string</CustomerID>
Options
- Optional.
- This is a string value containing the options set by the user.
Protocol Syntax JSON "Options":"string"
REST ?opt = string
SOAP/XML <Options>string</Options>
- List options in the following format, with multiple options delimited with a ",".
Syntax OptionName:Parameter,OptionName:Parameter
CorrectFirstName
- This option enables or disables spelling correction of first names.
- Global Name uses a database of commonly misspelled first names to correct the values of the First Name properties.
Option Name Parameter Description CorrectFirstName OFF
Default. Preserve first name spellings; no correction allowed. ON
Allows first name misspelling corrections.
NameHint
- This option sets the most likely format of the FullName input string.
- This helps the service in cases where the order and formatting of the FullName input string are unclear.
- Full or normal name order is: <Prefix> <First> <Middle> <Last> <Suffix>.
- Inverse name order is: <Last> <Suffix>, <Prefix> <First> <Middle>.
- Either the Code or Name listed below can be used to set the action.
- For example,
Options = NAMEHINT:4
andOptions = NAMEHINT:Varying
are equivalent settings.
- For example,
Option Name Parameter Code Parameter Name Definition NameHint 1
DefinitelyFull
Name will always be treated as normal name order regardless of formatting or punctuation. 2
VeryLikelyFull
Deprecated. Will resolve to Varying
(Name Hint:4). Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation.3
ProbablyFull
Deprecated. Will resolve to Varying
(Name Hint:4). If necessary, statistical logic will be employed to determine name order, with a bias towards normal name order.4
Varying
Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order. 5
ProbablyInverse
Deprecated. Will resolve to Varying
(Name Hint:4). If necessary, statistical logic will be employed to determine name order, with a bias toward inverse name order.6
VeryLikelyInverse
Deprecated. Will resolve to Varying
(Name Hint:4). Name will be treated as inverse name order unless normal order is clearly indicated by formatting or punctuation.7
DefinitelyInverse
Name will always be treated as inverse name order, regardless of formatting or punctuation. 8
MixedFirstName
Obsolete. Will resolve to Varying
(Name Hint:4). Name element is expected to only contain first names.9
MixedLastName
Obsolete. Will resolve to Varying
(Name Hint:4). Name element is expected to only contain last names.
GenderPopulation
- This option sets the gender balance of the source data, predominantly male, predominantly female, or neutral.
- If you know that the majority of inputted names will be predominantly one gender, meaning that gender-neutral names will likely be of a particular gender, use this property to set the gender bias while genderizing names.
- Either the ‘Code’ or ‘Name’ listed below can be used to set the action.
- For example,
Options = GENDERPOPULATION:3
andOptions = GENDERPOPULATION:Female
are equivalent settings.
- For example,
Option Name Parameter Code Parameter Name Definition GenderPopulation 1
Male
Bias toward male. 2
Mixed
Default. No bias toward either gender. 3
Female
Bias toward female.
GenderAggression
- This option sets how aggressively the service will attempt to genderize neutral first names.
- By default, Global Name will assign a value of “N” when attempting to genderize a first name that can easily be male or female, such as “Taylor,” “Chris,” or “Pat.”
- Using this property in conjunction with the GenderPopulation option, you can instruct the service on how much preference to give one gender over the other when assigning a gender to a normally neutral name.
- Either the ‘Code’ or ‘Name’ listed below can be used to set the action.
- For example,
Options = GENDERAGGRESSION:2
andOptions = GENDERAGGRESSION:Neutral
are equivalent settings.
- For example,
Option Name Parameter Code Parameter Name Definition GenderAggression 1
Aggressive
Aggressive name genderizing. 2
Neutral
Default. Neutral name genderizing. 3
Conservative
Conservative name genderizing.
- The table below shows how the settings for Gender Aggression and Gender Population affect genderizing:
Male Female Aggression Always [7] Often [6] Normally [5] Neutral [4] Normally [3] Often [2] Always [1] Conservative Even M N N N N N F Male M M N N N N F Females M N N N N F F Neutral Even M M N N N F F Male M M M N N F F Females M M N N F F F Aggressive Even M M M N F F F Male M M M M N F F Females M M N F F F F
- Notes on Gender assignment
- Gender values are assigned on the probability of a gender - compiled genders associated with known names.
- Notes on Gender assignment
- For example:
Input Assigned Gender Notes John Smith M John most always represents a male. Pat Smith N Pat is a common male and female name. Mary Smith F Mary most always represents a female. Smith Input doesn't contain data necessary to determine gender. Unknown Smith U Input has tokens where gender is unknown to the service.
MiddleNameLogic
- Deprecated. Middle name logic will be determined by the supplied Country, enabling simultaneous processing of records from different countries.
- This option controls how middle names are handled.
- Some names can be ambiguous with regards to the middle word of a full name. It may be a middle name or it may be the first part of a hyphenated last name, but the hyphen has been omitted for some reason.
- Normally, the service assumes that, in the absence of a hyphen, recognizable last names in the middle of a full name are treated as part of a hyphenated last name. “Mary O’Malley Kelly” is parsed into first name “Mary” and last name “O’Malley-Kelly.”
- On the other hand, “Colleen Marie Sullivan” is parsed into first name “Colleen,” middle name “Marie,” and last name “Sullivan.”
- Either the ‘Code’ or ‘Name’ listed below can be used to set the action.
- For example,
Options = MIDDLENAMELOGIC:0
andOptions = MIDDLENAMELOGIC:ParseLogic
are equivalent settings.
- For example,
Option Name Parameter Code Parameter Name Definition MiddleNameLogic 0
ParseLogic
Default. The service behaves as described above. 1
HyphenatedLast
The middle word is assumed to be part of the last name. “Matthew Edward Jones” is treated as “Matthew Edward-Jones.” 2
MiddleName
The middle word is assumed to be a middle name. for the name “Mary O’Malley Kelly,” O’Malley is assumed to be the middle name.
- When a hyphen is present, the hyphenated word is always treated as the last name, regardless of content.
SalutationOrder
- Optional. This option creates a pipe delimited list of preferred salutation formats and precedence to use when generating salutations. There are five possible formats to use for creating salutations. The options in default order are:
Option Name Parameter Name Definition Example Salutation Formal
Contains name prefix and lastname and suffix Mr. Smith MD
Informal
Contains firstname. John
FirstLast
Contains firstname and lastname. John Smith
Slug
Substitution when desired in SalutationOrder Valued Customer
Blank
<return blank>
<blank>
- For example, if the request is configured as:
opt=Salutation:Formal|FirstLast|Blank|Informal
- This requests a formal salutation to be built where possible but would rather have a blank salutation than an informal salutation (this could replace a blank with a proprietary slug like ‘Valued Customer:’).
SalutationSlug
- Optional. Accepts a string value and sets the text that will be substituted for a name into salutations generated when
salutationOrder:Slug
can be returned.
- Optional. Accepts a string value and sets the text that will be substituted for a name into salutations generated when
Option Name Parameter Name Definition SalutationSlug <your custom slug>
Sets the text for substituting a name in salutations.
- For example:
opt=SalutationSlug:Valued Customer
- Will return 'Dear Valued Customer' when other formats are lower in the salutationOrder
SalutationPrefix
- Optional. This option lets you set the preferred text that you want before the proper name in generated salutations.
Option Name Parameter Name Definition SalutationPrefix <your custom prefix>
Sets the prefix for the salutation name.
- For example:
opt=SalutationPrefix:Dear
- Will return 'Dear John Smith'
SalutationSuffix
- Optional. This option lets you set the preferred text that follows the proper name in salutations generated.
- Use a
_
(underscore) if your suffix requires a space in the response.
Option Name Parameter Name Definition SalutationSuffix <your custom suffix>
Sets the suffix for the salutation name.
- For example:
opt=SalutationSuffix:_and family
- Will return 'John Smith and family'
LegacySalutation (US/CAN only)
- Optional. This option will create a formal (Mr/Mrs) salutation from an assigned FirstName gender for US/CAN.
Option Name Parameter Definition LegacySalutation On
Creates a formal salutation. Off
Default. Will not create a formal salutation.
- For example:
opt=LegacySalutation:On
- Will return 'Mr. John Smith' when the input was 'John Smith'
Format
- Optional.
- The desired format of the response. Possible values for this option are "json" or "xml". The default value is "xml".
Protocol Syntax REST &format = string
Request Record Elements
JSON will only contain the Records element.
Protocol | Definition |
---|---|
JSON | Each name will be contained within [{}] under the Records element. |
REST | The REST interface only allows a single record per request. |
SOAP | This element is an array of object variables of the type RequestRecords. |
XML | There will be one RequestRecord element per address being submitted to the Cloud Service. |
RecordID
- Optional.
- This is a string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. It will return the input.
Protocol Syntax JSON "RecordID":"string"
SOAP/XML <RecordID>string</RecordID>
Company
- Optional. (Required if FullName is not inputted).
- The company name to be standardized.
Protocol Syntax JSON "Company":"string"
REST &comp = string
SOAP/XML <Company>string</Company>
FullName
- Optional. (Required if Company is not inputted).
- The full name to be genderized, standardized, and parsed.
Protocol Syntax JSON "FullName":"string"
REST &full = string
SOAP/XML <FullName>string</FullName>
Country
- Optional. (Default is
US
if not specified).
- The country name, abbreviation, or ISO code of the input name.
Protocol Syntax JSON "Country":"string"
REST &ctry = string
XML <Country>string</Country>