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
- HTTP request
- HTTP response
- Master Address List
- Supplementary materials
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-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 |
Master Address List: Versioning (year, month, version)
The Master Address List is updated on a monthly 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. Please note: If a quarterly license is purchased, only the values 01, 04, 07 and 10 will be valid as these correspond to the first month of a quarter. |
| File version | The newest version of the file is automatically retrieved when the version is set to “latest.zip”. 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 download format
curl -vL "https://download.api.smarty.com/master-address-list/2023/10/premium-geo/ne/
latest.zip?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
-o NE_Premium_Geo_Master_Address_List.zip
Sample URLs for quarterly updates
Note that the month fields are 01,04,07 or 10.
"https://download.api.smarty.com/master-address-list/2023/01/premium-geo/al/
latest.zip?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
"https://download.api.smarty.com/master-address-list/2023/04/premium-geo/ak/
latest.zip?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
"https://download.api.smarty.com/master-address-list/2023/07/premium-geo/az/
latest.zip?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
"https://download.api.smarty.com/master-address-list/2023/10/premium-geo/ar/
latest.zip?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
Stands for SmartyKey "Extension"
The SmartyKeyExt field in the Master Address List (MAL) can be used in combination with the SmartyKey field along with some sort of separator like a | or a , to uniquely identity every address in the list.
Why do I need this?
SmartyKey is guaranteed to be unique for each delivery point, but not necessarily for each address. The USPS, one of our main sources of data, is in the business of delivering mail and packages. They only care about a specific delivery point. At times there are multiple different addresses that have the exact same delivery point for the USPS. These addresses may have the exact same SmartyKey. Now, in cases like these, we have a unique and consistent identifier by using the SmartyKeyExt field as well.
Why are most of the SmartyKeyExt values 0
An address with a SmartyKeyExt of 0 is what we call a "root" address. Most addresses that do NOT have Aliases or "Shared Delivery Points" ONLY have "root" addresses and will only have a SmartyKeyExt of 0. Any addresses that share a SmartyKey will have non Root addresses with a SmartyKeyExt greater than 0.
Why is the separator necessary?
The separator between the SmartyKey and SmartyKeyExt field is necessary because of the variable length of the SmartyKey field. If we were to just "add" the SmartyKeyExt field on to the SmartyKey field without a character separator, we could potentially build a valid SmartyKey of another address. For example, say the SmartyKey for address "2758 W 530 N Provo UT" is 12345 and the SmartyKeyExt is 7 for that particular address: If we just used 123457 as the SmartyKey and SmartyKeyExt that would match with address with a valid different SmartyKey at address "7880 S. 35th W. Idaho Falls ID" which is incorrect. What we need to do is to add a character separator between the SmartyKey and SmartyKeyExt like 12345|7. This would enable us to uniquely identify that specific address in the Master Address List.
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 and the ISO-2 is lower case:
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 |
Sample URLs for state/national requests
Wyoming sample request
"https://download.api.smarty.com/master-address-list/2023/01/premium-geo/wy/
latest.zip?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
National sample request
"https://download.api.smarty.com/master-address-list/2023/01/premium-geo/national/
latest.zip?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
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 |
COUNTY_FIPS |
COUNTY_FIPS |
COUNTY_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 |
Sample URLs for list type requests
Basic
"https://download.api.smarty.com/master-address-list/2023/01/basic/national/
latest.zip?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
Premium
"https://download.api.smarty.com/master-address-list/2023/01/premium/national/
latest.zip?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
Premium-geo
"https://download.api.smarty.com/master-address-list/2023/01/premium-geo/national/
latest.zip?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
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.