US Master Address List
Contents
- Master Address List: Versioning (year, month, version)
- Stands for SmartyKey "Extension"
- Master Address List: State or country specifier
- Master Address List: Type
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 “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 |
nh |
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"