This page describes how to use the Download API to retrieve packages required to run local, on-site, or on-premises versions of the SmartyStreets APIs. Use of this API is restricted to authenticated users who have been granted access to the packages by purchasing an Enterprise plan.
Proper URL construction is required for all API requests. Here is an example URL:
Here is a more granular examination of the example above:
|Scheme||NOTE: non-secure |
|Path||See the package listing for exact values.|
|Query String||Authentication information, inputs, etc. Additional query string parameters are introduced in the next section.|
For additional information, please read our article about URL components.
HTTP requests can be categorized according to their HTTP method. Most HTTP requests are defined using the
GET method. We call these "get requests". Other common methods are
The following methods are supported by this API:
GET(for downloading a single package)
Note: Requests must be made using "Secret Key" authentication (Website key authentication is not allowed).
HTTP GET: Download a package
curl -vL "https://download.api.smartystreets.com/path/to/package?\ auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"\ -o "/path/to/output"
Each package will include a text file with installation instructions and documentation.
|Package Name||Package Information||URL Path (insert in request URL)|
|International Street Address API|
|International Street Address Data|
|US Street Address API|
|US Street Address Data|
|US ZIP Code API|
|US ZIP Code Data|
|US Autocomplete API|
|US Autocomplete Data|
|US Extract API|
Responses will have a
status header with a numeric value. This value is what you should check for when writing code to parse the response. The only response body that should be read and parsed is a
|Status Code||Response and Explanation|
|Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.|
|Payment Required: There is no active Enterprise subscription for the account associated with the credentials submitted with the request.|
|Not Found: The package you requested does not exist as specified. See the package listing for exact URL path values.|
|Method Not Allowed: Request method used is not allowed. See allowed request methods.|
|Temporary Redirect (success!): The |
In general, the following will serve as bare-minimum requirements/suggestions for running any of the software packages that are delivered by the Package Download API.
Certificate Authority: AddTrust External CA Root Fingerprint: 02faf3e291435468607857694df5e45b68851868 Supported Protocols: TLS 1.2 TLS 1.1 TLS 1.0 Cipher Suites: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA