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

View US Master Address List or US Parcel Boundary Data documentation.

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"

Sample curl request

Downloading a package

curl -vL "https://download.api.smarty.com/us-street-api/data/latest.tar.gz
		?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
		-o us-street-api
	

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-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).zip
parcel-data	Parcel Data	/parcel-data/(year)/(month)/(type)/(state or country)/(file version).zip

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.