• Introduction
• Compliance and Security
• Process Design
• Search
• Search Plugin
• Wiring up the Verification Pluginarch
• Further Processing with the Search Plugin
• Search Details
• Showing and Hiding Search Fields

Willowbend owns and maintains a Master Location Data Domain based on a national address database of over 160 million verified residential, business and PO Box addresses. Verified means that the address has passed the highest standards of delivery by the US Postal Service. Additionally, Willowbend owns and maintains an additional data set of over 14 million address locations that the US Postal Services recognize as existing, but to which they do not deliver mail – “NOSTAT”. (The reason an address may exist, but be classified as a NOSTAT, by the US Postal service fall into several categories. One category contains addresses that do not want street level delivery at any time – Such as the IRS or some large retailers. One category contains addresses that are deemed as long-term vacant locations and will be available for mail delivery once they are reoccupied. In some cases, NOSTAT addresses are locations that exist in a locales 911 database and have been transmitted to the USPS but are not yet occupied.) Willowbend has assigned a longitude and latitude to over 97% of those verified locations. Willowbend is moving its longitude and latitude information to be based on Local Assessor address information which will be completed in 2019. Where a street-level geocode is not possible, Willowbend has assigned a Zip9 centroid to an address.

Finally, Willowbend owns and maintains a series of metadata and related data records linked to the master database.   These include new mover records, Zip 9 summary information, vacant homes and businesses, Zip Code summary counts by type of dwelling, Congressional district, Census boundaries, County boundaries, MSA boundaries and more.  Willowbend maintains over 100 demographic variables linked to Census Block Group and Census Block that can be provided based on a request.

This data ownership by Willowbend of approximately 97% of all the residential and business addresses in the US is extremely important in demonstrating the difference between Search and other cloud-based solutions.  Search allows for registered clients to use it to increase the data value of their own data or gain access to location information not currently in their possession.

Willowbend’s Search is designed to allow full integration into a client’s business processes.  Search meets the needs for address verification, address location, address visualization, and policy compliance where needed.

Willowbend’s data servers and application servers are housed in a Tier 4 data center with 5-9’s uptime.  Backups are maintained at a related data center in another city for disaster recovery purposes.  All communication with the data and application servers is through secure channels such as HTTPS or SFTP. 

Willowbend’s address verification process does not include Personal Identifiable Information (PII).

All HIPAA or other data requiring specialized security is maintained in encrypted databases and tables in the data center.  However, because of the Willowbend process design, it is typically not required that such sensitive information reside outside of the originating source. 

Clients send requests to the API using predesigned REST format.  The process first attempts to match the input record to an address in the extensive Master Location database. There are numerous matching techniques employed.  If the address can be matched, information related to the address can be immediately returned to the client in JSON format. 

If an immediate match cannot be made, then the API sends the address information on to another application server where it is processed through Willowbend’s USPS certified DPV system.  The certified address is returned to the main server and is again checked to determine if after clean-up it can be matched to an existing record in the database.  If a match is performed, then related information is appended as requested by the client. 

Willowbend’s Search uses RESTful web services that provide access to the Master Location Data domain. Customers can access the data for use in building their own browser-based applications or through Willowbend’s Cloud-based Services.

Each Willowbend Customer is given an access key called a UserKey when they register. The UserKey is used to uniquely identify each user of the system and is used to authorize usage. Each call to the Search requires the UserKey as part of the input.

Search APIs are called using the secure SSL protocol.  URLs start with HTTPS to initiate any transaction against Willowbend’s Master Location Data. Results are returned as JSON datasets.

The Search plugin is a jQuery plugin that provides access to the Master Location Data domain. Customers can implement this plugin on a registration or e-commerce page of their website. The Plugin calls the Search API and is usable in most modern web browsers. The response returns a list of USPS standard addresses. Once an address is selected from the list additional details about the address can be accessed in the browser. 

The Search plugin can be embedded into an HTML page for easy address lookup. The requirements are listed below:

1. The HTML page needs a script reference to jQuery 3.1+
2. The HTML page needs a script reference to the jquery.wb-api script file.
3. The HTML page must have a Javascript function to call the Search plugin. The functions should be similar to those in the sample search.html.
4. Replace “Enter Willowbend Key” with your 12-character Willowbend UserKey in the plugin call.
5. Add an HTML text input with id=address onclick=autoComplete that will act as the data entry field for entering the address.
6. Add HTML text inputs with id=line1, city, state, and zipcode that will display the selected address.
7. Add HTML div with id=api-result to display the list of returned addresses.
8. Add HTML div with id=processing-result to display additional details about the selected address. See Search Details for more information on returned fields.

