Download API

This page describes how to use the Download API to retrieve packages required to run local, on-site, or on-premises versions of the Smarty (formerly SmartyStreets) APIs. Use of this API is restricted to authenticated users who have been granted access to the packages by purchasing an Enterprise plan.

Contents

  1. HTTP Request
    1. URL Composition
    2. Request Methods
    3. Package Listing
  2. HTTP Response
    1. Status Codes and Results
  3. Master Address List
    1. Versioning
    2. State or Country specifier
    3. Type
  4. Supplementary Materials
    1. Hardware and OS Requirements
    2. SSL/TLS Information

HTTP Request: URL Composition

Proper URL construction is required for all API requests. Here is an example URL:

https://download.api.smarty.com/path/to/package?auth-id=123&auth-token=abc

Here is a more granular examination of the example above:

URL Components Values Notes
Scheme https NOTE: non-secure http requests are not supported
Hostname download.api.smarty.com
Path /path/to/package See the package listing for exact values.
Query String ?auth-id=123&auth-token=abc 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 Request: Supported Methods/Verbs

Supported HTTP Methods

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 PUT, POST, and DELETE.

The following methods are supported by this API:

  • GET (for downloading a single package)

Note: Requests must be made using "secret key" authentication. (Embedded key authentication is not allowed.)

HTTP GET: Download a Package

curl -vL "https://download.api.smarty.com/path/to/package?\
	auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"\
	-o "/path/to/output"

Package Listing

Each package will include a text file with installation instructions and documentation.

Package Name Package Information URL Path (insert in request URL)
us-street-api US Street Address API /us-street-api/linux-amd64/latest.tar.gz
us-street-data US Street Address Data /us-street-api/data/latest.tar.gz
us-zipcode-api US ZIP Code API /us-zipcode-api/linux-amd64/latest.tar.gz
us-zipcode-data US ZIP Code Data /us-zipcode-api/data/latest.tar.gz
us-autocomplete-api US Autocomplete API /us-autocomplete-api/linux-amd64/latest.tar.gz
us-autocomplete-data US Autocomplete Data /us-autocomplete-api/data/latest.tar.gz
us-autocomplete-pro-api US Autocomplete Pro API /us-autocomplete-pro-api/linux-amd64/latest.tar.gz
us-autocomplete-pro-data US Autocomplete Pro Data /us-autocomplete-pro-api/data/latest.tar.gz
us-reverse-geo-api US Reverse Geo API /us-reverse-geo-api/linux-amd64/latest.tar.gz
us-reverse-geo-data US Reverse Geo Data /us-reverse-geo-api/data/latest.tar.gz
us-extract-api US Extract API /us-extract-api/linux-amd64/latest.tar.gz
master-address-list Master Address List /master-address-list/(year)/(month)/(type)/(state or country)/(file version)

HTTP Response: Status Codes and Results

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 200 response.

Status Code Response and Explanation
401 Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402 Payment Required: There is no active Enterprise subscription for the account associated with the credentials submitted with the request.
404 Not Found: The package you requested does not exist as specified. See the package listing for exact URL path values.
405 Method Not Allowed: Request method used is not allowed. See allowed request methods.
307 Temporary Redirect (success!): The Location response header will contain the actual download URL. This link will only last for a few seconds so it will be necessary for you to follow that redirect immediately. Passing the -L flag to the curl command (as shown in the examples on this page) will accomplish this automatically.

Master Address List: Versioning (Year, Month, Version)

The Master Address List is updated on a quarterly basis. The following versioning fields allows control over which version of a file is downloaded.

Year The year field specifies the year the file was generated and should be formatted in YYYY format, such as “2023”.
Month The month field also specifies a version referring to the month the file was generated. Numbers should be formatted with a leading zero if between 1 and 9, in MM format, like “08”. If a month is requested that does not align with a quarterly update, an HTTP 429 error will be returned.
File Version The newest version of the file is automatically retrieved when the version is set to “latest.tar.gz”. In some cases, a manual version can be specified to retrieve a specific version of a file as the master address list is sometimes generated multiple times in a month period. If a specific version of a file is desired, the format will present itself like “1.1:2023.08.B/” where the end character is incremented by version starting at ‘A’.

Master Address List: State or Country Specifier

Here the state or entire country is specified, according to the plan purchased. The following are valid options, note that territories are included:

AA AE AK AL AP AR AS AZ CA CO CT DC DE FL FM GA GU HI
IA ID IL IN KS KY LA MA MD ME MH MI MN MO MP MS MT NC
ND NE NG NJ NM NV NY OH OK OR PA PR PW RI SC SD TN TX
UT VA VI VT WA WI WV WY national

Master Address List: Type

Based on the master address list purchased, the type can be specified between basic, premium, or premium-geo. The table below highlights the differences of downloaded information based on the type included in the url:

Basic Premium Premium-Geo
SMARTY_KEY SMARTY_KEY SMARTY_KEY
FIRST_LINE FIRST_LINE FIRST_LINE
CITY CITY CITY
STATE STATE STATE
ZIP ZIP ZIP
ZIP4 ZIP4 ZIP4
COUNTRY_FIPS COUNTRY_FIPS COUNTRY_FIPS
COUNTY COUNTY COUNTY
PRIMARY_NUMBER PRIMARY_NUMBER
PRE_DIRECTION PRE_DIRECTION
STREET_NAME STREET_NAME
STREET_SUFFIX STREET_SUFFIX
POST_DIRECTION POST_DIRECTION
SECONDARY_DESIGNATOR SECONDARY_DESIGNATOR
SECONDARY_NUMBER SECONDARY_NUMBER
RDI RDI
SDP_TAG SDP_TAG
ALIAS_FLAG ALIAS_FLAG
SECONDARY_FLAG SECONDARY_FLAG
CONTAINS_SECONDARIES CONTAINS_SECONDARIES
SECONDARY_COUNT SECONDARY_COUNT
LINK_TO_PARENT_ADDRESS LINK_TO_PARENT_ADDRESS
LATITUDE
LONGITUDE
PRECISION

Hardware and OS Requirements

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.

  • 1+ gigabytes of RAM
  • Multiple CPU cores
  • A relatively recent version of the Linux kernel (basically something that can run compiled Go programs). Anything later than v2.6.32 should function without issues.

SSL/TLS Information

Use modern security software and cipher suites.

The leader in location data intelligence

Ready to get started?