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

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.

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?