At this point, you should be able to perform Address Search.

In the rare event that the Search plugin is not able to find an appropriate address to return, the Search plugin can be configured to call Further Processing. This feature calls Willowbend’s proprietary process to attempt to qualify the address and return the results.

Description: The Search returns a list of addresses that most closely matches the input Address. The full address should be entered on one line including any secondary address, city and state and zip code. As the address is input the Search API is called repeatedly to refine the displayed list.

Input Parameters for Search: Key, Address

Key: the UserKey provided to you upon registration

Address: Full Address including any Secondary unit or suite, city, state, and 5-digit Zipcode. Commas are not needed or desired to separate address elements

URL Format: https://api.willowbend.com/api/AutoComplete/key/${key}/address/${address}

Input Parameters for GetAddressByAid: Key, Product, Aid

Key: the UserKey provided to you upon registration

Product:                

PO = Full Addresses with parcel name, latitude, and longitude                

PP = All fields included in PO plus parcel owner and total value                

Aid = Willowbend Address AID

URL Format: https://api.willowbend.com/api/Address/ByAid/key/${key}/product/${product}/aid/${aid}

Output Fields:

Owner, Total_Value, AID, AreaKey, AssessorParcelNumber, AssessorParcelLat, AssessorParcelLon, CaRte, City,

CongressCode, DelvSeqNo, DP_Digits, DP_Check, Lat, Lon, Line1, Line1_1a_Lon, Location, NoMail, Postdir, Predir,

ResBus, SecDesc, SecNo, State, Streetname, StreetNum, Suffix, Vacant, Zipcode, ZipPlus4

Sample Output:

{
      "Owner":"",
      "Total_Value":"",
      "AID":116990140,
      "AreaKey":"480850316213",
      "AssessorParcelNumber":"",
      "AssessorParcelLat":"33.0243149",
      "AssessorParcelLon":"96.7887039",
      "Carte":"C095",
      "City":"Plano",
      "CongressCode":"03",
      "DelvSeqNo":"00052",
      "DP_Digits":"50",
      "DP_Check":"2",
      "Line1":"1800 Preston Park Blvd Ste 200",
      "Line1_1a_Long":"1800 Preston Park Blvd Ste 200",
      "Location":"",
      "NoMail":"Y",
      "Postdir":"",
      "Predir":"",
      "ResBus":"B",
      "SecDesc":"Ste",
      "SecNo":"200",
      "Streetname":"Preston Park",
      "StreetNum":"1800",
      "State":"TX",
      "Suffix":"Blvd",
      "Vacant":"N",
      "Zipcode":"75093",
      "Zipplus4":"5149"
}

The list of search fields that are displayed can be modified as needed. The Search plugin contains several Javascript functions for manipulating the visible list. The getAddressFields  function is the complete list of fields and the getVisibleFields function lists the fields that are displayed in the Address Details section:

• INTRODUCTION
• COMPLIANCE AND SECURITY
• PROCESS DESIGN
• VERIFICATION PLUGIN
• WIRING UP THE VERIFICATION PLUGIN
• VERIFICATION API
• VERIFICATION API DETAILS
• VERIFICATION API BATCH

Willowbend owns and maintains a Master Location Data Domain based on a national address database of over 160 million verified residential, business and PO Box addresses.  Verified means that the address has passed the highest standards of delivery by the US Postal Service.  Additionally, Willowbend owns and maintains an additional data set of over 14 million address locations that the US Postal Services recognize as existing, but to which they do not deliver mail – “NOSTAT”.  (The reason an address may exist, but be classified as a NOSTAT, by the US Postal service fall into several categories.  One category contains addresses that do not want street level delivery at any time – Such as the IRS or some large retailers.  One category contains addresses that are deemed as long-term vacant locations and will be available for mail delivery once they are reoccupied.  In some cases, NOSTAT addresses are locations that exist in a locales 911 database and have been transmitted to the USPS but are not yet occupied.) All address records have a longitude and latitude appended to them based on Caliper Corporation / Here® street data.  Approximately 97% of all address records have a geocode location based on their street address.  Where a street-level geocode is not possible, Willowbend has assigned a Zip9 centroid to an address

Finally, Willowbend owns and maintains a series of metadata and related data records linked to the master database.   These include new mover records, Zip 9 summary information, vacant homes and businesses, Zip Code summary counts by type of dwelling, Congressional district, Census boundaries, County boundaries, MSA boundaries and more.  Willowbend maintains over 100 demographic variables linked to Census Block Group and Census Block that can be provided based on the request.

