{"id":7725,"library":"smartystreets-python-sdk","title":"SmartyStreets Python SDK","description":"The SmartyStreets Python SDK is an official library designed to simplify access to SmartyStreets APIs for Python developers. It provides ready-made data structures and handles the underlying HTTP complexities. The library is currently at version 5.7.0, released on April 1, 2026, and is actively maintained with regular updates.","status":"active","version":"5.7.0","language":"en","source_language":"en","source_url":"https://github.com/smartystreets/smartystreets-python-sdk","tags":["address validation","geocoding","API client","SmartyStreets","US Street API"],"install":[{"cmd":"pip install smartystreets-python-sdk","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Used for making HTTP requests; automatically installed by pip.","package":"requests","optional":false}],"imports":[{"symbol":"BasicAuthCredentials","correct":"from smartystreets_python_sdk import BasicAuthCredentials"},{"symbol":"ClientBuilder","correct":"from smartystreets_python_sdk import ClientBuilder"},{"symbol":"exceptions","correct":"from smartystreets_python_sdk import exceptions"},{"note":"While aliasing to StreetLookup is common in examples, Lookup is the direct class name.","wrong":"from smartystreets_python_sdk.us_street import Lookup as StreetLookup","symbol":"Lookup","correct":"from smartystreets_python_sdk.us_street import Lookup"},{"symbol":"MatchType","correct":"from smartystreets_python_sdk.us_street.match_type import MatchType"}],"quickstart":{"code":"import os\nfrom smartystreets_python_sdk import BasicAuthCredentials, ClientBuilder, exceptions\nfrom smartystreets_python_sdk.us_street import Lookup\n\n# It is recommended to store your SmartyStreets Auth ID and Auth Token in environment variables.\n# Example: export SMARTY_AUTH_ID='YOUR_AUTH_ID'\n# Example: export SMARTY_AUTH_TOKEN='YOUR_AUTH_TOKEN'\nauth_id = os.environ.get('SMARTY_AUTH_ID', '')\nauth_token = os.environ.get('SMARTY_AUTH_TOKEN', '')\n\nif not auth_id or not auth_token:\n    print('Please set SMARTY_AUTH_ID and SMARTY_AUTH_TOKEN environment variables.')\n    exit(1)\n\ntry:\n    credentials = BasicAuthCredentials(auth_id, auth_token)\n    # The ClientBuilder can be used to build clients for various SmartyStreets APIs.\n    # For US Street Address API, use build_us_street_api_client().\n    client = ClientBuilder(credentials).build_us_street_api_client()\n\n    # Create a Lookup object for the address you want to validate.\n    lookup = Lookup()\n    lookup.street = \"1600 Amphitheatre Pkwy\"\n    lookup.city = \"Mountain View\"\n    lookup.state = \"CA\"\n    lookup.zipcode = \"94043\"\n\n    # Send the lookup to the SmartyStreets API.\n    client.send_lookup(lookup)\n\n    if not lookup.result or not lookup.result.candidates:\n        print(\"No candidates found for the address. It might be invalid.\")\n    else:\n        first_candidate = lookup.result.candidates[0]\n        print(f\"Validated Address: {first_candidate.delivery_line_1}, {first_candidate.last_line}\")\n        print(f\"Components: City={first_candidate.components.city_name}, State={first_candidate.components.state_abbreviation}, ZIP={first_candidate.components.zipcode}\")\n        if first_candidate.metadata.latitude and first_candidate.metadata.longitude:\n            print(f\"Latitude: {first_candidate.metadata.latitude}, Longitude: {first_candidate.metadata.longitude}\")\n\nexcept exceptions.SmartyException as e:\n    print(f\"SmartyStreets API error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Exceeding API rate limits will result in a 429 'Too Many Requests' HTTP status code, leading to failed requests.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Intermittent 503 'Service Unavailable' errors can occur due to server rotation or temporary issues on the SmartyStreets side.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Manage expectations regarding direct feature development or dedicated support channels for bespoke requests. Rely primarily on the provided documentation and community resources.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the 'requests' library explicitly first: `pip install requests`, then `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.","error":"ModuleNotFoundError: No module named 'requests' (during 'pip install smartystreets_python_sdk')"},{"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.","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).","error":"smartystreets_python_sdk.exceptions.bad_credentials_exception.BadCredentialsException: Unauthorized: Either the supplied credentials were invalid, or the supplied signing authority was invalid."},{"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.","cause":"Your application has sent too many requests to the SmartyStreets API within a short period, exceeding your account's rate limit.","error":"HTTP 429 status code: 'Too Many Requests: The rate limit has been exceeded.'"}]}