Smarty Python SDK

A Python client for Smarty’s address verification, geocoding, autocomplete, and data enrichment APIs.

The Smarty Python SDK lets you integrate address intelligence into your Python applications with minimal boilerplate. Whether you’re validating millions of addresses, enriching them with precise geocodes, or powering an autocomplete form, the SDK gives you a clear, Python-native way to call every Smarty API.

Contents

Installation

Install the SDK using pip:

$ pip install smartystreets_python_sdk

Import Packages:

from smartystreets_python_sdk import SharedCredentials, BasicAuthCredentials, exceptions, ClientBuilder

Authentication

Smarty offers two kinds of credentials depending on where your code runs:

• Server-side (backend, CLI, batch jobs)
  Use Auth ID + Auth Token (a Secret Key pair).
• Client-side (browser, front-end, public UI)
  Use Key + HostName.

You can find all keys in your Smarty account under:

Account → API Keys.

We recommend storing your credentials in environment variables for security:

export SMARTY_AUTH_ID="your-auth-id"
export SMARTY_AUTH_TOKEN="your-auth-token"
export SMARTY_AUTH_WEB="your-auth-web"
export SMARTY_WEBSITE_DOMAIN="your-website-domain"

Then you can import those in your script with the below:

# Server-side
auth_id = os.environ['SMARTY_AUTH_ID']
auth_token = os.environ['SMARTY_AUTH_TOKEN']
credentials = BasicAuthCredentials(auth_id, auth_token)

# Client-side
key = os.environ['SMARTY_AUTH_WEB']
hostname = os.environ['SMARTY_WEBSITE_DOMAIN']
credentials = SharedCredentials(key, hostname)
	

For details on authentication, and embedded vs secret keys, see our Authentication documentation.

Create an API client

The SDK offers different client builders for each API.

Server-side client

Here's an example for the US Street API:

client = ClientBuilder(credentials).build_us_street_api_client()

Browser/Frontend client

Here's an example for international-autocomplete-api:

client = ClientBuilder(credentials).build_international_autocomplete_api_client()

You can find a full list of API clients and options here.

Create and send lookups

Create lookups based on the addresses you want to validate. Here’s an example for the US Street API

batch = Batch()

batch.add(StreetLookup("1 Rosedale, Baltimore, Maryland"))
batch.add(StreetLookup("123 Bogus Street, Pretend Lake, Oklahoma"))
batch.add(StreetLookup("1 Rosedale, Baltimore, Maryland"))

Use the client you created earlier to send the batch:

try:
client.send_batch(batch)
except exceptions.SmartyException as err:
print(err)
return

Examine results

Review the results provided by the API:

for i, lookup in enumerate(batch):
		candidates = lookup.result

		if len(candidates) == 0:
			print("Address {} is invalid.\n".format(i))
			continue

		print("Address {} has at least one candidate.".format(i))
		print("If the match parameter is set to STRICT, the address is valid.")
		print("Otherwise, check the Analysis output fields to see if the address is valid.\n")

		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("")

More examples

• US Street API
• US Autocomplete Pro API
• US Enrichment API
• US Extract API
• US Reverse Geocoding API
• US ZIP Code API
• International Autocomplete API
• International Street API

All Python SDK examples can be found on our github here.