This data ownership by Willowbend of approximately 97% of all the residential and business addresses in the US is extremely important in demonstrating the difference between Verification Api and other cloud-based solutions.  Verification Api allows for registered clients to use it to increase the data value of their own data or gain access to location information not currently in their possession.

Willowbend’s Verification Api is designed to allow either standalone service or full integration into a client’s business processes.  Verification Api meets the needs for address verification, address location, address visualization, and policy compliance where needed.

Willowbend’s data servers and application servers are housed in a Tier 4 data center with 5-9’s uptime.  Backups are maintained at a related data center in another city for disaster recovery purposes.  All communication with the data and application servers is through secure channels such as HTTPS or SFTP.

Willowbend’s address verification process does not include Personal Identifiable Information (PII).

All HIPAA or other data requiring specialized security is maintained in encrypted databases and tables in the data center.  However, because of the Willowbend process design, it is typically not required that such sensitive information reside outside of the originating source.

Clients send requests to the Api using predesigned REST format.  The process first attempts to match the input record to an address in the extensive Master Location database. There are numerous matching techniques employed.  If the address can be matched, information related to the address can be immediately returned to the client in JSON format.

If an immediate match cannot be made, then the Api sends the address information on to another application server where it is processed through Willowbend’s USPS certified DPV system.  The certified address is returned to the main server and is again checked to determine if after clean-up it can be matched to an existing record in the database.  If a match is performed, then related information is appended as requested by the client.

The Verification plugin is a jQuery plugin that provides access to the Master Location Data domain. Customers can implement this plugin on a registration or ecommerce page of their website. The Plugin calls the Verification Api and is usable in most modern web browsers. The response returns the USPS standard address, Zip9 information and household level longitude and latitude of the address if available in the Master Location database. 

The Verification plugin can be embedded into an HTML page for easy address verification. The requirements are listed below:

1. The HTML page needs a script reference to jQuery 3.1+
2. The HTML page needs a script reference to the jquery.wb-api script file.
3. The HTML page must have a Javascript function to call the Verification plugin. The function should be similar to myFunction in the sample verify.html.
4. Replace “Enter Willowbend Key” with your 12-character Willowbend UserKey in the plugin call.
5. Add HTML text inputs with id= line1, city, state, and zip code that will act as the data entry fields for entering the address.
6. Add HTML div with id=api-result to display the returned address. See Verification Api Details for more information on returned fields.
7. Add a button to call myFunction when clicked.

At this point, you should be able to perform Address Verification.

The Verification Api is a RESTful web service that provides access to the Master Location Data domain. Customers can access the data for use in building their own browser-based applications or through Willowbend’s Cloud-based Services.

Each Willowbend Customer is given an access key called a UserKey when they register. The UserKey is used to uniquely identify each user of the system and is used to authorize usage. Each call to the Verification Api requires the UserKey as part of the input.

Verification Apis are called using the secure SSL protocol.  URLs start with HTTPS to initiate any transaction against Willowbend’s Master Location Data. Results are returned as JSON datasets.

Description: The Verification Api returns a single address that most closely matches the input Address and Zipcode or Address and City and State provide.

Input Parameters: Key, Product, Zipcode, Line1, City, State

Key: the UserKey provided to you upon registration

Product:

PA = Mailing Addresses

PB = Output Fields plus AreaKey, Lat & Lon, Congress Code

Zipcode: 5-digit Zipcode or replace with an underline character (_) if blank

Line1: Full Line1 Address for verification

City: City or replace with an underline character (_) if blank

State: 2-character State abbreviation or replace with an underline character (_) if blank

URL Format: https://api.willowbend.com/api/Address/ByLine1/key/{key}/product/{product}/zipcode/{zipcode}/line1/{line1}/City/{City}/State/{State}

Output Fields: AID, Line1, StreetNum, Predir, Streetname, Suffix, Postdir City, State, Zipcode, ZipPlus4, SecDesc, SecNo, CaRte, ResBus, Lat, Lon, AreaKey, Vacant, NoMail, Location

Examples: https://api.willowbend.com/api/Address/ByLine1/key/123ABC456DEF/product/PA/zipcode/75287/line1/17440 Dallas Pkwy/City/Dallas/State/TX

{ 
"Line1_1a_Long": "17440 Dallas Pkwy Ste 101",
 "AreaKey": "480850317061",
 "Assessor Lat": 32.98854, "Assessor Lon": -96.82809,
 "CongressCode": "03",
 "AID": 118035222,
 "StreetNum": "17440",
 "Line1_1a": "17440 Dallas Pkwy Ste 101",
 "Predir": "",
 "Streetname": "Dallas",
 "Suffix": "Pkwy",
 "Postdir": "",
 "City": "Dallas",
 "State": "TX",
 "Zipcode": "75287",
 "Zipplus4": "7307",
 "SecDesc": "Ste",
 "SecNo": "101",
 "Carte": "C001",
 "DelvSeqNo": "00039",
 "ResBus": "B",
 "Vacant": "N",
 "NoMail": "N",
 "Location": "",
 "DP_Digits": "26",
 "DP_Check": "6"
 }

