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:
| Field | Description | Basic | Premium | Premium-geo |
|---|---|---|---|---|
SMARTY_KEY |
Persistent, unique identifier for an address. An address will retain its SmartyKey, even in the case of aliases and street name changes, and different addresses are guaranteed to have different SmartyKey values. | ✓ | ✓ | ✓ |
SMARTY_KEY_EXT |
This field can be used in combination with the SmartyKey field along with a separator like
| or , to uniquely identify every address returned from the API.
|
✓ | ✓ | ✓ |
FIRST_LINE |
Contains the delivery line (street address). This can include the composition of a primary number, street name, suffix, predirection, postdirection, secondary designator, and secondary number. | ✓ | ✓ | ✓ |
PRIMARY_NUMBER |
The house, PO Box, or building number. | ✓ | ✓ | |
PRE_DIRECTION |
Directional information before a street name (N, SW, etc.) | ✓ | ✓ | |
STREET_NAME |
The name of the street in each address. | ✓ | ✓ | |
STREET_SUFFIX |
Abbreviated value describing the street (St, Ave, Blvd, etc.) | ✓ | ✓ | |
POST_DIRECTION |
Directional information after a street name (N, SW, etc.) | ✓ | ✓ | |
SECONDARY_DESIGNATOR |
Describes the location within a complex/building (ste, apt, etc.) | ✓ | ✓ | |
SECONDARY_NUMBER |
Apartment, suite, or office number, if any. | ✓ | ✓ | |
URBANIZATION |
The neighborhood, or city subdivision; used with Puerto Rican addresses | ✓ | ✓ | |
CITY |
The USPS default city name for this 5-digit ZIP Code | ✓ | ✓ | ✓ |
STATE |
The two-letter state abbreviation. | ✓ | ✓ | ✓ |
ZIP |
The 5-digit ZIP code. | ✓ | ✓ | ✓ |
ZIP4 |
The 4-digit add-on code. | ✓ | ✓ | ✓ |
COUNTY_FIPS |
The 5-digit county Federal Information Processing Series code. It combines a 2-digit state FIPS code and a 3-digit county code managed by the ANSI (American National Standards Institute). | ✓ | ✓ | ✓ |
COUNTY |
The name of the county for the address | ✓ | ✓ | ✓ |
RDI |
Residential Delivery Indicator. Indicates whether an address is residential or commercial | ✓ | ✓ | |
CENSUS_BLOCK_CODE |
A 15-digit numerical code that identifies the block within a census tract | ✓ | ||
CENSUS_PLACE |
The geographical area for an address as defined by the US Census Bureau | ✓ | ||
NON_POSTAL |
Indicates if an address is part of Smarty’s proprietary database of non-USPS addresses. Please note that versions of the MAL in which this field is not present do not include these addresses. | ✓ | ||
SDP_TAG |
Indicates USPS “Shared Delivery Points”. Many distinct addresses can share a USPS delivery
point, such as a loft or basement apartment. These have their own distinct address.
|
✓ | ✓ | |
ALIAS_FLAG |
Indicates if an address is an alias of another address. Some locations can be referred to by several distinct street addresses. We designate the most recent and accurate address as “default” and all others are “aliases.” Aliases share the same SmartyKey as the default address to help you with database management. |
✓ | ✓ | |
SECONDARY_FLAG |
Indicates if an address is a secondary (Apt, Ste, etc…) | ✓ | ✓ | |
CONTAINS_SECONDARIES |
Indicates if an address contains secondary units | ✓ | ✓ | |
SECONDARY_COUNT |
Indicates how many secondary units an address contains | ✓ | ✓ | |
LINK_TO_PARENT_ADDRESS |
If an address is a secondary unit (Apt, Ste, etc…), this field will contain the SmartyKey of the base address | ✓ | ✓ | |
LATITUDE |
The horizontal component used for geographic positioning, ***based on the WGS84 coordinate system***. It is the angle between 0° (the equator) and ±90° (north or south) at the poles. It is the first value in an ordered pair of (latitude, longitude). A negative number denotes a location below the equator; a positive number is above the equator. Combining lat/long values enables you to pinpoint addresses on a map. | ✓ | ||
LONGITUDE |
The vertical component used for geographic positioning. It is the angle between 0° (the Prime Meridian) and ±180° (westward or eastward). It is the second number in an ordered pair of (latitude, longitude). A negative number indicates a location west of Greenwich, England; a positive number east. Combining lat/long values enables you to pinpoint addresses on a map. | ✓ | ||
PRECISION |
Indicates the precision of the latitude and longitude values.
|
✓ |
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"