Articles

 

Using SmartyStreets Python SDK

This article is a companion to the YouTube video produced by SmartyStreets on how to use the SmartyStreets Python SDK.

Its purpose it to show how to use the US Street API with a single address using Python. Also see the Helpful Links section below for links to other APIs and examples.

SmartyStreets provides a Python SDK to help with your development tasks.

In this article, we'll discuss:

Register

Before you can use the SmartyStreets Python SDK, you will need to register for a free account. This will give you an auth-id and auth-token that you will use in the sample code below.

Once you register, login to your SmartyStreets Account.
Then click API Keys at the top of the page to find your auth_id and auth_token. These will be used in the sample code later in the article.

Install the SmartyStreets Python SDK (can used used with Python 2 and 3)

$ pip install smartystreets_python_sdk

US Street Single Address Sample Code

Note that this sample requires an auth_id and auth_token (see Register above).


import os

from smartystreets_python_sdk import StaticCredentials, exceptions, ClientBuilder
from smartystreets_python_sdk.us_street import Lookup


def run():
    auth_id = ""
    auth_token = ""

    # We recommend storing your secret keys in environment variables instead---it's safer!
    # auth_id = os.environ['SMARTY_AUTH_ID']
    # auth_token = os.environ['SMARTY_AUTH_TOKEN']

    credentials = StaticCredentials(auth_id, auth_token)

    client = ClientBuilder(credentials).build_us_street_api_client()
    # client = ClientBuilder(credentials).with_proxy('localhost:8080', 'user', 'password').build_us_street_api_client()
    # Uncomment the line above to try it with a proxy instead

    # Documentation for input fields can be found at:
    # https://smartystreets.com/docs/us-street-api#input-fields

    lookup = Lookup()
    lookup.input_id = "24601"  # Optional ID from your system
    lookup.addressee = "John Doe"
    lookup.street = "1600 Amphitheatre Pkwy"
    lookup.street2 = "closet under the stairs"
    lookup.secondary = "APT 2"
    lookup.urbanization = ""  # Only applies to Puerto Rico addresses
    lookup.city = "Mountain View"
    lookup.state = "CA"
    lookup.zipcode = "94043"
    lookup.candidates = 3
    lookup.match = "Invalid"  # "invalid" is the most permissive match

    try:
        client.send_lookup(lookup)
    except exceptions.SmartyException as err:
        print(err)
        return

    result = lookup.result

    if not result:
        print("No candidates. This means the address is not valid.")
        return

    first_candidate = result[0]

    print("Address is valid. (There is at least one candidate)\n")
    print("Delivery Information")
    print("--------------------")
    print("Delivery line 1: {}".format(first_candidate.delivery_line_1))
    print("Delivery line 2: {}".format(first_candidate.delivery_line_2))
    print("Last line:       {}".format(first_candidate.last_line))
    print()

    print("Address Components")
    print("-------------------")
    print("Primary number:  {}".format(first_candidate.components.primary_number))
    print("Predirection:    {}".format(first_candidate.components.street_predirection))
    print("Street name:     {}".format(first_candidate.components.street_name))
    print("Street suffix:   {}".format(first_candidate.components.street_suffix))
    print("Postdirection:   {}".format(first_candidate.components.street_postdirection))
    print("City:            {}".format(first_candidate.components.city_name))
    print("State:           {}".format(first_candidate.components.state_abbreviation))
    print("ZIP Code:        {}".format(first_candidate.components.zipcode))
    print("County:          {}".format(first_candidate.metadata.county_name))
    print("Latitude:        {}".format(first_candidate.metadata.latitude))
    print("Longitude:       {}".format(first_candidate.metadata.longitude))


if __name__ == "__main__":
    run()
                    

Code Discussion

Specify your AuthID and AuthToken that you received when you registered for a free SmartyStreets account. You can either hard-code the values, or create environment variables.

Next, you build the client object. If you have a proxy, uncomment out the with_proxy line and specify the URL and authentication if applicable.


auth_id = ""
auth_token = ""

# We recommend storing your secret keys in environment variables instead---it's safer!
# auth_id = os.environ['SMARTY_AUTH_ID']
# auth_token = os.environ['SMARTY_AUTH_TOKEN']

credentials = StaticCredentials(auth_id, auth_token)

client = ClientBuilder(credentials).build_us_street_api_client()
# client = ClientBuilder(credentials).with_proxy('localhost:8080', 'user', 'password').build_us_street_api_client()
# Uncomment the line above to try it with a proxy instead
                    

The Lookup object defines the data you want to use to perform the query. It can vary depending on the information you have available.

The next section of code performs the lookup and handles exceptions.

Note that this sample only performs a single query, however in other example code you will see how to perform multiple queries in a single API call.


lookup = Lookup()
lookup.input_id = "24601"  # Optional ID from your system
lookup.addressee = "John Doe"
lookup.street = "1600 Amphitheatre Pkwy"
lookup.street2 = "closet under the stairs"
lookup.secondary = "APT 2"
lookup.urbanization = ""  # Only applies to Puerto Rico addresses
lookup.city = "Mountain View"
lookup.state = "CA"
lookup.zipcode = "94043"
lookup.candidates = 3
lookup.match = "Invalid"  # "invalid" is the most permissive match

try:
    client.send_lookup(lookup)
except exceptions.SmartyException as err:
    print(err)
    return

result = lookup.result

if not result:
    print("No candidates. This means the address is not valid.")
    return
                    

Lastly, we interpret the results from the API call. Note that the results variable is an array which contains all possible candidates returned by the API. In this example, we just examine the first candidate.

Each candidate contains a summary for the USPS Delivery Address. You can also access the individual Address Components that are available for the address by using the components object on the candidate.

To see a complete list of the components, feel free to look in the SDK source code.


first_candidate = result[0]

print("Address is valid. (There is at least one candidate)\n")
print("Delivery Information")
print("--------------------")
print("Delivery line 1: {}".format(first_candidate.delivery_line_1))
print("Delivery line 2: {}".format(first_candidate.delivery_line_2))
print("Last line:       {}".format(first_candidate.last_line))
print()

print("Address Components")
print("-------------------")
print("Primary number:  {}".format(first_candidate.components.primary_number))
print("Predirection:    {}".format(first_candidate.components.street_predirection))
print("Street name:     {}".format(first_candidate.components.street_name))
print("Street suffix:   {}".format(first_candidate.components.street_suffix))
print("Postdirection:   {}".format(first_candidate.components.street_postdirection))
print("City:            {}".format(first_candidate.components.city_name))
print("State:           {}".format(first_candidate.components.state_abbreviation))
print("ZIP Code:        {}".format(first_candidate.components.zipcode))
print("County:          {}".format(first_candidate.metadata.county_name))
print("Latitude:        {}".format(first_candidate.metadata.latitude))
print("Longitude:       {}".format(first_candidate.metadata.longitude))
                    

Helpful Python SDK Links

This site uses cookies for analytics, personalized content, and ads. By continuing to browse this site, you agree to this use.
Consuming raw or undercooked cookie dough may increase your risk of foodborne illness.