Tamr Documentation

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 Name

Type

Description

country

string

Required

A field representing the country name to normalize.

Country Code Normalization Output Schema

Attribute Name

Type

Description

country_code

string

The ISO 3166-1 alpha-2 two character country code e.g. GB, US, etc.

Country Code Normalization Examples

Example Input

Example Output

country: United States

country_code: US

country: United Kingdom

country_code: GB

country: USA

country_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 valid ISO 3166-1 alpha-2 two-letter country code (e.g. US) in the country_code field
    • A valid country calling code (e.g. +1) as part of the phone number in the phone_number field.
      Otherwise, the enricher will return valid = false
  • If the country field in your data is not already in ISO 3166-1 alpha-2 format, you can use Tamr’s Country Code Normalization service to normalize country codes.

Phone Validation Input Schema

Attribute Name

Type

Description

phone_number

string

Required

Phone number

country_code

string

Required

SO 3166-1 alpha-2 two-letter country code

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

carrier

string

The original carrier of the phone number

Available for mobile numbers only

Phone Validation Examples

Example Input

Example 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 Name

Type

Description

email

string

Required

Email 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

user

string

The user or local part of the email address

Blank if syntax is invalid

domain

string

The domain of the email address

Blank if syntax is invalid

Email Validation Examples

Example Input

Example Output

email: [email protected]

valid_syntax: true
domain_deliverable: true
user: john.smith
domain: gmail.com

email: [email protected]

valid_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

You may enter either the full address or the individual address components.

Global Address Validation Input Schema

Attribute Name

Type

Description

full_address

string

Required if you do not provide the address components in the address fields

The full address

address_1 - address_4

string

Required if you do not provide the full_address

Street address lines 1-4

city

string

Optional

City

region

string

Optional

Region, state, province, or country

postal_code

string

Optional

Zip or postal code

country

string

Optional

Country name or ISO 3166 2-character country code and ISO 3166 3-character country code

Global Adress 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” or “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_distance

string

The 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 Input

Example 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)