User GuidesAPI ReferenceRelease Notes
Doc HomeHelp CenterLog In

Tamr Enrichment Services

Tamr provides the following enrichment services:

Country Code Normalization

Use the country code normalizer to normalize the country field in your data to the ISO 3166-1 alpha-2 two character country code.

Country Code Normalization Considerations

Country code normalization must be performed prior to phone number validation.

Country Code Normalization Input Schema

Attribute NameTypeDescription
countrystringRequiredA field representing the country name to normalize.

Country Code Normalization Output Schema

Attribute NameTypeDescription
country_codestringThe ISO 3166-1 alpha-2 two character country code, for example: GB, US, and so on.

Country Code Normalization Examples

Example InputExample Output
country: United Statescountry_code: US
country: United Kingdomcountry_code: GB
country: USAcountry_code: US

Phone Validation

Use the phone validation enrichment service to:

  • Validate phone numbers against National Number Plans from ITU and other public data sets.
  • Standardize valid phone numbers into standard international or local format.
  • Enrich phone numbers with type, carrier and region, if available.

Phone Validation Considerations

The input data must contain either:

  • A country name
  • A valid country calling code (for example +1) as part of the phone number in the phone_number field.

Otherwise, the enricher will return valid = false.

Phone Validation Input Schema

Attribute NameTypeDescription
phone_numberstringRequiredPhone number
countrystringRequiredCountry name (for example: United States, U.S., and so on)

Phone Validation Output Schema

Attribute Name

Type

Description

valid

boolean

True if format is valid.

False if format is not valid.

country_code

string

The country calling code

cleaned_number

string

The number returned in the national_format field, without formatting

national_format

string

Phone number standardized to the national format

international_format

string

Phone number standardized to the international format, including country code

region

string

The region for the phone number

type

string

The phone number type

Values:

  • Fixed line
  • Mobile
  • Fixed line or mobile
  • Toll free
  • Premium rate
  • Shared cost
  • VOIP
  • Personal number
  • Pager
  • Universal access number
  • Voicemail
  • Unknown
carrierstringThe original carrier of the phone numberAvailable for mobile numbers only

Phone Validation Examples

Example InputExample Output
phone_number: 339 321 2857
country_code: US
valid: true
country_code: 1
cleaned_number: 3393212857
national_format: (339) 321-2857
international_format: +1 339-321-2857
region: Massachusetts
type: Fixed Line or Mobile
carrier:
phone_number: +1 139 0829 3163
country_code:
valid: false
country_code:
cleaned_number:
national_format:
international_format:
region:
type:
carrier:
phone_number: +44 2037 972801
country_code:
valid: true
country_code: 44
cleaned_number: 7973451763
national_format: 07973 451763
international_format: +44 7973 451763
region: United Kingdom
type: Mobile
carrier: Orange

Email Validation

Use the email validation enrichment service to:

  • Check that the syntax of the email address is valid according to the definitions in RFC 5321 and RFC 5322 (except for certain exceptions, see considerations below).
  • Check whether email can be delivered to the domain of the email address over the public internet.
  • Extract the components of the email address, including the local part or user and the domain. Extracting the domain of an email address can be useful for certain mastering use cases, for example determining the organization in which a person works.

