Willowbend API Documentation
Was this helpful?Introduction
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 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.
Compliance and Security
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.
Process Design
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.
Search
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.
Search Plugin
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.
Wiring up the Search Plugin
The Search plugin can be embedded into an HTML page for easy address lookup. The requirements are listed below:
- The HTML page needs a script reference to jQuery 3.1+
- The HTML page needs a script reference to the jquery.wb-api script file.
- 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.
- Replace “Enter Willowbend Key” with your 12-character Willowbend UserKey in the plugin call.
- Add an HTML text input with id=address onclick=autoComplete that will act as the data entry field for entering the address.
- Add HTML text inputs with id=line1, city, state, and zipcode that will display the selected address.
- Add HTML div with id=api-result to display the list of returned addresses.
- 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.
Further Processing with the Search Plugin
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.
Search Details
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":"",
"AssessorParcelLon":"",
"Carte":"C095",
"City":"Plano",
"CongressCode":"03",
"DelvSeqNo":"00052",
"DP_Digits":"50",
"DP_Check":"2",
"Lat":33.0243149,
"Lon":-96.7887039,
"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"
}
Showing and Hiding Search Fields
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
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.
Compliance and Security
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.
Process Design
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.
Verification Plugin
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.
Wiring up the Verification Plugin
The Verification plugin can be embedded into an HTML page for easy address verification. The requirements are listed below:
- The HTML page needs a script reference to jQuery 3.1+
- The HTML page needs a script reference to the jquery.wb-api script file.
- 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.
- Replace “Enter Willowbend Key” with your 12-character Willowbend UserKey in the plugin call.
- Add HTML text inputs with id= line1, city, state, and zip code that will act as the data entry fields for entering the address.
- Add HTML div with id=api-result to display the returned address. See Verification Api Details for more information on returned fields.
- Add a button to call myFunction when clicked.
At this point, you should be able to perform Address Verification.
Verification API
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.
Verification API Details
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",
"Lat": 32.98854, "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"
}
Verification API Batch
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",
"Lat": 33.0003433,
"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:
| A1 | The input record was an exact match for either the abbreviated version or the long version of an address in the Willowbend national database based on Line 1, Line 1a, City, State, Zip Code |
| A2 | The input record was a “like” match for either the abbreviated version or the long version of an address in the Willowbend national database based on Line 1, Line 1a, City, State, Zip Code |
| A3 | The input record was a “like” match for either the abbreviated version or the long version of an address in the Willowbend national database based on Line 1, Line 1a, Zip Code |
| A4 | The input record was a “like” match for either the abbreviated version or the long version of an address in the Willowbend national database based on Line 1, Line 1a, City, State |
| B1 | The input address was parsed and reconstructed based on correcting Line 1 or Line 1a, and was an exact match for either the abbreviated version or the long version of an address in the Willowbend national database based on Line 1, Line 1a, City, State, Zip Code |
| B2 | The input address was parsed and reconstructed based on correcting Line 1 or Line 1a, and was a “like” match for either the abbreviated version or the long version of an address in the Willowbend national database based on Line 1, Line 1a, City, State, Zip Code |
| B3 | The input address was parsed and reconstructed based on correcting Line 1 or Line 1a, and was a “like” match for either the abbreviated version or the long version of an address in the Willowbend national database based on Line 1, Line 1a, Zip Code |
| B4 | The input address was parsed and reconstructed based on correcting Line 1 or Line 1a, and was a “like” match for either the abbreviated version or the long version of an address in the Willowbend national database based on Line 1, Line 1a, City, State |
| C1 | The raw original address was sent to the CASS/DPV system and either was a “like” match for either the abbreviated version or the long version of an address in the Willowbend national database based on Line 1, Line 1a, City, State, Zip Code, or it was a non-valid address and returned with a “0” |
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
| Quantity of addresses in body | Time to process in Milliseconds | Milliseconds per record |
| 10 | 1326 | 132.6 |
| 20 | 1911 | 95.5 |
| 50 | 8213 | 164.26 |
| 100 | 14316 | 143.16 |
| 200 | 28706 | 143.53 |
| 500 | 102215 | 204.43 |
| 1000 | 336564 | 336.56 |
| 2000 | 1624023 | 812.01 |
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.
Downloads
Willowbend Search Plugin Documentation (165.3 KiB, 91 hits)
Published: 03-28-2018
Willowbend Search Plugin Documentation (165.3 KiB, 91 hits) Willowbend Verify Plugin Documentation (45.7 KiB, 85 hits)
Published: 03-28-2018
Willowbend Verify Plugin Documentation (45.7 KiB, 85 hits)