/rest/name-analysis/analyse_name?language=language&country=country&par_*&in_* /rest/name-analysis/verifyname?language=language&country=country&par_*&in_*
Analyse Requests
The name-analysis service includes the following requests:
A name line validation can be done in two different modes: analysis of name lines (analyse_name) or verification and repositioning of the name items (verifyname).
analyse_name
The analyse_name
request can be used to extract and analyse name elements from an address. This particularly applies to the analysis of names of private persons. In special cases, the following elements can also be extracted:
-
Additional special delivery information, e.g. ’1st floor’.
-
Companies (whenever the legal form is separated from the name).
-
Street, postcode and town, provided these entries correspond to typical patterns.
verifyname
The verifyname
request can be used to verify the names of individuals and companies. For this purpose, the following output fields are available:
-
Personal data
-
Extracted company data
For each recognized name, the personal data, such as salutation key, gender, surname, name suffix, etc. will be verified and repositioned, if required.
Request parameters
The configuration parameters
control the processing of the request. The input arguments
describe the individual fields of a data record that is to run through the request.
Output arguments
contain the individual fields of the processed record and do not have to be specified when calling the request.
-
This is an input field
-
This is an output argument
-
This is a configuration parameter
General parameters
Name | Description |
---|---|
language |
Language in which warnings and error messages will be displayed. |
country |
Enter the ISO-2-country code for the country. only for verifyname: |
analyse_name parameters
Name | Description |
---|---|
par_city |
Sets the recognition of towns. Assigning 1 to this parameter reduces the risk of wrongly identifying input elements as town name. |
par_free_field_01 … par_free_field_10 |
Definition of free fields. |
par_linebreaks |
Ignore line breaks? Ignoring the end of line (of input lines) improves the analysis when the parameter is set to 1. If the end of line is always ignored (parameter = 2), the quality of the analysis result can decrease due to the high number of new alternatives. |
par_name_lastfirst, par_name_firstlast |
Weighting of the order of name elements for output. These values are not complementary. Both possibilities are checked for, their quality being influenced by the weighting (by multiplication). Setting one parameter to zero excludes the corresponding possibility.
Possible values: 0 - 100 |
par_norm_output |
Standardization of free fields and output lines regarding the spelling. This parameter is used to standardize the spelling of known words (i.e. found in the dictionary). In addition, the following parameter allows to enable or disable a generalized upper case or lower case spelling. |
par_norm_spec_chars |
This parameter is used to set how country-untypical special characters, i.e. whether they are to be converted or not (e.g. é to e).
Example: |
par_out_bad_line_1 … par_out_bad_line_6 |
These parameters are used to control the handling of the record input lines if the record belongs to the result category 5. It is thus possible to assign the input lines to specific output arguments. For instance, with par_out_bad_line_1=out_company, the input line in_line_1 is assigned to the output argument out_company (provided the result category is 5). |
par_ref_company |
This parameter is used to set whether a referenced company is to be analysed separately. For instance, assuming the input is 'Max Meier in XY GmbH', the company XY GmbH will only be analysed as individual company if the par_ref_company parameter is set to 1. Otherwise, this will be classified as additional information relating to Max Meier. |
par_ref_persons |
This parameter is used to set whether a referenced person is to be analysed separately. For instance, assuming the input is 'Max Meier c/o Jutta Müller‘, Jutta Müller will only be analysed as separate person if the par_ref_persons parameter is set to 1. Otherwise, this will be classified as additional information relating to Max Meier. |
par_salutation |
Salutation control |
par_spaced_reduces |
Recognition of spaced characters, i.e. the term ’G . m . b . H .’ is for instance identified as ’GmbH’. |
par_street |
Sets the recognition of street elements. Assigning either 1 or 2 to this parameter reduces the risk of wrongly identifying input elements as street name. A street type could for instance be ’Straße’, ’Weg’ or ’Gasse’, i.e. for ’Hauptstraße’ the street type is ’Straße’. |
par_trans_upper_lower |
Standardization of output regarding upper/lower case spelling. |
in_line_1 |
First line in the input address |
in_line_2 |
Second line in the input address |
in_line_3 |
Third line in the input address |
in_line_4 |
Fourth line in the input address |
in_line_5 |
Fifth line in the input address |
in_line_6 |
Sixth line in the input address |
out_res_rate |
Reliability of the analysis result. Possible values range from 0 to 100. They can be seen as percentages. |
out_comp_form |
Identified legal form provided the address is a company address. |
out_res_comp_ref |
Company referencing key: 0 = No referencing 1 = Backward referencing, e.g. ’bei’ (c/o, at) |
out_comp_ref |
Further referenced persons, e.g. ’attn. Max Müller’. |
out_comp_ref_word |
Word used for referencing the company, e.g. ’Max Meier in XY GmbH’ ⇒ ’in’. |
out_pers1 |
Information relating to the first person. |
out_res_pers1_ref |
Person referencing key. |
out_pers1_ref |
Further referenced persons. |
out_pers1_ref_word |
Word used for referencing the person. |
out_res_pers1_sex |
Gender key. |
out_pers1_salutation |
Salutation. |
out_pers1_letter |
Letter salutation determined through gender. |
out_pers1_envelope |
Envelope salutation determined through gender. |
out_pers1_title_aca |
Academic title. |
out_pers1_title_nob |
Title of nobility. |
out_pers1_title_oth |
Other titles. |
out_pers1_prof |
Profession/activity. |
out_pers1_first |
First name. |
out_res_pers1_first |
First name key: |
out_pers1_last |
Complete family name. |
out_pers1_last_pref |
Family name prefixes (e.g. ’von’). |
out_pers1_last_main |
Main family name. |
out_pers1_last_suff |
Family name suffix. |
out_res_pers1_last |
Family name key. Example: For ’Max und Eva Meier’, Meier was generated automatically for Max. The arguments out_res_pers1_ref through out_res_pers1_last also apply to any further person, however with using ’pers2’ or ’pers3’ instead of ’pers1’. |
out_company |
Input element identified as company |
out_str_hno |
Input element identified as street |
out_location_add |
Further delivery information identified in the input (e.g. ’1st floor’). |
out_city |
Input element identified as town |
out_zip |
Input element identified as postcode |
out_not_recognized |
Name line elements which cannot be analysed (interruptions marked with ’|’). |
out_res_info |
Three-digit record information: |
out_res_sex |
Overall gender key |
out_salutation |
Salutation created through gender. |
out_letter |
Letter salutation created through gender. |
out_envelope |
Envelope salutation created through gender |
out_free_field_01 |
… out_free_field_10 |
out_int_status |
Internal argument used for troubleshooting only. In case of enquiries at Uniserv, please also send this argument. |
out_res_cname<country-code>_cl |
<country-code> is e.g. d for DE, a for AT etc.
Analysis result categories. |
verifyname parameters
The 'out_res_…' arguments are used to output the evaluation of the respective preceding output field.The system assigns matching points that indicate the degree of matching. The evaluation of such a match is represented by a number between '0' (worst match) and '100' (best match). If the output is a negative value, such as '-100', this means that the corresponding input values are not consistent with the associated fields.
Name | Description |
---|---|
in_language |
Language. |
in_form_of_address |
Salutation. |
in_preceding_academic_titles |
Preceding academic title. Academic title that precedes the name information. Example: |
in_given_names |
Given name. One or more given names. |
in_initials |
Given name initials. |
in_first_surname_noble_titles |
Title of nobility associated with the first surname. |
in_first_surname_prefix |
Prefix of the first surname. |
in_first_surname |
First surname. |
in_second_surname_noble_titles |
Title of nobility associated with the second surname. |
in_second_surname_prefix |
Prefix of the second surname. |
in_second_surname |
Second surname. |
in_succeeding_academic_titles |
Trailing academic title. Academic title appended to the name information. |
in_surname_suffixes |
Surname suffix. |
in_gender |
Gender. |
in_company_names |
Company name. One or more company names. |
in_legal_form |
Legal form. |
out_company_names |
Company name. One or more company names. |
out_first_surname |
First surname. |
out_first_surname_noble_titles |
Title of nobility associated with the first surname. |
out_first_surname_prefix |
Prefix of the first surname. |
out_form_of_address |
Salutation. |
out_gender |
Gender. Possible values: |
out_given_names |
Given name. One or more given names. |
out_initials |
Given name initials. |
out_legal_form |
Legal form. |
out_preceding_academic_titles |
Preceding academic title. Academic title that precedes the name information. Example: |
out_rate |
Total rate. |
out_rate_Info |
Calculation of the total rate. Calculation of the total rate (out_rate argument). This argument may contain information on any repositioning and correction of gender data. |
out_res_company_names |
Evaluation of the company names (out_company_names). |
out_res_first_surname |
Evaluation of the first surname (out_first_surname). |
out_res_first_surname_noble_titles |
Evaluation of the title of nobility associated with the first surname (out_first_surname_noble_titles). |
out_res_first_surname_prefix |
Evaluation of the prefix of the first surname (out_first_surname_prefix). |
out_res_form_of_address |
Evaluation of the salutation. Evaluation of the salutation field (out_form_of_address). |
out_res_gender |
Evaluation of the gender field (out_gender). |
out_res_given_names |
Evaluation of the given names. Evaluation of the given name field (out_given_names). |
out_res_initials |
Evaluation of the given name initials. Evaluation of the initials field (out_initials). |
out_res_legal_form |
Evaluation of the legal form (out_legal_form). |
out_res_preceding_academic_titles |
Evaluation of the preceding academic title (out_preceding_academic_title). |
out_res_second_surname |
Evaluation of the second surname (out_second_surname). |
out_res_second_surname_noble_titles |
Evaluation of the title of nobility associated with the second surname (out_second_surname_noble_titles). |
out_res_second_surname_prefix |
Evaluation of the prefix of the second surname (out_second_surname_prefix). |
out_res_succeeding_academic_titles |
Evaluation of the appended academic title (out_succeeding_academic_title). |
out_res_surname_suffixes |
Evaluation of the surname suffix (out_surname_suffixes). |
out_second_surname |
Second surname. |
out_second_surname_noble_titles |
Title of nobility associated with the second surname. |
out_second_surname_prefix |
Prefix of the second surname. |
out_succeeding_academic_titles |
Trailing academic title. Academic title appended to the name information. Example: |
out_surname_suffixes |
Surname suffix. |
Running a Request
Most parameters and input arguments are optional. If you omit them, they either use the default value or they are ignored.
The request will return the following two objects:
-
info The info object may contain warnings, e.g. if an invalid parameter was passed.
-
content The content object contains the output arguments.
Sample Request
GET /rest/name-analysis/analyse-name?language=de&in_line_1=DR.%20angela%20merkel
Sample Response
{
"info": [
{
"level": "OK",
"code": 0,
"description": "",
"count": 1,
"durationInMs": 83
}
],
"content": [
{
"out_city": "",
"out_comp_form": "",
"out_comp_ref": "",
"out_comp_ref_word": "",
"out_company": "",
"out_envelope": "An",
"out_free_field_01": "Frau DR. angela merkel",
"out_letter": "Sehr geehrte",
"out_location_add": "",
"out_not_recognized": "",
"out_pers1": "DR. angela merkel",
"out_pers1_envelope": "An",
"out_pers1_first": "angela",
"out_pers1_func": "",
"out_pers1_last": "merkel",
"out_pers1_last1": "",
"out_pers1_last2": "",
"out_pers1_last_main": "merkel",
"out_pers1_last_pref": "",
"out_pers1_last_suff": "",
"out_pers1_letter": "Sehr geehrte",
"out_pers1_prof": "",
"out_pers1_ref": "",
"out_pers1_ref_word": "",
"out_pers1_salutation": "Frau",
"out_pers1_title_aca": "DR.",
"out_res_cname_d_cl": "1",
"out_res_comp_ref": "0",
"out_res_info": "100",
"out_res_pers1_first": "0",
"out_res_pers1_last": "0",
"out_res_pers1_ref": "0",
"out_res_pers1_sex": "2",
"out_res_pers2_first": "",
"out_res_pers2_last": "",
"out_res_pers2_ref": "",
"out_res_pers2_sex": "",
"out_res_pers3_first": "",
"out_res_pers3_last": "",
"out_res_pers3_ref": "",
"out_res_pers3_sex": "",
"out_res_rate": "95",
"out_res_sex": "2",
"out_salutation": "Frau",
"out_status": "",
"out_str_hno": "",
"out_zip": ""
}
]
}