Skip to main content
Not sure which product you need?Let the wizard guide you
42 days freeStart trial
Smarty

US Address Verification in Python - Developer's quickstart guide

Welcome to the developer’s guide for our US Address Verification product. This document will walk you through getting started with using our products in Python, with code block examples.

Before getting started, it’s important to note that most SDKs are hosted in Smarty’s official GitHub organization. The JavaScript SDK, Rust SDK, and some examples for TypeScript, React, and Vue can be found here. Also, if you’re working with another language, we’ve got support for that, too. These repositories also have examples of calling other Smarty APIs.

In-depth docs of other Smarty APIs can be found here.

Ready, set, let’s go!

Install

To get started with verifying US addresses, pull down Smarty’s Python SDK to your development machine of choice:

pip install smartystreets_python_sdk
Tell us what looks wrong and we'll take a look.

Quickstart

Import the Smarty SDK

Next, you’ll want to import the Smarty Python SDK:

from smartystreets_python_sdk import BasicAuthCredentials, exceptions, ClientBuilder, Batchfrom smartystreets_python_sdk.us_street import Lookup as StreetLookup
Tell us what looks wrong and we'll take a look.

The us-street class provides the structures and endpoints to access Smarty’s US Address Verification and US Rooftop Geocoding products.

Create an API client

Build your client object with your Smarty credentials (secret keys).

auth_id = os.environ['SMARTY_AUTH_ID']token = os.environ['SMARTY_AUTH_TOKEN']credentials = BasicAuthCredentials(auth_id, token)client = ClientBuilder(credentials).build_us_street_api_client()
Tell us what looks wrong and we'll take a look.

This client handles all HTTP complexities. The ClientBuilder provides a number of option methods, such as setting max retries, timeouts, base URL, etc. For authentication, we will use basic auth with the secret keys. We recommend storing your credentials in environment variables for security.

Create and batch lookups

The Smarty Python SDK sends all address validation requests in batches. To create a request, start by creating a batch of addresses to send for processing at Smarty. We've provided some sample addresses here, but feel free to load your own addresses however you'd like.

addresses = ["1600 Pennsylvania Avenue Washington, DC", "1600 Amphitheatre Parkway Mountain View, CA 94043"]batch = Batch()for address in addresses:    lookup = StreetLookup()    lookup.street = address    batch.add(lookup)
Tell us what looks wrong and we'll take a look.

Here, we’ve created a batch by loading each address into a Lookup object. Next, we add those Lookups to a Batch. Typically, these addresses come from a file, database, etc., but we’ve left that part up to you, depending on your needs.

For each lookup, you can use a combination of at least:

  • street, city, and state
    OR
  • street and ZIP Code
    OR
  • street (full address in a single field)

As another example, Lookup could include street, city, state, and ZIP Code, even though breaking the address into these components is not needed to perform the lookup.

lookup = StreetLookup()lookup.street = "1600 Amphitheatre Parkway"lookup.city = "Mountain View"lookup.state = "CA"lookup.zipcode = "94043"
Tell us what looks wrong and we'll take a look.

There are many other fields that allow you to customize your response, such as match type, candidates, inputID, etc. To explore all of these options, view the us-street-api documentation here.

Also note that each batch has a maximum size limit of 100; multiple concurrent batches can be sent.

Send batch

Once you have your Batch filled with Lookups, simply call SendBatch to get your validated results:

try:    client.send_batch(batch)except exceptions.SmartyException as err:    print(err)    return
Tell us what looks wrong and we'll take a look.

The results will be placed in the Results field for each lookup within the batch.

To keep your integration reliable, we recommend handling any errors returned by the API. You can find a list of response codes for the us-street-api here.

Examine results

As mentioned earlier, the results of each Lookup within the batch are stored in its Results field. Keep in mind that each Lookup could have multiple results.

for i, lookup in enumerate(batch):    candidates = lookup.result    if len(candidates) == 0:        print("Address {} is invalid.\n".format(i))        continue    for candidate in candidates:        components = candidate.components        metadata = candidate.metadata        print("\nCandidate {} : ".format(candidate.candidate_index))        print("Delivery line 1: {}".format(candidate.delivery_line_1))        print("Last line:       {}".format(candidate.last_line))        print("ZIP Code:        {}-{}".format(components.zipcode, components.plus4_code))        print("County:          {}".format(metadata.county_name))        print("Latitude:        {}".format(metadata.latitude))        print("Longitude:       {}".format(metadata.longitude))    print("")
Tell us what looks wrong and we'll take a look.

Here, we’ve included a sample of how you might loop through all results and print them, but at this point, you’re free to process the output however you would like!

Documentation

Most of the SDKs are available in Smarty’s official GitHub organization, including the JavaScript SDK, Rust SDK, and repositories for TypeScript, React, and Vue. These repositories also have examples of calling other Smarty APIs.

In-depth docs for other Smarty APIs can be found here.

Was this helpful?

Ready to get started?

This chat is powered by Help Scout. Chats are recorded. Privacy Policy