Worldview Data Quality Capabilities
HIERARCHY REQUIRED FIELDING
Hierarchy of the service
The current release of the web service consists of the following implemented hierarchy/structure for a request:
<validate>
<input>
<address>
<credentials>
<email>
<identity>
<phone>
In order to assemble a request for the service you must provide credentials and populate one of the input elements requesting a specific service. By default, the global data quality features are always enabled, but these features can be disabled for individual web service calls with the options like DisableDQChecks which are discussed later in this document.
Address Verification and Geocoding
The current release has limited country detection enabled so it is advised that whenever possible each call contains either the ISO2, ISO3 or country name to be assured of accurate country classification and utilization of the best reference data and results service.
Data Quality Implementation
Like Address Verification and Validation described above, similar validation checks can be applied to a Name, an Email and a Phone Number.
The example code snippets below are utilize .NET and visual basic via SOAP, the resulting code for other structures and transports (JSON, REST) would have similar structures.
Creating the objects
Dim gdcinp As New wvprod.gdcInput 'Allows for input into the service
Dim phone2 As New wvprod.phone 'Allows for direct reference to phone portion of the API
Dim email2 As New wvprod.email 'Allows for direct reference to phone portion of the API
Dim contact2 As New wvprod.identity 'Allows for direct reference to phone portion of the API
Dim avsResult As wvprod.gdcResult ‘ Provides reference to results
Access to all services of the Worldview API are from the same web service endpoint. So the web reference mentioned in the example related to address quality and identity is still valid.
Setting parameters
First get a “live” reference to the relevant section of the web service.
gdcinp.identity = contact2 ‘ contact2 is an instantiation of the identity section
gdcinp.phone = phone2 ‘ phone2 is an instantiation of the phone section
gdcinp.email = email2 ‘ email2 is an instantiation of the email section
Then package up the inputs for processes. Keep in mind only the true identity checks require options (IdentityVerify, etc.) the service assumes if you pass a name, email, or phone and have access to process these inputs you want data quality validation. To disable these checks you can pass the option DisableDQChecks and the data provided will be passed through without data quality processing.
gdcinp.phone.phone_number = “19193496087”
gdcinp.phone.calling_code = “US”
gdcinp.phone.calling_from = “US”
gdcinp.email.full_email_address = “help@globaldataconsortium.com”
gdcinp.phone.countryCode = “US”
gdcinp.email.countryCode = “US”
gdcinp.options = "" & “uppercase”
Making the request
Once the parameters are set then simply make the validate call assigning the results to a GDC result object.
'= Now make validation call
avsResult = avsEngine.validate(gdcinp)
'= Then pull result values (complete name) from the returned object.
avsResult.identity.completename
Examples of each SOAP request and response are found in the Appendix 6 and more sample code is available as needed. Simply send a request to help@globaldataconsortium.com.
Name, Email, and Phone Data Quality Examples
DQ Name
Use this service to:
- Convert person names to specified format
- Correctly capitalize person names and company names
- Generate correct diacritics in a name (diacritics are accents, circumflexes, etc.)
- Check if a person name exists (validate names)
- Abbreviate person names and company names
- Divide person names and company names over a specified number of lines
- Check for suspect name usage (e.g. Mickey Mouse and James Bond)
DQ Name is the default configuration.
DQ Name Sample Request
<completename>Aaron Castillo</completename>
<countryCode>MX</countryCode>
DQ Name Sample Response:
<identity>
<adaptation>30</adaptation>
<detailCode>WS-2396175.2014.2.3.17.12.1.270</detailCode>
<options>None</options>
<lt;reliability>10</reliability>
<completename>Aaron Castillo</completename>
<contact_type>Person</contact_type>
<countryCode>MX</countryCode>
<gender>Male</gender>
<givenfullname>Aaron</givenfullname>
<surname_first>Castillo</surname_first>
</identity>
DQ Email
Use this service to:
- Check if an email address is formatted correctly
- Check if the domain in the email address exists
- Show suggestions for valid and/or invalid domains
- Access the validity of the email address
DQ Email is the default configuration.
DQ Email Sample Request:
<full_email_address>michaeljackson@gmail.com</full_email_address>
<countryCode>US</countryCode>
DQ Email Sample Response:
<email>
<addressee>michaeljackson</addressee>
<adaptation>30</adaptation>
<detailCode>WS-2396175.2014.2.3.17.12.1.270</detailCode>
<code>VALIDSYNTAX</code>
<value>Valid syntax of email</value>
<code>VALID</code>
<value>Valid domain</value>
<reliability>30</reliability>
<domain>gmail.com</domain>
<full_email_address>michaeljackson@gmail.com</full_email_address>
<top_level>com</top_level>
</email>
DQ Phone
Use this service to:
- Check if an (international) telephone number is valid and the status of the phone number (e.g. Live, Dead). Verifies if a phone number complies with country specific requirements with respect to formatting and other country specific issues
- Obtain information about the phone number type. For example, mobile, free phone, fixed or premium rate
- Decompose a phone number into logical parts. For example, international access code with country code, area code and subscriber number
- Format the phone number according to the country you want to call from
Additional Notes regarding DQ Phone
Country code - The country of the telephone number. A country code (ISO 3166-alpha-2 code) indicating for which country a phone number has been provided. The need to fill this field depends on the format of the phone number that has been provided. (Required Field)
Calling form country - A country code (ISO 3166-alpha-2 code) indication in which country you are. Optional field that can be used to generate the international call prefix and for formatting the phone number. (Required Field)
DQ Phone Sample Request:
<phone_number>1 (416) 225-2598</phone_number>
<countryCode>US</countryCode>
<calling_from>US</calling_from>
DQ Phone Sample Response:
<phone>
<area_code>1416</area_code>
<calling_code>1</calling_code>
<calling_from/>US</calling_from/>
<adaptation>30</adaptation>
<detailCode>WS-2396175.2014.2.3.17.12.1.270</detailCode>
<code>100</code>
<value>Phone Number is valid</value>
<code>102</code>
<value>Phone Number doesn't match country code in input</value>
<reliability>30</reliability>
<line_type>FIXED_LINE_OR_MOBILE</line_type>
<number>2252598</number>
<phone_number>1 (416) 225-2598</phone_number>
<timezone/>
<trunk/>
</phone>
Understanding Results
Address Results
The example address, 123 W Cornwall Rd Cary NC 27607 USA, produces the result codes and messages in the XML below.
<codes>
<adaptation>10</adaptation>
<detailCode>WS458845.2015.8.16.14.33.29.791</detailCode>
<detail_list/>
<messages>
<code>codes</code>
<value>25;messages;</value>
</messages>
<messages>
<code>PROCESS_CODE</code>
<value>VERIFIED</value>
</messages>
<messages>
<code>mail_code</code>
<value>5</value>
</messages>
<messages>
<code>mail_msg</code>
<value>Completely Confident</value>
</messages>
<messages>
<code>25</code>
<value>ZIP changed</value>
</messages>
<messages>
<code>PROCESS_MSG</code>
<value>RESULT VERIFIED ACCORDING TO DEFINED RULES</value>
</messages>
<options></options>
<reliability>10</reliability>
</codes>
Result Process Codes and Statuses
The Worldview platform includes additional high-level address processing codes and messages. These values are returned in the codes and messages section of the results and are denoted as PROCESS_CODE and PROCESS_MSG. The table below is a list of codes and messages for address verification services.
| Worldview Process Code | Worldview Process Message |
|---|---|
| VERIFIED | RESULT VERIFIED ACCORDING TO DEFINED RULES |
| PARTIALLY VERIFIED | RESULT PARTIALLY VERIFIED ACCORDING TO DEFINED RULES |
| MANUAL | RESULT NOT VERIFIED ACCORDING TO DEFINED RULES. REQUIRES MANUAL REVIEW. |
| CORRECTED | RESULT CORRECTED ACCORDING TO DEFINED RULES |
| PARTIALLY CORRECTED | RESULT PARTIALLY CORRECTED ACCORDING TO DEFINED RULES |
Mail-Score Codes and Messages
This release of the Worldview platform includes high-level mail-score codes and messages. These values are returned in the codes and messages section of the results and are denoted as mail_code and mail_msg. The table below is a list of codes and messages for address verification services.
| Worldview Mail-Score Code | Worldview Mail-Score Description |
|---|---|
| 5 | Completely Confident |
| 4 | Almost Certain |
| 3 | Should be Fine |
| 2 | Fair Chance |
| 1 | Futile |
Reliability Codes represent a scoring system designed to be easy to understand and implement/decision.
<reliability>10</reliability>
| Reliability | Description |
|---|---|
| 10 | (Good/Correct/Corrected) |
| 20 | (Questionable/Possible/Probable) |
| 30 | (Not Correct/Results not complete enough) |
The WV team recommends the customer analyze the messages and <errCodes> for all return values for extra information. The error codes and messages can be found in the interactive help with-in the portal.
Adaptability codes represent the measure of change regarding the reliability code.
<adaptation>10</adaptation>
| Adaptation | Description |
|---|---|
| 0 | No Change |
| 10 | Very minor adjustment such as capitalization or casing for standardization. |
| 20 | Substantial change which appears to have had a minor impact on the reliability – such as correction of spelling or address formatting, and minor address data changes. Example append of +4 top US Postal code. |
| 30 | Substantial change which appears to have had a minor impact on the reliability – appending of missing address data or change of address elements. |
Note: Adaptability is mainly a function of address verification and enrichment.
Information regarding the specific changes is also available in the <errCodes> and messages return values.
Utilize the combination of both reliability and adaptation codes and messages to interpret results. A table below gives case examples:
| Adaptation | Reliability | Description |
|---|---|---|
| 30 | 10 | Major changes (30) we were able to improve the reliability to a 10 |
| 20 | 20 | With significant changes (20) we were only able to slightly improve (20) |
| 30 | 20 | Even with major changes (30) we were able to improve the reliability to a 20, but there is some review which should be considered |
The coding scheme is designed to allow for easy initial and efficient decision-ing on data quality and identity. Coding Messages are also provided describing specific changes in common language – Postal Code Enhanced.
Detail Codes and Detail Results provide access to detailed information on the processing results from the local provider.
Global Address Verification Field Messages
Certain status messages are provided by Worldview for every address result. The are found in the table below. The subsequent tables provide country and provider specific messages that may contain additional detail. Since this document is updated on a quarterly basis, not all messages may be found in the tables. Please contact help@globaldataconsortium.com with any questions regarding the latest messages.
Address Messages – Worldwide
| Status Code | Status Message |
|---|---|
| Reliability Codes and Messages | |
| R1 | The record has been verified by the provider as correct. |
| R2 | The record has been verified by the provider as possible/questionable. |
| R3 | The record has been verified by the provider as not correct/bad. |
| Adaptation Codes and Messages | |
| A1 | Minor changes made to the input address. |
| A2 | Significant changes made to the input address. |
| A3 | Major changes made to the input address. |
| MP | (Matched Province/Administration) Full match was made to Province/Administration on input |
| CP | Changed Province/Administration) Could not match resulting Province/Administration with input field specified. |
| EP | (Enhanced Province/Administration) Partial match/enhanced Province/Administration related input data |
| ML | Matched Locality) Full match was made to Locality on input |
| CL | (Changed Locality) Could not match resulting Locality with input field specified. |
| EL | (Enhanced Locality) Partial match/enhanced Locality related input data |
| MD | (Matched District) Full match was made to District on input |
| CD | (Changed District) Could not match resulting District with input field specified. |
| ED | (Enhanced District) Partial match/enhanced District related input data |
| MT | (Matched Thoroughfare/Street) Full match was made to Thoroughfare/Street on input |
| CT | (Changed Thoroughfare/Street) Could not match resulting Thoroughfare/Street with input field specified. |
| ET | (Enhanced Thoroughfare/Street) Partial match/enhanced Thoroughfare/Street related input data |
| MHA | (Matched House number Additional) Full match was made to House number Additional on input |
| CHA | (Changed House number Additional) Could not match resulting House number Additional with input field specified. |
| EHA | (Enhanced House number Additional) Partial match/enhanced House number Additional related input data |
| MPC | (Matched Postal Code) Full match was made to Postal Code on input |
| CPC | (Changed Postal Code) Could not match resulting Postal code with input field specified. |
| EPC | (Enhanced Postal Code) Partial match/enhanced Postal code related input data |
| MHN | (Matched House number) Full match was made to House number on input |
| CHN | (Changed House number) Could not match resulting House number with input field specified. |
| EHN | (Enhanced House) Partial match/enhanced House number related input data |
Address Validation Example
Making an Address Verification Call
Then set the credentials into the address input object (gdcinp) and create a new instance of the address variable for populating the address data or validation.
' now make call
gdcinp.credentials = lgin
gdcinp.address = New WorldViewWS2.address' or declare with New
Populating an Address Request
Then set the address data for correction/validation.
gdcinp.address.addressLine1 = “123 W Cornwall Rd”
gdcinp.address.addressLine2 = “”
gdcinp.address.province = “NC”
gdcinp.address.postTown = “Cary”
gdcinp.address.PostalCode = “27607”
gdcinp.address.countryCode = “USA”
gdcinp.address.countryName = “United States”
gdcinp.options = “Geocoding”
This code takes the input address and sets an option that says after address validation/correction perform a geocoding request on the resulting address and return the latitude and longitude with the corrected address data. There will be more about utilizing options in subsequent sections of this guide.
Requesting a Result
Making a validation call is as easy as passing the assembled address data variable to the validate function. See the code snippet below:
'= Now make validation call
avsResult = avsEngine.validate(gdcinp)
First you assign the address object to the gdcinput property for address input. Notice the results are coming back in avsResult defined as a gdcResult. Also, the avsResult object typed as gdcResult contains the address, email, phone responses, though we only requested an address validation based on input. Here is example code for getting the response values for certain address pieces.
Print avsResult.address.thoroughfare
Print avsResult.address.county
Print avsResult.address.locality
Print avsResult.address.province
Print avsResult.address.postalCode
Print avsResult.address.countryName
This section of the call holds the return results. Please see the Appendix for an XML Response and Result Example.