Download API - reference
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
- HTTP request
- HTTP response
- Supplementary materials
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=abcHere 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-apiPackage 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/(country iso 3)-(administrative area iso 2)/(year)/(month)/(file type)/(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 and TLS information
Use modern security software and cipher suites.
About Us
We're Smarty, but people also refer to us as SmartyStreets.
SmartyStreets offers global address verification, address validation, and geocoding via API, bulk upload, and a collection of 3rd party integrations that transform how organizations handle address data.