SmartyStreets Python SDK

Common errors

• ModuleNotFoundError: No module named 'requests' (during 'pip install smartystreets_python_sdk')

  cause 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.
  fix Install 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.

  cause 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).
  fix Verify 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.'

  cause Your application has sent too many requests to the SmartyStreets API within a short period, exceeding your account's rate limit.
  fix Implement 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.

Warnings

• gotcha Using the wrong type of API key (embedded vs. secret) for client-side versus server-side requests will result in a 401 'Authentication Required' error.
  Fix: Ensure 'secret keys' are used for server-to-server calls (e.g., in backend Python applications) and 'embedded keys' with correct `Referer` headers for client-side (browser/mobile) applications. Double-check `auth_id` and `auth_token` values.
• gotcha Exceeding API rate limits will result in a 429 'Too Many Requests' HTTP status code, leading to failed requests.
  Fix: Implement retry logic with exponential backoff. Review your SmartyStreets account plan to understand and manage your allocated lookup limits. If using embedded keys, consider whitelisting known IP addresses.
• gotcha Intermittent 503 'Service Unavailable' errors can occur due to server rotation or temporary issues on the SmartyStreets side.
  Fix: Client-side code should be built with retry mechanisms (e.g., exponential backoff) and potentially momentary blacklisting of unresponsive IPs to handle these transient errors gracefully.
• gotcha The SmartyStreets Python SDK is offered 'FREE, AS IN PUPPIES,' which implies that while it's available for use, enhancement requests and extensive support are at SmartyStreets' sole discretion.
  Fix: Manage expectations regarding direct feature development or dedicated support channels for bespoke requests. Rely primarily on the provided documentation and community resources.

Install

• pip install smartystreets-python-sdk Install with pip

Imports

• BasicAuthCredentials

  from smartystreets_python_sdk import BasicAuthCredentials

• ClientBuilder

  from smartystreets_python_sdk import ClientBuilder

• exceptions

  from smartystreets_python_sdk import exceptions

• Lookup
  wrong:

  from smartystreets_python_sdk.us_street import Lookup as StreetLookup

  correct:

  from smartystreets_python_sdk.us_street import Lookup

  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

Quickstart

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