Registry /
http-networking / smartystreets-python-sdk
Install & Compatibility
Where this runs
tested against v6.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.678s · 22.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.2s · import 0.601s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BasicAuthCredentials
✓ from smartystreets_python_sdk import BasicAuthCredentials
ClientBuilder
✓ from smartystreets_python_sdk import ClientBuilder
exceptions
✓ from smartystreets_python_sdk import exceptions
Lookup
✓ from smartystreets_python_sdk.us_street import Lookup
✗ from smartystreets_python_sdk.us_street import Lookup as StreetLookup
While aliasing to StreetLookup is common in examples, Lookup is the direct class name.
MatchType
✓ from smartystreets_python_sdk.us_street.match_type import MatchType
This quickstart demonstrates how to validate a US street address using the SmartyStreets Python SDK. It initializes credentials using environment variables, builds a US Street API client, creates an address lookup, sends it, and prints the validated address details and geocoding information.
import os
from smartystreets_python_sdk import BasicAuthCredentials, ClientBuilder, exceptions
from smartystreets_python_sdk.us_street import Lookup
# It is recommended to store your SmartyStreets Auth ID and Auth Token in environment variables.
# Example: export SMARTY_AUTH_ID='YOUR_AUTH_ID'
# Example: export SMARTY_AUTH_TOKEN='YOUR_AUTH_TOKEN'
auth_id = os.environ.get('SMARTY_AUTH_ID', '')
auth_token = os.environ.get('SMARTY_AUTH_TOKEN', '')
if not auth_id or not auth_token:
print('Please set SMARTY_AUTH_ID and SMARTY_AUTH_TOKEN environment variables.')
exit(1)
try:
credentials = BasicAuthCredentials(auth_id, auth_token)
# The ClientBuilder can be used to build clients for various SmartyStreets APIs.
# For US Street Address API, use build_us_street_api_client().
client = ClientBuilder(credentials).build_us_street_api_client()
# Create a Lookup object for the address you want to validate.
lookup = Lookup()
lookup.street = "1600 Amphitheatre Pkwy"
lookup.city = "Mountain View"
lookup.state = "CA"
lookup.zipcode = "94043"
# Send the lookup to the SmartyStreets API.
client.send_lookup(lookup)
if not lookup.result or not lookup.result.candidates:
print("No candidates found for the address. It might be invalid.")
else:
first_candidate = lookup.result.candidates[0]
print(f"Validated Address: {first_candidate.delivery_line_1}, {first_candidate.last_line}")
print(f"Components: City={first_candidate.components.city_name}, State={first_candidate.components.state_abbreviation}, ZIP={first_candidate.components.zipcode}")
if first_candidate.metadata.latitude and first_candidate.metadata.longitude:
print(f"Latitude: {first_candidate.metadata.latitude}, Longitude: {first_candidate.metadata.longitude}")
except exceptions.SmartyException as e:
print(f"SmartyStreets API error: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'requests' (during 'pip install smartystreets_python_sdk')
In some environments or older Python versions, if the 'requests' package is not already installed, the SDK's setup process might fail trying to import itself before its dependencies are resolved.
fixInstall the 'requests' library explicitly first: `pip install requests`, then `pip install smartystreets-python-sdk`.
smartystreets_python_sdk.exceptions.bad_credentials_exception.BadCredentialsException: Unauthorized: Either the supplied credentials were invalid, or the supplied signing authority was invalid.
This error (or an HTTP 401 status code) typically indicates invalid Auth ID/Auth Token, or using the incorrect type of API key (e.g., an embedded client-side key for a server-side request).
fixVerify that your `SMARTY_AUTH_ID` and `SMARTY_AUTH_TOKEN` environment variables are correctly set and correspond to 'secret keys' for server-side applications. For client-side applications, ensure 'embedded keys' are used with appropriate `Referer` headers.
HTTP 429 status code: 'Too Many Requests: The rate limit has been exceeded.'
Your application has sent too many requests to the SmartyStreets API within a short period, exceeding your account's rate limit.
fixImplement robust retry logic with exponential backoff on your API calls. Check your SmartyStreets account dashboard for specific rate limits and consider upgrading your plan if sustained higher throughput is required.
Upgrade
Version history
6.2.1latest on PyPI · released Jun 8, 2026
Audit
Dependencies
requestsrequiredUsed for making HTTP requests; automatically installed by pip.