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 US Master Address List is updated monthly. The following versioning fields allow control over which version of a file is downloaded.
| Year | The year field specifies the year the file was generated and should be formatted as YYYY, 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 US Master Address List is sometimes generated multiple times in a month. If a specific version of a file is desired, the format will appear as “2023.08.B/”, where the final 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 US Master Address List can be used in combination with the SmartyKey field, along with some sort of separator like a | or a , to uniquely identify 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, multiple addresses have the exact same delivery point with 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 value 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 fields is necessary because of the variable length of the SmartyKey field. If we were to just "add" the SmartyKeyExt field onto 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 an address with a valid different SmartyKey at the address "7880 S. 35th W., Idaho Falls, ID" which is incorrect.
What we need to do is add a character separator between the SmartyKey and SmartyKeyExt like 12345|7. This would enable us to uniquely identify that specific address in the US Master Address List.
Master address list: State or country specifier
Here, the state or the entire country is specified according to the purchased plan. The following are valid options. Note that territories are included and the ISO-2 is lowercase:
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 US Master Address List purchased, the type can be specified between basic, premium, or premium-geo. The table below highlights the differences in 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 with 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_2020 | 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 don’t 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, helping 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 latitude and longitude 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 indicates a location east of Greenwich, England. Combining latitude and longitude values enables you to pinpoint addresses on a map. | ✓ | ||
PRECISION | Indicates the precision of the latitude and longitude values.
Note: Concerning addresses for which the ZIP9 or higher precision is not available, the ZIP# precision is interpolated based on neighboring addresses. Thus, ZIP7 is an average of all the lat/long coordinates of nearby ZIP Codes that share those first 7 digits. | ✓ |
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"
Was this helpful?