POST — BULK ADDRESSES

Description: The Verification Batch Api returns verified address that is processed in bulk mode using a block of input addresses

Input Parameters: Key, Product, Zipcode, Line1, City, State

Key: the UserKey provided to you upon registration

Product:

PA = Mailing Addresses

PB = Output Fields plus AreaKey, Lat & Lon, Congress Code

            Zipcode: 5-digit Zipcode or replace with an underline character (_) if blank

            Line1: Full Line1 Address for verification

            City: City or replace with an underline character (_) if blank

            State: 2-character State abbreviation or replace with an underline character (_) if blank

URL Format: https://api.willowbend.com/api/address/ByLine1Batch/key/{key}/product/{product}

Output Fields: AID, Line1, StreetNum, Predir, Streetname, Suffix, Postdir City, State, Zipcode, ZipPlus4, SecDesc, SecNo, CaRte, ResBus, Lat, Lon, AreaKey, Vacant, NoMail, Location

Examples:https://api.willowbend.com/api/Address/ByLine1/key/123ABC456DEF/product/PA/zipcode/75287/line1/17440 Dallas Pkwy/City/Dallas/State/TX

The body of the data sent must be in the following JSON format:

{ "data": [
{"zipcode":"75093","line1":"5312 Seascape Ln","city":"Plano","state":"TX","cid":"0001"},
{"zipcode":"75252","line1":"18333 Preston Rd STE 250","city":"Dallas","state":"TX","cid":"19TX"},
{"zipcode":"75001","line1":"17440 Dallas Pkwy Ste 217","city":"Dallas","state":"TX","cid":"1220"} ]}

The Batch Api returns an array of data JSON records as shown below

[

{
"MatchLevel": "A1",
"CID": "19TX",
"Passes": 1,
"ProcessTime": 23,
"Line1_1a_Long": "18333 Preston Rd Ste 250",
"AreaKey": "480850317161",
"Assessor Lat": 33.0003433,
"Assessor Lon": -96.79691,
"CongressCode": "03",
"AID": 117962586,
"StreetNum": "18333",
"Line1_1a": "18333 Preston Rd Ste 250",
"Predir": "",
"Streetname": "Preston",
"Suffix": "Rd",
"Postdir": "",
"City": "Dallas",
"State": "TX",
"Zipcode": "75252",
"Zipplus4": "6026",
"SecDesc": "Ste",
"SecNo": "250",
"Carte": "R010",
"DelvSeqNo": "00155",
"ResBus": "B",
"Vacant": "N",
"NoMail": "N",
"Location": "",
"DP_Digits": "50",
"DP_Check": "0"
}
]

The CID field is designed to hold the customer’s unique ID for the record, so it can be used for matching back to the customer’s dataset.  It does not need to be numeric.

The AID is the unique ID of the record in the Willowbend national database. Records returned with an AID of “0” or Null are not valid addresses.

The MatchLevel is a code that indicates the level at which matching occurred:

 Best Practices

The Batch Api was tested using Google’s Postman App as the client to determine if there is a point of diminishing returns on the quantity of addresses placed in the body of the query.

A selection of random addresses was used containing records in various degrees of quality.

This testing was done in the production API, so other users were on the system.  Some of the variations in the results is probably due to their usage.

This table represents the results of that testing

These timings can vary based on the quality of the addresses processed.  The further into the processes required to identify the correct address the longer the process will run. The test data had addresses in every MatchLevel in what was processed.

Our recommendation based on these timings is that batches should not exceed 1000 records at one time for maximum efficiency.  Batches between 250 and 500 are clearly the best.

Under heavy load with 4 sets of 500 records running nearly simultaneously, the processing time for 500 records went from .25 seconds per record to .51 seconds per record.  This would be like sending multiple POSTs to the system of 500 records back to back to process 2,000 records.  The total milliseconds per record in this approach to process 2,000 records are 474.88 per record.  This is approximately 60% faster than sending 2,000 records at a single time.

  Willowbend Search Plugin Documentation (165.3 KiB, 120 hits)

Published: 03-28-2018

 

  Willowbend Verify Plugin Documentation (45.7 KiB, 109 hits)

 Published: 03-28-2018