Explore usage of Smarty Streets API for address validation

[hartsick]

Explore address validation
With Smarty Streets API
To discover how we might deliver the best address validation experience

Resources

• Smarty Free account signup
• Smarty Ruby SDK documentation
• Smarty System requirements, including information about SSL/TLS
• Smarty Streets US street address API docs
• USPS address validation API docs
• [Internal] Notes from Smarty meeting
• [Internal] Test addresses and results

Approach

• Prototype server-side validations of address
  • How do we know if address is allowable
  • Assigning and displaying errors to model
• Prototype client-side validations of address
  • Displaying to client when address has been changed
• Prototype client-side autocomplete
• Benchmark / measure API usage of autocomplete
• Test cases referenced in questions below
• Write up notes

Note: this is now only using the US street address validation API, since autocomplete has been deprioritized for launch.

Questions to answer

• Can we restrict validations to USPS data?
  • Yes, by enabling strict match mode or by enabling invalid or enhanced APIs but filtering any dpv_match_codes that are not Y, S, or D. Match output strategies invalid or enhanced are the only ways to suggest addresses to the user (strict will not`).
• Can we validate addresses in US territories?
  • Yes, though presenting the full address returned from the API is slightly different than how we do this with other addresses (optional urbanization field). Context: we have tested this with a few addresses from Puerto Rico.
• Can we validate addresses in overseas military bases?
• What settings do we need to use to make it as close to the USPS online API as possible?

Running notes

• In the Ruby SDK example on address validation, there's a note that the 'urbanization' field is only used for addresses in Puerto Rico. What does this mean for us?
• Does state need a specific format (eg state two-letter code)? What does it need for territories and overseas?
• We can use match output strategy strict to only return results if they have dpv_match_code of Y, S, or D, which we think maps to USPS deliverability. However, this seems to be very strict in practice - and won't return suggestions
• When addresses meet the dpv_match_code, they can also return dpv_footnotes with information from USPS about the address. See api docs. I assume this is only present for S and D types but not sure. Additionally, Smarty adds a footnotes section (docs].
• I'm having a problem matching US military bases. I'm using examples based on the USPS documentation and can't get the API to return a result because they're fake. Do we have real ones we can test with? Same for territories (using addresses from Google Maps)
• USPS site doesn't seem to accept dpv_match_code of D, and only accepts Y and S.
• When dpv_match_code is S additional information is preserved in the returned address even though it is incorrect.
• Suggestion from Mapbox on autocomplete: start sending keystrokes after ~6 characters

[hartsick]

Note from Porta: can we compare to the USPS address validation API and see what they accept?

[porta-antiporta]

Looking at USPS API we will:

• Key off DPVConfirmation field and accept the following values: Y, S
• Store both the address input by the user and the address returned

<Address1>
<Address2>
<City>
<CityAbbreviation>
<State>
<Zip5>
<Zip4>
<DeliveryPoint>
<CarrierRoute>

• CityAbbreviation, DeliveryPoint, CarrierRoute will be hidden from the user.
• DPVConfirmation value will also be stored.
• Address returned is what will be sent to USPS.

This recap correctly @hartsick?

[porta-antiporta]

We need input from SmartyStreets as to how to call their API to match as close a return as the USPS API (ex. SmartyStreets can return more than 1 address (in case of multiple potential matches), USPS API only returns one.) @ryanwoldatwork is this something we can ask SmartyStreets?

[hartsick]

@porta-antiporta Thinking more about this, I think we should find a way to submit the corrected address on the review page like what you had already specified in #43 (vs what we talked about earlier). I think we don't want to submit something to USPS that the person submitting hasn't seen and verified.

[porta-antiporta]

@hartsick yes I agree. Apologies, I was looking at this issue as fleshing out technical approach to the API, was going to update #43 with our findings. So to confirm:

1. We accept the returned address from the API
2. That new address is rendered on Review page along with a note/warning so the user is aware of the change.

[hartsick]

@porta-antiporta great! that makes sense to me!

[hartsick]

@porta-antiporta Poking around USPS.com and the Smarty Streets API, it seems like USPS shop currently doesn't accept dpv value D (for missing apartment numbers) but do accept Y and S. planning to move forward with that

[porta-antiporta]

10-4. updated above and in #43

[hartsick]

For going forward with this, I think we have a couple of options (loose notes before I din break):

1. Only use strict validation from address validation API. This is the simplest technically but would mean we have many more validation failures and couldn't suggest many, if any, address corrections. The only time we might give useful feedback to user is if a correct address is missing a line 2, like apartment. I think the negative impacts of this could be reduced if we used this with the autocomplete API set onto to show postal data.
2. Use invalid or enhanced matched strategy from address validation API. This is more complex from a technical and UX stand-point (need warnings), but might let us give suggested addresses where there was no exact match.

In all of these we'd need to implement in Javascript in order to display the suggested / corrected address back to the user before hitting the server. We would want to revalidate server-side just in case.

[ryanwoldatwork]

Hi @hartsick - thanks for outlining these tradeoffs.

If the USPS match is required (presumably, to support mailing needs), then strict makes sense.

Overall, this prompts me to inquire about "failure demand" - and otherwise, is there a help system to catch outlier cases/user experiences?

[hartsick]

Notes from Jan 11 sync:

• Split address validation and autocomplete into two stories, prioritize first
• Want to understand Smarty capacity / load before implementing autocomplete
• Want to have an escape hatch to make sure people don't get stuck; not sure what
• If address validation goes down: first pass: if we aren't validating address then we do need to collect contact information. second pass: integrate with USPS API for backup