Using Smarty Python SDK

This article is a companion to the YouTube video produced by Smarty on how to use the Smarty 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.

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

In this article, we'll discuss:

Register with Smarty
Code Example
Helpful Links

Register

Before you can use the Smarty 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 Smarty 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 Smarty 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://www.smarty.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 Smarty 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))

Integrations & plugins

Learning hub

Contact us

Using Smarty Python SDK

Register

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

US Street Single Address Sample Code

Code Discussion

Helpful Python SDK Links