Returns 1-n usages for that address or absent if #isUsageForAll returns true.

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.

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 place 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 place should be set to "IT".

Technical note: when the system needs a Locale it uses the place with the language.

If not provided, and {@link #place} is available, the primary language for that place is used.

Value: A language code such as an ISO-639-1 two letter code, for example "fr" for French.

Technical note: when the system needs a Locale it uses the place with the language.

One code starts with the ISO 15924 script name, optionally followed by the ISO 639-1 or ISO 639-3 language code.

Examples: "Latn:de", "Latn:gsw", "Cyrl:ru".

Multiple writing systems may be used, for example "Cyrl:sr" plus "Latn:sr".

The special non-standard script name "Asci" is used for the us-ascii character set.

This hint helps the server to match terms with its databases, and generate better results. Also, the user may be warned when accidentally using characters not in his range, for example when a Cyrillic character slipped into his Latin customer database (which may be visually indistinguishable).

Arguments to send to the server. There are a few public properties. And custom properties may be created for customers to customize server behavior for their needs.

Tells what kind of risk was detected.

Risk types:

• FakeRiskType - classification of fake risks. In some situations the exact classification is difficult. For example a person's name may be from fiction, but also be famous at the same time. See https://goo.gl/2dFKhy
• DisguiseRiskType - classification of disguise risks. Such mangled input is used to circumvent machine processing. Humans can still understand these modified values, but machines can't unless they detect the patterns and clean the input. See https://goo.gl/zw1kt1

The values are organized by culture. The name types that are often used in the USA are in the AmericanNameFieldType}, and so on. Certain values appear in multiple but their meaning is the same.

Name field types:

• AmericanNameFieldType - Contains the name field types that are often used in America. See https://goo.gl/WP85x8
• ArabicNameFieldType - The traditional name fields of the Arabic culture. See https://goo.gl/cgH7gw
• CommonNameFieldType - Contains the name field types that are commonly shared by many cultures. See https://goo.gl/eKR6Em
• LegalNameFieldType - Contains the field types that are used by organizations. See https://goo.gl/uY2zwQ
• OtherNameFieldType - A place for "other" types that don't fit into Common and are not too culture specific. See https://goo.gl/Gt7cZg
• WesternNameFieldType - Currently no values here, they all fit into CommonNameFieldType.

ISO-639 code of the language. Either 639-1 or 639-3, for example "it" or "ita" for Italian.

Usage: In combination with the Context.place it helps the services to better classify the culture of the person.

Invalid input: The behavior on illegal input depends on the web service that is called. It may ignore it, or throw an invalid input exception.

Multiple addresses may be added.

Usage: Depends on the service. A data validator service may check for problems such as illegal syntax or inexistent domain. A service may check for disposable email addresses. It may be used to extract name information. A validator service may compare the name in the email address with the person's name.

Invalid input: The behavior on illegal input depends on the web service that is called. A validator service may report problems with invalid email address syntax, or inexistent domain names, etc. Services may throw an invalid input exception.

Multiple numbers may be added.

Usage: Depends on the service. A data validator service may check for problems. A fake checker may look for suspicious input.

Invalid input: The behavior on illegal input depends on the web service that is called. A validator service may report problems with an address. Other services mostly just ignore invalid phone data as it is not their task to validate, and the information is just helping to better understand the input and is not essential.

Multiple addresses may be passed (domicile, mailing/delivery address, ...) or a single address may be responsible for all purposes.

Usage: Depends on the service. A validator service may check for valid addresses, and report problems (such as invalid zip codes). A genderizer service may use it to better classify the names.

Invalid input: The behavior on illegal input depends on the web service that is called. A validator service may report problems with an address. Other services mostly just ignore invalid address data as it is not their task to validate, and the information is just helping to better understand the input and is not essential.

Usage: Depends on the service. A validator service may check for valid dates, and report problems (such as 1986-02-31). A genderizer service may use it to filter irrelevant birth statistics.

Invalid input: The behavior on illegal input depends on the web service that is called. Invalid (xml) input such as a non-numeric string should always result in an illegal input exception. An invalid date such as 1986-02-31 may trigger an illegal input exception, or it may just be ignored.

The field type, a common interface for the enum values.

The gender of the person. This is how common database applications usually store the gender for a person.

Defines the person's marital status.

The nationalities eg [DE,FR] in upper case, or null if the info is not available. The method should not return an empty collection in case the nationality of a person is unknown. There are few people without nationality, but they exist, and that would be the correct case for an empty collection.

The mother tongue(s), or null if the information is not available. The method should not return an empty collection in case the mother tongue of a person is unknown. There are not too many people without any mother tongue, but it exists, and then that would be the correct case for an empty collection.

The country code or name in any language.

• "DE" Germany (ISO 3166-alpha2 code)
• "Germany"
• "U.S.A."

The region or region code (state, county, province), such as "CA" in the USA for California.

• "CA" for California USA
• "Jud. Brasov" in Romania

Returns the locality and postal code, in any order.

Whether the postal code or the locality comes first depends on stuff. How it's entered, how it's common for the country, etc.

When the data is available separate in #getLocality and #getPostalCode then this method here returns a combination of those. The implementation is advised to concatenate the values in a format which is suitable for the customs. For example a specialized GermanAddress would append the locality after the postal code, separated by a space.

The city area/neighborhood/district/sector information.

• "Vila Industrial" in Brazil
• "Sector 6" in Romania, only used in the capital Bucharest

The postal code should not be prefixed with a country code that is not part of the postal code itself, such as an ISO 3166-1 alpha-2 code. Example: "FR-71320" or "F-71320". If possible then the country code should be dropped. The ISO 31-66-1 alpha-2 maybe directly used as the {@link #getCountry country} instead.

• "94107" USA
• "H3Z 2Y7" Canada
• "8022" Switzerland
• "CH-8022" Switzerland, european style of adding country code as prefix

An overall score considering all the detected risks and all the positive attributes of the record.

Range [-1,1] where:

• [-1,0) means no risks were detected and the record looks good.
• 0 means no risks were detected, but also no positive attributes were found, the service can't tell for sure.
• (0,1] means one or multiple risks were detected.

Impl where the whole street/house etc information is in plaintext form in a single line and needs to be parsed to extract information.

It contains at least a street name, but may contain all other kinds of information also such as apartment/suite etc.

Returns the complete number in any format. This is the minimal required api for all implementations.

Implementations may provide additional getters for information such as:

• type of number (phone, fax, mobile, fixed, ...)
• separate country code, area code and number