Analyse Requests

The name-analysis service includes the following requests:

/rest/name-analysis/analyse_name?language=language&country=country&par_*&in_*
/rest/name-analysis/verifyname?language=language&country=country&par_*&in_*

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.
de = German
en = English (default)
fr = French

country

Enter the ISO-2-country code for the country.
AT = Austria
BE = Belgium
CH = Switzerland
DE = Germany
ES = Spain
FR = France
IT = Italy
NL = Netherlands

only for verifyname:
SE = Sweden

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.
0 = No further restriction (default)
1 = Town must be preceded by a postcode

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.
0 = No
1 = Only if a known word is generated. Example: Line1 = Tho, Line2 = mas → Thomas is identified as first name. (default)
2 = Yes, always

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.

par_name_lastfirst sets a weighting for the family name preceding the first name.
par_name_firstlast sets a weighting for the first name preceding the family name.

Possible values: 0 - 100
Default: 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.
0 = The spelling is not standardized (default). 1 = Words found in the convert-address dictionary are spelled in the output as specified in the dictionary. 2 = Words found in the convert-address dictionary are abbreviated in the output as specified in the dictionary. If no abbreviation exists, the normal standardized spelling is used.

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). 0 = Parameter has no effect
1 = Convert special characters only if the input does not contain any country-untypical special characters (e.g. é to e in Germany. The conversion of country-untypical special characters is run in the same way as the standardization procedure as a whole. Thus, if par_norm_output=0, the conversion is executed according to the spelling in the input. On the other hand, if par_nomr_output=1 or 2, the conversion is executed according to the standardized spelling in the dictionary.

Example:
If, in Germany, the input contains for instance 'Rene Meier', the spelling remains unchanged. If however the input is 'Rene André Meier', this name is converted to 'René André Meier'
2 = All country-untypical special characters are converted. (è always becomes e).
3 = The only special characters maintained are those already found in the input. Only the upper/lower case spelling is standardized (if par_norm_output = 1 is enabled).

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.
0 = Not to be analysed as separate company
1 = To be analysed as separate company (default)

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.
0 = Not to be analysed as separate person
1 = To be analysed as separate person (default)

par_salutation

Salutation control
0 = The salutation is taken from the input; it is also used to determine the gender.
1 = The salutation is taken from the input if it matches the first name. (default)
2 = Both the salutation and the gender are determined through the first name (where possible).

par_spaced_reduces

Recognition of spaced characters, i.e. the term ’G . m . b . H .’ is for instance identified as ’GmbH’.
Default: 1

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’.
0 = No further restriction
1 = Street must contain house number or street type (default)
2 = Street must contain house number and street type

par_trans_upper_lower

Standardization of output regarding upper/lower case spelling.
blank = Keep spelling (default)
1 = Upper case spelling
2 = 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.
0 = No referencing (default)
1 = Backward referencing (c/o)
2 = Forward referencing (attn.)
3 = Linked (and/or/,)

out_pers1_ref

Further referenced persons.

out_pers1_ref_word

Word used for referencing the person.

out_res_pers1_sex

Gender key.
0 = Not defined
1 = Male
2 = Female

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:
0 = First name known
1 = No first name
2 = First name unknown
3 = Salutation and first name do not match

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.
0 = General family name
1 = Family name known as first name
2 = Family name generated automatically

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:
1st pos.: = Number of persons
2nd pos.:1 = Company name included
3rd pos.:1 = Delivery information included

out_res_sex

Overall gender key
0 = All undefined
1 = 1 man
2 = 1 woman
3 = Several men
4 = Several women
5 = 1 man and 1 woman
6 = 1 man and several women
7 = 1 woman and several men
8 = Undefined and male or female
9 = Company

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
Free fields.

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.
1 = Analysis correct.
2 = Analysis predominantly correct.
3 = Analysis partly incorrect.
5 = Analysis incorrect.

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.
danish
dutch
english
finnish
french
german
italian
lätzebuergesch
norwegian
portugese
spanish
swedisch

in_form_of_address

Salutation.

in_preceding_academic_titles

Preceding academic title. Academic title that precedes the name information.

Example:
'Dr. Max Müller'

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.
Example:
'John Smith Ph. D.'

in_surname_suffixes

Surname suffix.

in_gender

Gender.
male
female
undef (undefined)
N.A. (for organizations)

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:
male
female
undef (undefined)
N.A. (for organizations)

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:
'Dr. Max Müller'

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:
'John Smith Ph. D.'

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": ""
    }
  ]
}