Skip to main content

SmartyStreets.py

https://badge.fury.io/py/smartystreets.py.svg https://travis-ci.org/bennylope/smartystreets.py.svg?branch=master https://pypip.in/d/smartystreets.py/badge.svg

A wrapper for the SmartyStreets address validation and geolocation API.

Other Python libraries exist but skip out on multiple address submission and make opinionated decisions about how to transform the return data.

Features

SmartyStreets.py aims to provide a sane, tested, and feature complete wrapper to the SmartyStreets LiveAddress API, including address lookup for validation and geolocation, as well as zipcode lookup and validation.

Installation

SmartyStreets.py requires the requests library and will install it if it is found missing. Installed versions < 2.0 will be upgraded.:

pip install smartystreets.py

Basic usage

API client

Create a client instance with your key:

client = SmartyStreets(AUTH_ID, AUTH_TOKEN)

Create a client instance with SmartyStreets configuration options:

client = SmartyStreets(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 = SmartyStreets(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 geolocation

Where is it?:

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

Accuracy is subject to address inputs and available data.

Address verification

Is this a deliverable address?:

>>> address.confirmed
True

The value here does not necessarily mean this is an exact mail address (e.g. with apartment number). The SmartyStreets API will return a code indicating the complete DPV status.

Multiple addresses: input ID lookup

You can look up an address by the input_id parameter (provided you include one in the request):

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

The get method is used because the SmartyAddresses object’s default lookup is against the list index.

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.

History

0.2.3 (2015-03-15)

  • Bugfix in logging suppression header

0.2.2 (2015-01-29)

  • Adds strict JSON serialization to ensure all-but-specified fields are serialized into strings.

0.2.1 (2014-11-17)

  • Bugfix in plain string address input handling

0.2.0 (2014-10-23)

  • Added experimental async client

0.1.0 (2014-10-21)

  • First release on PyPI.

Metadata

Release files for smartystreets.py 0.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for smartystreets.py 0.2.3
File Size Uploaded Provenance Actions
smartystreets.py-0.2.3.tar.gz 21.4 kB Without provenance Details for smartystreets.py-0.2.3.tar.gz

Release files / smartystreets.py-0.2.3.tar.gz

Download URL smartystreets.py-0.2.3.tar.gz
Size 21.4 kB
Tags Source
SHA-256 checksum
How to use checksums
db429608fb4023651aa1aae973357f86138c82d8954bcec56a6f3dc45fa97f7f
BLAKE2b-256 checksum
How to use checksums
97dfc8bb9006977f65e688c56c43728dc5a8cf8397f8bbff31d16a1c851759e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for smartystreets.py 0.2.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page