Email Validation Considerations

  • Email addresses where the local part contains quotes or the domain is an IP address are not considered valid. Although these addresses are officially allowed according to the RFC definitions, these types of email addresses are not used in practice.
  • If a timeout is reached before domain deliverability is determined, the value for domain_deliverability is `Unknown1.

Email Validation Input Schema

Attribute NameTypeDescription
emailstringRequiredEmail address

Email Validation Output Schema

Attribute Name

Type

Description

valid_syntax

boolean

True if format is valid

False if format is not valid

domain_deliverable

string

If syntax is valid:

  • True if domain is deliverable
  • False if domain is not deliverable

Blank if syntax is invalid

userstringThe user or local part of the email addressBlank if syntax is invalid
domainstringThe domain of the email addressBlank if syntax is invalid

Email Validation Examples

Example InputExample Output
email: [email protected]valid_syntax: true
domain_deliverable: true
user: john.smith
domain: gmail.com
email: john.smith@gmailvalid_syntax: false
domain_deliverable:
user:
domain
email: [email protected]valid_syntax: true
domain_deliverable: false
user: tom
domain: undeliverable-example.com

Global Address Validation

Use the global address validation enrichment service to:

  • Standardize valid global addresses into standard international or local format.
  • Enrich addresses with latitude, longitude, and detailed address information.

Global Address Validation Considerations

  • Note: Make sure you map an input attribute to the country attribute and do not leave it blank, as this data is necessary for quality results.
  • You may enter either the full address or the individual address components.

Global Address Validation Input Schema

Attribute NameTypeDescription
full_addressstringRequired if you do not provide the address components in the address fields.The full address
address_1 - address_4stringRequired if you do not provide the full_address.Street address lines 1-4
citystringOptionalCity
regionstringOptionalRegion, state, province, or country.
postal_codestringOptionalZip or postal code
country*stringRequiredCountry name or ISO 3166 2-character country code and ISO 3166 3-character country code.

Global Address Validation Output Schema

Attribute Name

Type

Description

verification_status

string

Full address, correctly formatted for mailing in the relevant country.

match_level

string

The post-processed verification match level. Provides the level to which the input data matches the available reference data once all changes and additions performed during the verification process have been taken into account.

Possible values include:

  • Delivery Point (PostBox or SubBuilding)
  • Premise (Premise or Building)
  • Thoroughfare
  • Locality or PostalCode
  • AdministrativeArea
  • None

avc

string

The accuracy code, which is comprised of the following values:

  • Verification status
  • Post-processed verification match level
  • Pre-processed verification match level
  • Parsing status
  • Lexicon identification match level
  • Context identification match level
  • Postcode status
  • Matchscore

See additional documentation for more information about this code.

sub_building

string

The secondary identifiers for a particular delivery point.

For example:
FLAT 1
SUITE 212.

Blank if secondary identifiers are not available.

premise

string

The alphanumeric code identifying an individual location.

Blank if a code is not available.

building

string

The descriptive name identifying an individual location.

Blank if the descriptive name is not available.

post_box

string

The post box for a delivery point.

Blank if a post box is not available.

dependent_thoroughfare

string

The most common street or block data element within a country.

For example:
BUILDING NAME 1A
DEPENDANT
THOROUGHFARE SEASTONE COURT
THOROUGHFARE STATION ROAD
POST TOWN HOLT
POST CODE NR25 7HG

thoroughfare

string

The most common street or block data element within a country.

For example: USA Street

double_dependent_locality

string

The smallest population center data element, dependent on both the contents of the locality and dependent_locality fields.

For example: UK Village

dependent_locality

string

A smaller population center data element, dependent on the contents of the locality field.

For example: Turkish Neighborhood

locality

string

The most common population center data element within a country.

For example:
USA City
Canadian Municipality

sub_administrative_area

string

The smallest geographic data element within a country.

For example: USA County

administrative_area

string

The most common geographic data element within a country.

For example:
USA State
Canadian Province

super_administrative_area

string

The largest geographic data element within a country.

For example, for a Madrid locality: Comunidad De Madrid

postal_code

string

The complete postal code for a particular delivery point.

Blank if postal code cannot be determined.

postal_code_primary

string

The primary postal code used for a particular country.

For example:
USA Zip
Canadian Postcode
Indian PINcode

postal_code_secondary

string

Secondary postal code information, if it is used in a particular country, if the code can be determined, and if reference data is available.

For example: USA Zip Plus 4

Blank otherwise

country_name

string

The ISO 3166 official country name.

iso3166-2

string

The ISO 3166 2-character country code.

iso3166-3

string

The ISO 3166 3-character country code.

iso3166-n

string

The ISO 3166 3-digit numeric country code.

address

string

The full address, correctly formatted for mailing in the relevant country, including line breaks specified by a comma.

address 1 - address8

string

Lines 1-8 of the address for mailing.

Blank if not available.

delivery_address

string

The full address correctly formatted for mailing in the relevant country, including line breaks specified using the AddressLineSeparator option, without the following:

  • Organization
  • Locality
  • AdministrativeArea hierarchy
  • PostalCode hierarchy

delivery_address1 - delivery_address8

string

Lines 1-8 of the address for delivery.

Blank if not available.

latitude

string

The WGS 84 latitude in decimal degrees format.

longitude

string

The WGS 84 longitude in decimal degrees format.

geo_accuracy

string

The GeoAccuracy code, comprised of the following values:

  • Geocoding status
  • Geocoding level

See additional documentation for more information about this code.

geo_distancestringThe radius of accuracy in meters, giving an indication of the likely maximum distance between the given geocode and the physical location.This field is derived from, and therefore dependent on, the accuracy and coverage of the underlying reference data.

Global Address Validation Examples

Example InputExample Output
full_address:
address_1: 1 Fore Street Avenue
address_2:
address_3:
city: London
region:
postal_code: EC2Y 9DT
country: United Kingdom
verification_status: Partially Verified
match_level: Premise (Premise or Building)
avc: P44-I44-P6-100
sub_building:
premise: 1
building:
post_box:
dependent_throughfare:
thoroughfare: Fore Street Avenue
double_dependent_locality:
dependent_locality:
locality: London
sub_administrative_area:
administrative_area: London
super_administrative_area:
postal_code: EC2Y 9DT
postal_code_primary: EC2Y 9DT
postal_code_secondary:
country_name: United Kingdom
iso3166-2: GB
iso3166-3: GBR
iso3166-n: 826
address: 1 Fore Street AvenueLondonEC2Y 9DT
address1: 1 Fore Street Avenue
address2: London
address3: EC2Y 9DT
address4:
address5:
address6:
address7:
address8:
delivery_address: 1 Fore Street Avenue
delivery_address1: 1 Fore Street Avenue
delivery_address2:
delivery_address3:
delivery_address4:
delivery_address5:
delivery_address6:
delivery_address7:
delivery_address8:
latitude: 51.518100
longitude: -0.089470
geo_accuracy: P4
geo_distance: 0.0
full_address:
address_1: Borsigalee 26
address_2:
verification_status: Verified
match_level: Premise (Premise or Building)

Address Format Validation

Note: Global Address Validation contains advanced features not present in Address Format Validation including: advanced standardization and validation, and geocoding.

Use the address format validation enricher to:

  • Check if an address is missing any required fields for that country.
    Example: State is a required field for the US; if it is not present, then state is listed as a missing field.
  • Check if a field is invalid.
    Example: XX is not a valid state for the US.
  • Standardize common components of an address.
    Example: St → Street.
  • Standardize country names to 2 character codes.
    Example: United States → US.

Address Format Validation Considerations

  • valid_address_format will be false if there are missing or invalid fields.

Note: Make sure the country attribute is filled: neither null or empty.

Address Format Validation Input Schema

Attribute nameTypeDescription
address_line_1*stringRequiredStreet address line 1
address_line_2stringOptionalStreet address line 2
citystringOptionalCity
regionstringOptionalRegion, state, province, or county
postal_codestringOptionalZip or postal code
country*stringRequiredThe country name,, for example, United States, US, and so on.

Address Format Validation Output Schema

Field NameTypeDescription
valid_address_formatbooleanTrue if format is valid; False otherwise.
missing_fieldsstringA list of the fields that are missing based on the required fields for the country specified in the country_code field. If the country_code is invalid, missing_fields will be empty.
invalid_fieldsstringMessage explaining why address is invalid. No error if address is valid. If the country_code is invalid, only country_code will be listed here.
standardized_address_line_1stringStandardized street address line 1.
standardized_address_line_2stringStandardized street address line 2.
standardized_citystringCity.
standardized_regionstringRegion, state, province, or county.
standardized_postal_codestringZip or postal code.
standardized_countrystringISO 3166 2-character country code.

Address Format Validation Example

Example InputExample Output
address_line_1: 47 Lee St
region: ma
postal_code: 02139
country: United States
valid_address_format: false
missing_fields: city
invalid_fields:
standardized_address_line_1: 47 LEE STREET
standardized_address_line_2:
standardized_city:
standardized_region: MA
standardized_postal_code: 02139
standardized_country: US