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
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))Helpful Python SDK links