smartystreets.py 2.0.2

API client

Create a client instance with your key:

from smartystreets import Client
client = Client(AUTH_ID, AUTH_TOKEN)

Create a client instance with SmartyStreets configuration options:

client = Client(AUTH_ID, AUTH_TOKEN, standardize=True, invalid=False,
            logging=False)

These options correspond to the x-standardize-only, x-include-invalid, and x-suppress-logging headers for opening up results to standardized but not necessarily deliverable addresses, including invalid delivery addresses, and toggling SmartyStreets API logging, respectively.

Since the SmartyStreets API only permits up to 100 addresses to be looked up at once the client will raise an exception if more than 100 are provided. You can turn off this functionality using the truncate_addresses option, which will silently truncate the list to the first 100 addresses:

client = Client(AUTH_ID, AUTH_TOKEN, truncate_addresses=True)

Address lookup

Simple address lookup:

client.street_address("100 Main St Richmond, VA")

Multiple simple street addresses:

client.street_addresses(["100 Main St Richmond, VA", "100 Main St Richmond, VA"])

Note that these are different function names.

You can also use dictionaries including detailed data:

client.street_address({
    'input_id': 'k1d8j',
    'street': '100 Main st',
    'city': 'Richmond',
    'state': 'VA',
    'candidates': 2,
})

And multiple detailed lookups:

client.street_addresses([
    {
        'input_id': 'k1d8j',
        'street': '100 Main st',
        'city': 'Richmond',
        'state': 'VA',
        'candidates': 2,
    }, {
        'input_id': 'z29ir',
        'street': '400 Main st',
        'city': 'Richmond',
        'state': 'VA',
        'candidates': 2,
    }
])

Return data

Just as important as a clean interface for working with the API is a helpful way of working with the returned data.

Returned data is presented as either a single SmartyAddress or a SmartyAddresses collection. Each is based on builtin types so that you always have access to the underlying data exactly as it was returned, but with added convenience methods.

>>> address = client.street_address("100 Main St Richmond, VA")
>>> address.location
(37.5436,-77.4453)

>>> address.confirmed
True

>>> addresses = client.street_address([{'input_id': '123', 'street': ...}])
>>> addresses.get('123')
{'input_id': '123', 'street': ... }

Zipcode lookup

TODO

Response errors

The following documented response codes raise specific exceptions based on a SmaryStreetsError class.

• 400 Bad input. Required fields missing from input or are malformed.

• 401 Unauthorized. Addressuthentication failure; invalid credentials.

• 402 Payment required. No Addressuthenticationctive subscription found.

• 500 Internal server error. General service foundailure; retry request.