New 42-day free trial Get it now
Smarty

Bulk Address Validation: Command-line interface

If you have large lists of addresses to process and some experience with the command line, our Command-Line Interface (CLI) is simple and straightforward to set up. It can process millions of either US or international (non-US) addresses very quickly, and can also enrich US addresses with property, financial, and secondary address data. Each address processed will count as one "address lookup" from the corresponding subscription: US Address Verification, International Address Verification, or US Property Data. (If you're not yet familiar with the command line, try our Web Interface. It can process up to 500,000 US or international addresses at once.)

Contents

  1. Scripting and automation
  2. Download
  3. Installation
  4. Preparing your input file
  5. Using the interface
  6. The output file
  7. The log file
  8. Command-line parameters
  9. Examples
  10. Updates
  11. Troubleshooting
  12. US address output fields
  13. US ZIP Code output fields
  14. International address output fields
  15. International postal code output fields
  16. Usage tips

Scripting and automation

The CLI is designed for manual, user-run batch processing. It isn’t supported for unattended or automated production workflows because updates are delivered as downloadable releases.

If you need automated processing in deployed software, use our supported SDKs. For direct HTTP integration, use the US Street Address API documentation.

This constraint is based on how we provide software updates for this tool.

If you need to process address data from deployed software running autonomously, we recommend our officially supported SDKs.

For those seeking an even more direct HTTP integration, we also provide detailed documentation for the US Street Address API.

Download

You can download (free) the Command-Line Interface for the following platforms:

Installation

  1. First, download the package for your platform.
  2. Next, extract the archive (for example, to your Desktop).

You’ll see a folder that includes:

  • smartylist — the CLI executable (run it from your terminal)
  • sample-input.csv — example input
  • sample-output.csv — example output
  • change-log.txt — release notes
  • DO-NOT-README.txt — important notes

Power users: Feel free to copy or move smartylist to wherever is convenient. On Linux, you may place it in a directory on your $PATH (for example, /usr/local/bin).

Preparing your input file

Save your addresses as CSV or PSV (comma- or pipe-delimited). Include a header row with field names spelled exactly as shown below. More complete input typically produces better results.


US addresses

For US addresses, use one of these combinations of columns:
street | city | state | zipcode
street | city | state
street | zipcode
address (entire address in a single field)

If you have secondary information (apartment/suite/etc) in a separate column, label that column "secondary." Such a column can be added to any of the first three combinations shown above. For example:
street | secondary | city | state | zipcode

street city state zipcode
11310 Old Seward Highway Anchorage AK 99515
3211 Edwards Lake Pkwy Birmingham AL
11219 N Rodney Parham Road 72212
4507 North US Highway 89 Flagstaff AZ 86004

International addresses

Use one of these combinations of columns:
country | address1 | locality | administrative_area | postal_code
country | address1 | locality | administrative_area
country | address1 | postal_code
country | freeform (entire address except country in a single column)

Important: To return geocodes (latitude/longitude) in the response for a particular address, provide a column named geocode with a value of true. Alternatively, you could use the -geocode command-line parameter to return geocodes for the entire batch.

country address1 locality administrative_area postal_code geocode
AUS 200 River Terrace Kangaroo Point Queensland 4169 true
DEU Hainichener Strasse 64 Freiberg Sachsen true
PYF 21 Allée Pierre Loti Papeete 98714 false
RUS ул. Фурштатская, д. 13 191028 true
JPN きみ野 6-1-8 大和市 神奈川県 242-0001 false

For either US or international addresses, you can include fields that contain non-address data, like an ID number or business name. Your input data will be returned untouched as part of the output. The column names for non-address data should not conflict with address data column names.

US Enrichment Data

For US Enrichment, use one of these combinations of columns, depending on whether you’re performing a query by SmartyKey or searching by address:

By SmartyKey:

  • smarty_key

By address (freeform):

  • street or freeform

By address (components):

  • street | city | state | zipcode

Optional: include etag to check whether a record has changed. If the etag hasn’t changed, the CLI returns an empty record (see US Enrichment docs).

Notes:

  • Property financial data has limited support and will only return the base property data.
  • Secondary data has limited support and will only return the root address and secondary count.

Consider the following examples of US Enrichment input files:

smarty_key
123456
7891011

smarty_key etag
123456 AAHQCAIDAYBQIAQC
7891011 AIAAQBAHBAAQ6DB

freeform
1400 Sandhill Dr Orem UT
123 N Pole Dr Outback AK 90123

street city state zipcode
1400 Sandhill Dr Orem UT
123 N Pole Dr Outback AK 90123


Final consideration

Avoid blank lines (except at the end). Blank lines can shift line numbers, which makes it harder to map results back in a spreadsheet. If you need spacing, include an ID column with a unique value on every row.

Using the interface

Open your terminal and use the "change directory" command to navigate to where your Command Line Interface files reside. This is what that might look like:

Windows:

cd /Users/[username]/Desktop/smartylist_windows_latest

Mac:

cd ~/Desktop/smartylist_osx_latest

On Windows, we recommend running this command as an administrator.

Three specific command-line parameters are required in order to process a list: -auth-id, -auth-token, and -input. (To find your -auth-id and -auth-token, open the API Keys tab of your account and look under the heading of Secret Keys.) The -input parameter specifies the location of your input file. If you placed your input file inside the SmartyList folder, the complete command to process it might look like this:

Windows:

smartylist -auth-id="123" -auth-token="Abc" -input="your_file"

Mac:

./smartylist -auth-id="123" -auth-token="Abc" -input="your_file"

We recommend starting with a small file to confirm configuration and input field mapping. The CLI displays detected settings and field types before processing, then prompts for confirmation.

To select an API, add -api (see parameters).

To run a file through a particular API, use the -api parameter. See parameters.

The output file

By default, the CLI writes output next to the input file and appends -output to the filename. You can set a different path with -output.

When viewing the output file, you will see all of your original data fields on the left, followed by an empty field, followed by our output fields on the right, with field names in brackets.

The CLI output fields for US addresses are very similar to the raw output from the US Street Address API, though in a different order. For an explanation of the US output fields, please see Address Output Fields.

The CLI output fields for international addresses are likewise very similar to the raw output from the International Street Address API, with these differences:

  • There is one new field in the CLI output for international addresses: line_number. This is simply a row numbering scheme to help keep track of their original output order.

The CLI output fields for US Enrichment are similar to the API's raw output, with the following differences:

  • There is one new field in the CLI output: line_number. This is simply a row numbering scheme to help keep track of their original output order.
  • Property financial data has limited support and will only return the base property data.
  • Secondary data has limited support and will only return the root address and secondary count.

The log file

Every time you process a list with the Command-Line Interface, it will produce a log file and place it next to the corresponding input file. The name of the log file will follow this pattern: 

[name-of-input-file]-log_[date-time]

It includes the pre-run configuration plus step-by-step processing details. If something fails, check the log first. Support may request it when troubleshooting.

Command-line parameters

Here we list all the command-line parameters that can be used with our Command-Line Interface.

The first three parameters listed below are all that are required to process a list. The others are optional; you can employ them to customize the tool's functionality.

To use them, simply list them when you run smartylist at the command prompt, following this model: 

smartylist -[parameter] -[another-parameter]
  • -auth-id="123"

    The auth-id value (or name of environment variable) to use for API requests.

  • -auth-token="Abc"

    The auth-token value (or name of environment variable) to use for API requests.

  • -input="path/to/the/input/file"

    The path to the input file, which has addresses you want to validate.

  • -output="/path/to/the/output/file"

    If provided, this is where the bulk validation tool will place the output file containing the results of processing your input file. If not provided, the tool will place the output alongside the input.

  • -log="path/to/the/log/file"

    If desired, you can tell the bulk validation tool where to put the diagnostic log file. If this parameter isn't provided, the tool will place the log file alongside the input file.

  • -api="name-of-api"

    Valid values are "us-street", "international-street", and "us-enrichment". If this parameter isn't provided, "us-street" will be assumed by default. If an invalid value is provided, an error will be thrown, and the process won't run.

  • -license="name-of-license"

    Use this parameter to specify the license to use for the chosen input file. Valid values can be found in your subscriptions page, under the appropriate subscription.

  • -base-url="http://www.your-site.com"

    The base URL to use for API requests if you're pointing to an on-site API installation. If you're using our regular cloud service, this parameter isn't necessary.

  • -format="format-value"

    This parameter should only be used when processing US addresses. When you provide this parameter, the tool will override the default output format. Valid values are the same as those for the format parameter of the US Street Address API. If you would like to set the formatting to the Project USA Format, we recommend setting format="project-usa”.

  • -match="match-value"

    This parameter should only be used when processing US addresses. When you provide this parameter, the tool will override any values in the match column of the input file. Valid values are the same as the match parameter for the US Street Address API. The default is match="enhanced", so if you're not using one of our newer "Core" licenses, you will need to specify the match type.

  • -county-source="county-source-value"

    This parameter should only be used when processing US addresses. When you provide this parameter, the tool will override any values in the match column of the input file. Valid values are the same as the county_source parameter for the US Street Address API.

  • -enrichment-dataset=”name-of-enrichment-dataset”

    This parameter should only be used with the us-enrichment API to target a specific enrichment dataset. See supported datasets in the US Enrichment documentation. Examples: property, or risk, or geo-reference, etc.

  • -enrichment-data-subset=”name-of-enrichment-data-subset”

    This parameter should only be used with the us-enrichment API, and the enrichment dataset contains subsets. See supported data subsets in the US Enrichment documentation. Examples: principal, or 2010, or 2020, etc.

  • -enrichment-include=”comma separated property groups or attribute names”

    This parameter is used to include only specific property groups or attributes in the output file.
    It's only applicable with the us-enrichment API and the property dataset and principal data subset. Example value: group_location,assessed_value
    See the US Address Enrichment API documentation for usage details.

  • -enrichment-exclude=”comma separated property groups or attribute names”

    This parameter is used to exclude specific property groups or attributes from the output file.
    It's only applicable with the us-enrichment API and the property dataset and principal data subset. Example value: tax_assess_year
    See the US Address Enrichment API documentation for usage details.

  • -geocode

    This parameter will return geocodes for International Street queries. Otherwise, the geocodes (lat/long) columns will have a value of 0.

  • -rate-limit=[integer]

    With this command-line parameter, you can specify how many addresses to send to the API per second. For example: -rate-limit=300 will cause the CLI to send 300 addresses per second. Valid values are positive integers. If a rate-limit value of less than 1 or a non-integer is given, an error will be thrown, and the CLI process won't run. If this parameter isn't used, no rate limit will be applied.

  • -proxy="www.your-proxy.com"

    The URL of your proxy, if one has been configured for your network. In most cases, this flag isn't necessary.

  • -silent

    Tells the tool to squelch all diagnostic output and process the list without a confirmation prompt if possible. (No value needed.)

  • -timeout

    If your network connection is slow, you may receive timeout errors during execution, such as context deadline exceeded (Client.Timeout or context cancellation while reading body). This parameter can help prevent those errors by allowing more time for the response to be received from the server. The default value is 5 (5 seconds). (No value needed.)

  • -version

    When you provide this parameter, the tool simply prints the version of the application to stdout and exits. (No value needed.)

Examples

US Street:


smartylist -api us-street -auth-id SMARTY_AUTH_ID -auth-token SMARTY_AUTH_TOKEN -input us-file.csv

(Call the US Street API with the auth ID and token as environment variables.)

smartylist -api us-street -auth-id abcdefg -auth-token abcdefg -match enhanced -license us-rooftop-geocoding-cloud -input us-file.csv

(Call the US Street API with the auth ID and token as actual values. Use match=enhanced for the entire run. Use a specific license.)

International Street:


smartylist -api international-street -auth-id SMARTY_AUTH_ID -auth-token SMARTY_AUTH_TOKEN -geocode -input inter-file.csv

(Call the International Street API with the auth ID and token as environment variables. Return geocodes.)

US Enrichment


smartylist -api us-enrichment -input smartykeys.txt -auth-id SMARTY_AUTH_ID -auth-token SMARTY_AUTH_TOKEN -enrichment-dataset property -enrichment-data-subset principal

(Call the US Enrichment API with the auth ID and token as environment variables. Access the property dataset and the principal data subset.)


smartylist -api us-enrichment -input smartykeys.txt -auth-id SMARTY_AUTH_ID -auth-token SMARTY_AUTH_TOKEN -enrichment-dataset geo-reference -enrichment-data-subset 2010

(Call the US Enrichment API with the auth ID and token as environment variables. Access the geo-reference dataset and the 2010 data subset.)


smartylist -api us-enrichment -input smartykeys.txt -auth-id SMARTY_AUTH_ID -auth-token SMARTY_AUTH_TOKEN -enrichment-dataset risk

(Call the US Enrichment API with the auth ID and token as environment variables. Access the risk dataset.)

Updates

Try this command at the command prompt:

smartylist -version

(Mac/Linux users may need to insert ./ in front of the word smartylist.)

If the latest version number doesn't match what you see, you might be missing out on recent improvements and should probably download and install the latest version.

New releases are announced in our open-source Changelog repository.

Troubleshooting

If Excel doesn’t display some characters correctly

The Smarty CLI outputs a comma-delimited or pipe-delimited file with correct characters, in many languages, including all characters in the UTF-8 character set. If Excel isn't displaying some characters correctly, we recommend this procedure:

  1. Instead of opening the output file directly with Excel (e.g., by double-clicking on the file), open Excel and open a brand new, empty file.
  2. In Excel, go to the File menu and select “Import.”
  3. During the import process, choose the comma-delimited or pipe-delimited file that the Smarty CLI output.
  4. Also, during the import process, be sure to tell Excel that the "File origin" or character set you want to use is "Unicode (UTF-8)."
  5. Finally, you will be given the opportunity to set the file delimiters. Choose the one that makes the preview look right (probably either comma or pipe).

4 more ways to validate in bulk

  1. Web Interface Tool

  2. Microsoft Excel Add-In

  3. Google Sheets Add-On

  4. QGIS mapping software

US address output fields

All output fields correspond to the US Street Address API Fields, but are arranged in a more useful order by the Bulk Address Validation Tool Web Interface and the Command-Line Interface.

Field name Type Definition
Input fields several varchar(50) All fields from the corresponding input line.
(blank field) varchar(0) This field intentionally left blank. No, really, it's just blank.
[sequence] int Incrementing sequence number which refers to the input record number.
[summary] varchar(50) Indicates whether the input address matched a valid USPS address.
  • No match. The address is invalid.
  • Match-mailable. The address is valid and can receive mail.
  • Match-vacant. The address is valid but vacant.
  • Match-inactive. The address is valid but inactive.
  • Match-non-postal. A match was made to a valid non-postal address.
  • No match - PO Box only. The ZIP Code is PO Box delivery only.
[addressee] varchar(50) The name of the person or company at this address. This value is taken directly from the addressee input field. Very rarely, this field might be filled automatically based on the USPS address record.
[delivery_line_1] varchar(50) Contains the first delivery line (usually the street address). This can include any of the following:
  • urbanization (Puerto Rico only)
  • primary number
  • street predirection
  • street name
  • street suffix
  • street postdirection
  • secondary designator
  • secondary number
  • extra secondary designator
  • extra secondary number
  • PMB designator
  • PMB number
[delivery_line_2] varchar(50) The second delivery line (if needed); it is common for this field to remain empty.
[city_name] varchar(64) The USPS-preferred city name for this particular address, or an acceptable alternate if provided by the user
[state_abbreviation] char(2) The two-letter state abbreviation
[full_zipcode] char(10) The nine-digit ZIP Code
[notes] varchar(250) Describes steps taken to verify and standardize the address and other information about it.
[county_name] varchar(64) The name of the county in which the address is located
[rdi] varchar(12) Residential delivery indicator (residential or commercial)

residential — The address is a residential address.
commercial — The address is a commercial address.
unknown — The RDI of the address is currently unknown.
[latitude] decimal(9,6) 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] decimal(9,6) The vertical component used for geographic positioning, ***based on the WGS84 coordinate system***. 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] varchar(18) Indicates the precision of the latitude and longitude values.

Unknown — Coordinates not known, possibly because address is invalid
None — Coordinates are not provided for this address. Military addresses such as APO, FPO, and DPO do not provide coordinates.
Zip5 — Accurate to a 5-digit ZIP Code level (least precise)
Zip6 — Accurate to a 6-digit ZIP Code level
Zip7 — Accurate to a 7-digit ZIP Code level
Zip8 — Accurate to an 8-digit ZIP Code level
Zip9 — Accurate to a 9-digit ZIP Code level (most precise with the basic subscription)
Parcel — Accurate to the centroid of a property parcel. Requires the US Rooftop Geocoding subscription.
Rooftop — Accurate to the rooftop of a structure for this address. Requires the US Rooftop Geocoding subscription.

Note: Concerning addresses for which the ZIP9 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.
[dpv_match_code] varchar(1) Status of the Delivery Point Validation (DPV). This lets you know if the USPS delivers mail to the address.

Y — Confirmed; entire address is present in the USPS data. To be certain the address is actually deliverable, verify that the dpv_vacant field has a value of N and the active field has a value of Y.
(e.g., 1600 Amphitheatre Pkwy Mountain View, CA)
N — Not confirmed; address is not present in the USPS data.
S — Confirmed by ignoring secondary info; the main address is present in the USPS data, but the submitted secondary information (apartment, suite, etc.) was not recognized.
(e.g., 62 Ea Darden Dr Apt 298 Anniston, AL)
D — Confirmed but missing secondary info; the main address is present in the USPS data, but it is missing secondary information (apartment, suite, etc.).
(e.g., 122 Mast Rd Lee, NH)
[blank] — The address is not present in the USPS data.
[dpv_footnotes] varchar(32) Information related to the delivery point validation of this address. All these footnotes have a length of 2 characters, and there may be up to 14 footnotes.

AA — Street address, city, state, and ZIP are all valid.
(e.g., 2335 S State St Ste 300 Provo UT)
A1 — Address is invalid.
(e.g., 3214 N University Ave New York NY)
BB — Entire address is valid.
(e.g., 2335 S State St Ste 300 Provo UT)
CC — The submitted secondary information (apartment, suite, etc.) was not recognized.
(e.g., 2335 S State St Ste 500 Provo UT)
F1 — Military or diplomatic address
(e.g., Unit 2050 Box 4190 APO AP 96278)
G1 — General delivery address
(e.g., General Delivery Provo UT 84601)
M1 — Primary number (e.g., house number) is missing.
(e.g., N University Ave Provo UT)
M3 — Primary number (e.g., house number) is invalid.
(e.g., 16 N University Ave Provo UT)
N1 — Address is missing secondary information (apartment, suite, etc.).
(e.g., 2335 S State St Provo UT)
PB — PO Box street style address.
(e.g., 555 S B B King Blvd Unit 1 Memphis TN 38103)
P1 — PO, RR, or HC box number is missing.
(e.g., Dept 126 Denver CO 802910126)
P3 — PO, RR, or HC box number is invalid.
(e.g., PO BOX 60780 FAIRBANKS AK 99706)
RR — Confirmed address with private mailbox (PMB) info.
(e.g., 3214 N University Ave #409 Provo UT)
R1 — Confirmed address without private mailbox (PMB) info.
(e.g., 3214 N University Ave Provo UT)
R7 — Confirmed as a valid address that doesn't currently receive US Postal Service street delivery.
(e.g., 6D Cruz Bay St John VI 00830)
U1 — Address has a "unique" ZIP Code.
(e.g., 100 North Happy Street 12345)

Here are some common combinations:
  • AABB - ZIP, state, city, street, and primary number match.
  • AAM1 - ZIP, state, city, and street match, but the primary number is missing.
  • AAM3 - ZIP, state, city, and street match, but the primary number is invalid.
  • AAN1 - ZIP, state, city, street, and primary number match, but there is secondary information such as apartment or suite that would be helpful.
  • AABBR1 - ZIP, state, city, street, and primary number match. Address confirmed without private mailbox (PMB) info.
[footnotes] varchar(24) Indicates which changes were made to the input address. Footnotes are delimited by a # character. See the footnotes table below for details.
[enhanced_match] varchar(64) When an address is submitted with the match parameter set to "enhanced", this field will contain additional information about the result. Multiple values may be present, separated by commas. Additional values will be added from time to time. The current possible values are:

(blank) — Enhanced matching was not performed.
none — Enhanced matching was performed but no address match was found.
non-postal-match — Enhanced matching was performed and a match was found within additional, non-postal address data.
postal-match — Enhanced matching was performed and a match was found within postal address data.
missing-secondary — The address should have a secondary (e.g. apartment), but none was found in the input.
unknown-secondary — The provided secondary information did not match a known secondary within the address data.
ignored-input — The provided input contained information that was not used for a match.
[county_fips] char(5) The 5-digit county FIPS (Federal Information Processing Standards) code. It is a combination of a 2-digit state FIPS Code and a 3-digit county code assigned by the NIST (National Institute of Standards and Technology).
[record_type] char(1) Indicates the type of record that was matched. Only given if a DPV match is made.

F — Firm; the finest level of match available for an address.
(e.g., Julie Julia 11300 Center Ave Gilroy CA 95020-9257)
G — General Delivery; for mail to be held at local post offices.
(e.g., General Delivery Provo UT 84601)
H — High-rise; address contains apartment or building sub-units.
(e.g., 1600 Pennsylvania Ave SE Washington DC 20003-3228)
P — Post Office box
(e.g., PO Box 4735 Tulsa OK 74159-0735)
R — Rural Route or Highway Contract; may have box number ranges.
(e.g., RR 2 Box 4560 Anasco PR 00610-9393)
S — Street; address contains a valid primary number range.
(e.g., 16990 Monterey Rd Lake Elsinore CA 92530-7529)
[blank] — No record type because address did not make a valid DPV match
[zip_type] varchar(32) Indicates the type of the ZIP Code for the address that was matched. Only given if a 5-digit match is made.

Unique — The ZIP Code consists of a single delivery point, pertaining to a US Postal Service customer (like a large business or government agency) that routes all of its own mail internally.
Military — The ZIP Code pertains to military units and diplomatic organizations, often in foreign locations.
POBox — The ZIP Code is a PO Box ZIP Code and is assigned to a collection of Post Office Boxes.
Standard — The ZIP Code does not pertain to any of the above categories.
[carrier_route] char(4) The postal carrier route for the address. Consists of a one-letter prefix followed by a three-digit route designator.
(e.g., C007, R123)

C — Carrier Route (commonly termed "City Route")
R — Rural Route
H — Highway Contract Route
B — Post Office Box Section
G — General Delivery Unit

Routes C770 through C779 pertain to PO Box Street Addresses.
[congressional_district] char(2) The congressional district to which the address belongs. Output will be two digits from 01 - 53 or "AL." "AL" means that the entire state (or territory) is covered by a single congressional district. These include: Alaska, Delaware, Montana, North Dakota, South Dakota, Vermont, Wyoming, Washington DC, Virgin Islands, and other territories.
[building_default_indicator] char(1) Indicates whether the address is the "default" address for a building; for example, the main lobby.

Y — Yes
N — No
[elot_sequence] varchar(4) eLOT (Enhanced Line of Travel) 4-digit sequence number
[elot_sort] varchar(4) eLOT (Enhanced Line of Travel) product was developed to give mailers the ability to sort their mailings by line of travel sequence.

A — Ascending
D — Descending
[blank] — Address was not submitted for eLOT.
[time_zone] varchar(48) Indicates the common name of the standard time zone associated with the address. This will always be the standard time zone name (e.g., "Mountain"), never the daylight saving variant (e.g., "MDT" or "Mountain Daylight Time").

Valid Responses
Alaska, Atlantic, Central, Eastern, Hawaii, Mountain, None, Pacific, Samoa, UTC+9, UTC+10, UTC+11, UTC+12
[utc_offset] decimal(4,2) Indicates the number of hours the standard time zone is offset from Universal Time Coordinated (UTC), the international time standard, also known as Greenwich Meridian Time (GMT).

Note: This is the standard time offset. If the dst field is true and daylight saving time is currently in effect at the address, the actual offset would be one hour greater (e.g., Mountain Standard Time is UTC-7, but Mountain Daylight Time is UTC-6).

Valid Responses
-11, -10, -9, -8, -7, -6, -5, -4, 0, 9, 10, 11, 12
[dst] char(5) Indicates if the time zone observes daylight saving time, adjusting clocks forward and back with the seasons. Use this field in conjunction with [time_zone] and [utc_offset] to determine the current local time at an address. For example, Arizona and Hawaii do not observe daylight saving time, while most other US states do.

true — Time zone observes daylight saving time. During DST periods, add one hour to the [utc_offset] to get the current offset.

If dst is absent from the response, then the time zone does not observe daylight saving time, and the [utc_offset] value applies year-round.
[dpv_cmra] varchar(1) Indicates whether the address is associated with a Commercial Mail Receiving Agency (CMRA), also known as a private mailbox (PMB) operator. A CMRA is a business through which USPS mail may be sent or received, for example the UPS Store and Mailboxes Etc.

Y — Address is associated with a valid CMRA.
N — Address is not associated with a valid CMRA.
[blank] — Address was not submitted for CMRA verification.
[ews_match] char(5) Early warning system flag; a positive result indicates the street of the address is not yet ready for mail delivery and that the address will soon be added to the master ZIP+4 file in the coming weeks or months. This commonly occurs for new streets or streets undergoing a name change.

true — The address was flagged by EWS, preventing a ZIP+4 match.
[blank] — Address was not flagged by EWS.
[lacslink_indicator] varchar(1) Indicates whether there is an address match in the LACSLink database.

Y — LACS record match; a new address could be furnished because the input record matched a record in the master file.
S — LACS record - secondary number dropped; the record is a ZIP+4 street level or high-rise match. The input record matched a master file record, but the input address has a secondary number and the master file record did not.
N — No match; a new address could not be furnished; the input record could not be matched to a record in the master file.
F — False positive; a false positive record was detected.
[blank] — No LACSLink lookup attempted.
[lacslink_code] varchar(2) The reason for the LACSLink indication that was given (below)

A — Match: Address provided. LACSLink record match was found, and a converted address was provided.
00 — No Match. No converted address. No soup for you!
09 — Match: No new address. LACSLink matched an input address to an old address, which is a "high-rise default" address; no new address was provided.
14 — Match: No conversion. Found a LACSLink record, but couldn't convert the data to a deliverable address.
92 — Match: Dropped secondary number. LACSLink record was matched after dropping the secondary number from input.
[blank] — No LACSLink lookup attempted.
[suitelink_match] varchar(5) Indicates a match (or not) to the USPS SuiteLink data. SuiteLink attempts to provide secondary information such as "suite" or "apartment" whenever there is a match based on address and company name.

true — There was a SuiteLink match and the result is provided.
false — There was no SuiteLink match.
[dpv_vacant] varchar(1) Indicates that a delivery point was active in the past, but is currently vacant (in most cases, unoccupied over 90 days) and is not receiving deliveries. This status is often obtained when mail receptacles aren't being emptied and are filling up, so mail is held at the post office for a certain number of days before the delivery point is marked vacant.

Y — Address is vacant.
N — Address is not vacant.
[blank] — Address was not submitted for vacancy verification.
[active] varchar(1) Indicates whether the address is active, or "in-service" according to the USPS. Examples: New developments may have addresses but will be "inactive" until somebody moves in. Or, after Hurricane Katrina, addresses in the affected area were marked as inactive for a time. Residents may also mark their own mailboxes as inactive for privacy and other reasons.

Y — Address is active.
N — Address is inactive.
[blank] — Activity status is not known by the USPS.
[urbanization] varchar(64) The neighborhood, or city subdivision; used with Puerto Rican addresses.
[primary_number] varchar(30) The house, PO Box, or building number
[street_name] varchar(64) The name of the street
[street_predirection] char(16) Directional information before a street name (N, SW, etc.)
[street_postdirection] char(16) Directional information after a street name (N, SW, etc.)
[street_suffix] char(16) Abbreviated value describing the street (St, Ave, Blvd, etc.)
[secondary_number] varchar(32) Apartment or suite number, if any
[secondary_designator] varchar(16) Describes location within a complex/building (Ste, Apt, etc.)
[extra_secondary_number] varchar(32) Descriptive information about the location of a building within a campus
(e.g., E-5 in "5619 Loop 1604, Bldg E-5, Ste 101 San Antonio TX")
[extra_secondary_designator] varchar(16) Description of the location type within a campus
(e.g., Bldg, Unit, Lot, etc.)
[pmb_designator] varchar(16) Private mailbox unit designator, assigned by a CMRA
[pmb_number] varchar(16) The private mailbox number assigned by a CMRA; this value is not verified by Smarty.
[default_city_name] varchar(64) The default city name for this 5-digit ZIP Code
[zipcode] char(5) The 5-digit ZIP Code
[plus4_code] varchar(4) The 4-digit add-on code (more specific than 5-digit ZIP)
[delivery_point] char(2) The last two digits of the house/box number, unless an "H" record is matched, in which case this is the secondary unit number representing the delivery point information to form the delivery point barcode (DPBC).
[delivery_point_check_digit] char(1) Correction character, or check digit, for the 11-digit barcode
[last_line] varchar(50) City, state, and ZIP Code combined
[delivery_point_barcode] varchar(12) 12-digit POSTNET™ barcode; consists of 5-digit ZIP Code, 4-digit add-on code, 2-digit delivery point, and 1-digit check digit.

Footnotes

This table describes possible values in the [footnotes] field.

(Example addresses may be changed at any time due to the nature of the data.)

Value Definition Details
A# Corrected ZIP Code The address was found to have a different 5-digit ZIP Code than the one submitted. The correct ZIP Code is shown in the zipcode field.
(e.g., 4800 Fairmount Ave Kansas City MO 64111)
B# Corrected city/state spelling The spelling of the city name and/or state abbreviation in the submitted address was found to be different than the standard spelling. The standard spellings are shown in the city_name and state_abbreviation fields.
(e.g., 2410 University Ave W #614 St Paul, MN)
C# Invalid city/state/ZIP The ZIP Code in the submitted address could not be found because neither a valid city and state, nor valid 5-digit ZIP Code was present. Smarty recommends that the customer check the accuracy of the submitted address.
(e.g., 200 Camp Drive 25816)
D# No ZIP+4 assigned This address is not present in the USPS data. Smarty recommends that the customer check the accuracy of the submitted address.
(e.g., 2288 S Bethel Ave Sanger, CA 93657)
E# Same ZIP for multiple Multiple records were returned, with the same 5-digit ZIP Code.
(e.g., 1 Rosedale Baltimore MD)
F# Address not found The address, exactly as submitted, could not be found in the city, state, or ZIP Code provided. Some possible reasons for this are: the primary number is missing, the street is missing, or the street is too badly misspelled to understand.
(e.g., 2600 Rafe Lane Jackson MS 39201)
G# Used addressee data Information in the addressee input field was determined to be part of the address. It was moved out of the addressee field and incorporated into the street field.
(e.g., 97 Taylor St apt 3F Taylor Manchester NH)
H# Missing secondary number The address as submitted is missing a secondary number (apartment, suite, etc.). Smarty recommends that the customer check the accuracy of the submitted address and add the missing secondary number to ensure the correct Delivery Point Barcode (DPBC).
(e.g., 109 Wimbledon Sq Chesapeake VA 23320)
I# Insufficient/ incorrect address data More than one ZIP+4 Code was found to satisfy the address as submitted. The submitted address did not contain sufficiently complete or correct data to determine a single ZIP+4 Code. Smarty recommends that the customer check the accuracy and completeness of the submitted address. For example, a street may have a similar address at both the north and south ends of the street.
(e.g., 1 Rosedale Baltimore MD 21229)
J# Dual address The input contained two addresses. For example: 123 MAIN ST PO BOX 99.
(e.g., PO Box 38606 30th Street Train Station Philadelphia PA 19104)
K# Cardinal rule match Although the address as submitted is not valid, we were able to find a match by changing the cardinal direction (North, South, East, West). The cardinal direction we used to find a match is found in the components.
(e.g., 315 W Cesar Chavez St Austin TX)
L# Changed address component An address component (i.e., directional or suffix only) was added, changed, or deleted in order to achieve a match.
(e.g., 213 S QUANAH RUSSELLVILLE AR 72801)
LL#
or
LI#		 Flagged address for LACSLink The input address matched a record that was LACS-indicated, that was submitted to LACSLink for processing. This does not mean that the address was converted; it only means that the address was submitted to LACSLink because the input address had the LACS indicator set.
M# Corrected street spelling The spelling of the street name was changed in order to achieve a match.
(e.g., 3308 Fountainviuw Monsey NY)
N# Fixed abbreviations The delivery address was standardized. For example, if STREET was in the delivery address, Smarty will return ST as its standard spelling.
(e.g., 2438 Brown Avenue Knoxville TN 37917)
O# Multiple ZIP+4; lowest used More than one ZIP+4 Code was found to satisfy the address as submitted. The lowest ZIP+4 add-on may be used to break the tie between the records.
(e.g., 6200 North Kings Highway Apt 278 Apt 207 Alexander VA 22408)
P# Better address exists The delivery address is matchable, but it is known by another (preferred) name. For example, in New York, NY, AVENUE OF THE AMERICAS is also known as 6TH AVE. An inquiry using a delivery address of 39 6th Avenue would be flagged with Footnote P#. If the given address is acceptable, then it will not be changed to the preferred version (e.g., 7202 Panam Expy S San Antonio TX 78224). If the given address is unacceptable, then it will be changed to the preferred version (e.g., 131 Stone Farm Lebanon NH 03766)
Q# Unique ZIP match The address has a "unique" ZIP Code
(e.g., 645 Swick Hill Street Charlotte NC 28263)
R# No match; EWS: Match soon The delivery address is not yet matchable, but the US Postal Service Early Warning System file indicates that a match will be available soon.
S# Unrecognized secondary address The secondary information (apartment, suite, etc.) was not recognized as part of the USPS data.
(e.g., 1409 Hueytown Rd Apt 1781 Bessemer AL 35023)
T# Multiple response due to magnet street syndrome The search resulted in a single response; however, the record matched was flagged as having magnet street syndrome, and the input street name components (pre-directional, primary street name, post-directional, and suffix) did not exactly match those of the record. A "magnet street" is one having a primary street name that is also a suffix or directional word, having either a post-directional or a suffix (i.e., 2220 PARK MEMPHIS TN logically matches to a ZIP+4 record 2200-2258 PARK AVE MEMPHIS TN 38114-6610), but the input address lacks the suffix "AVE" which is present on the ZIP+4 record. The primary street name "PARK" is a suffix word. The record has either a suffix or a post-directional present. Therefore, in accordance with CASS requirements, a ZIP+4 Code must not be returned. The multiple response return code is given since a "no match" would prevent the best candidate.
(e.g., 84 Green St Northampton MA)
U# Unofficial city name The city name in the submitted address is an alternate city name that is not accepted by the US Postal Service. The preferred city name is output in the city_name field.
(e.g., 150 Ken Visage Ln LaFayette GA)
V# Unverifiable city/state The city and state in the submitted address could not be verified as corresponding to the given 5-digit ZIP Code. This comment does not necessarily denote an error; however, Smarty recommends that the customer check the accuracy of the city and state in the submitted address.
(e.g., 7210 17 Avenue New York NY 11204
W# Invalid delivery address The USPS does not provide street delivery service for this ZIP Code. The USPS requires the use of a PO Box, General Delivery, or Postmaster for delivery within this ZIP Code.
X# Default Unique ZIP Code The address has a "unique" ZIP Code with a default ZIP+4 code
(e.g., 2020 S LAND OLAKES BLVD APT 9 FORT WORTH TX 76199
Y# Military match The address has a military or diplomatic ZIP Code.
(e.g., PSC 10 Box 1324 APO AE 09142)
Z# Matched with ZIPMOVE The ZIPMOVE product shows which ZIP+4 records have moved from one ZIP Code to another. If an input address matches a ZIP+4 record which the ZIPMOVE product indicates has moved, the search is performed again in the new ZIP Code.
(e.g., 26131 State Highway 37 Seligman MO 65745)

US ZIP Code output fields

All output fields correspond to the ZIP Code API Fields, but are arranged in a more useful order. Please note the ZIP Code API Fields output is only available via the Web Interface. It is not available via the Command-Line Interface.

Field name Definition
Inputs fields All fields from the corresponding input line.
(Blank field) This field intentionally left blank. No, really, it's just blank.
[sequence] Incrementing sequence number which refers to the input record number.
[summary] Value will be "match" unless the input was invalid. In that case, the values will corresponds to the values presented in the status field.
[reason] Corresponds to the reason field. (see table below example response).
[city] The name of the city
[default_city] A boolean value indicating whether or not the city name is the default name for the corresponding ZIP Code:
  • true — The city is the default name for the corresponding ZIP Code.
  • [blank] — The city is not the default name for the corresponding ZIP Code.
[state] The state name
[state_abbreviation] The official, two-letter state abbreviation
[zipcode] The 5-digit ZIP Code
[zipcode_type] The type of ZIP Code. Possible values:
  • S - Standard (regular ZIP Code)
  • M - Military (APO/FPO military ZIP)
  • P - P.O. Box (serves only post-office boxes)
  • U - Unique (belongs primarily to a firm)
[county_name] The name of the county
[county_fips] The county FIPS Code
[latitude] The approximate latitude geo-coordinate
[longitude] The approximate longitude geo-coordinate
[precision] The precision of the latitude/longitude geo-coordinate

International address output fields

All output fields correspond to the international street address API fields, but are arranged in a more useful order by the Bulk International Street Address Web Interface.

Field name Type Definition
Input fields several varchar(50) All fields from the corresponding input line.
(blank field) varchar(0) This field intentionally left blank. No, really, it's just blank.
[sequence] int Incrementing sequence number which refers to the input record number.
[verification_status] varchar(16) Indicates the verification status of the address.

None — Status not known, possibly because the address is invalid.

Partial — Parts of the address were matched (at the indicated precision level). Better input might result in a better match.

Ambiguous — The input address has more than one match within our dataset (at the indicated precision level).

Verified — The entire address was verified (at the indicated precision level).
[notes] varchar(250) Describes steps taken to verify and standardize the address and other information about it.
[address_precision] varchar(24) Indicates the precision of the address values.

None — Address not known, possibly because this address is invalid.

AdministrativeArea — Address is only verified down to the administrative area.
(e.g., typically a state or province)

Locality — Address is only verified down to the locality.
(e.g., typically a city or town)

Thoroughfare — Address is only verified down to the thoroughfare level.
(e.g., typically a street)

Premise — Address is verified down to the premise level.
(e.g., typically an individual property or building)

DeliveryPoint — Address is verified down to the delivery point.
(e.g., rooftop level)
[max_address_precision] varchar(16) Indicates the highest possible address_precision for the address.
[latitude] decimal(9,6) 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 measured in decimal degrees. It is the first value in an ordered pair of latitude, longitude. A negative number denotes a location south of the equator; a positive number is north. Combining lat/long values enables you to pinpoint addresses on a map.
[longitude] decimal(9,6) The vertical component used for geographic positioning, ***based on the WGS84 coordinate system***. It is the angle between 0° (the Prime Meridian) and ±180° (westward or eastward) measured in decimal degrees. 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.
[geocode_precision] varchar(18) Indicates the precision of the latitude and longitude values.

None — Coordinates not known, possibly because address is invalid.

AdministrativeArea — Coordinate is only accurate down to the administrative area.
(e.g., typically a state or province)

Locality — Coordinate is only accurate down to the locality level.
(e.g., typically a city or town)

Thoroughfare — Geocode is only accurate down to the thoroughfare level.
(e.g., typically a street)

Premise — Geocode is accurate down to the premise level.
(e.g., typically an individual property or building)

DeliveryPoint — Geocode is accurate down to the actual delivery point.
(e.g., rooftop level)
[max_geocode_precision] varchar(16) Indicates the highest possible geocode_precision for the address.
[address_format] varchar(128)

A template that shows where we positioned the different address components on line 1, line 2, etc. (The format changes from one country to another.)

Example:

building | premise thoroughfare | postal_code locality

Each "pipe" character (|) represents a line break. Following this guide, the numbered address fields would be composed accordingly:

  • Address 1: building
  • Address 2: premise thoroughfare
  • Address 3: postal_code locality

This value is always blank for US addresses. Here's some additional info on the composition of US addresses.

[organization] varchar(256) The name of the recipient, firm, or company at this address. The output will be identical to the input.
[address1]-[address-12] varchar(256) If verification_status = verified these fields will contain the correctly formatted address for mailing in the relevant country, split into individual address lines.

If verification_status ≠ verified the address fields may contain standardized address information or even the original input data.
[country_iso_3] varchar(3) The ISO 3166-1 alpha-3 country code. See our full listing for details.
[super_administrative_area] varchar(64) The largest administrative division within a country
(e.g., region in France)
[administrative_area] varchar(64) The most common administrative division within a country
(e.g., province in Canada)
[sub_administrative_area] varchar(64) The smallest administrative division within a country
(e.g., county in Germany)
[building] varchar(64) The descriptive name that identifies an individual location, if one exists
[dependent_locality] varchar(64) If there is additional information about the locality, it will be here.
(e.g., neighborhood in Turkey)
[dependent_locality_name] varchar(64) If the dependent_locality has a name, you'll find it here.
(E.g., the dependent_locality "Dong Cheng Qu" is named "Dong Cheng.")
[double_dependent_locality] varchar(64) If there is additional information about the dependent_locality, you'll find it here.
(e.g., village in the United Kingdom)
[locality] varchar(64) Within a country, this is the most common population center.
(e.g., city in Chile)
[postal_code] varchar(64) The complete postal code for the delivery point
(e.g., V6G1V9 in Canada)
[postal_code_short] varchar(64) Primary postal code information
(e.g., 90210 in the United States)
[postal_code_extra] varchar(64) Secondary postal code information
(e.g., 3425 in the United States)
[premise] varchar(64) Alphanumeric code pertaining to an individual location
[premise_extra] varchar(64) Extra information about the premise that is not necessarily authoritative but might still be useful
(E.g., in a French address, 25 bis rue Emile Zola, 91190 Gif Sur Yvette, France, the premise number could be followed by the word "bis" which would be considered premise_extra data.)
[premise_number] varchar(64) The alphanumeric component of the premise field
(E.g., if premise contains "Plot 7/7A" premise_number would contain "7/7A.")
[premise_type] varchar(64) The premise type component of the premise field
(E.g., if premise contains "Plot 7/7A" premise_type would contain "Plot.")
[thoroughfare] varchar(64) All thoroughfare components combined
[thoroughfare_predirection] varchar(64) The directional prefix component of the thoroughfare
(E.g., if thoroughfare contains "N Main St" thoroughfare_predirection would contain "N."
[thoroughfare_postdirection] varchar(64) The directional suffix component of the thoroughfare
(E.g., if thoroughfare contains "Main St N" thoroughfare_postdirection would contain "N.")
[thoroughfare_name] varchar(64) The name component of the thoroughfare
(E.g., if thoroughfare contains "Main St" thoroughfare_name would contain "Main.")
[thoroughfare_trailing_type] varchar(64) The trailing thoroughfare type component of the thoroughfare
(E.g., if thoroughfare contains "N Main St" thoroughfare_trailing_type would contain "St.")
[thoroughfare_type] varchar(64) The leading thoroughfare type component of the thoroughfare
(E.g., if thoroughfare contains "Rue De La Gare" thoroughfare_leading_type would contain "Rue.")
[dependent_thoroughfare] varchar(64) All of the dependent thoroughfare components combined
[dependent_thoroughfare_predirection] varchar(64) The directional prefix component of the dependent_thoroughfare
(E.g., if dependent_thoroughfare contains "N Main St" dependent_thoroughfare_predirection would contain "N.")
[dependent_thoroughfare_postdirection] varchar(64) The directional suffix component of the dependent_thoroughfare
(E.g., if dependent_thoroughfare contains "Main St N" dependent_thoroughfare_postdirection would contain "N.")
[dependent_thoroughfare_name] varchar(64) The name component of the dependent_thoroughfare
(E.g., if dependent_thoroughfare contains "N Main St" dependent_thoroughfare_name would contain "Main.")
[dependent_thoroughfare_trailing_type] varchar(64) The trailing dependent_thoroughfare type component of the dependent_thoroughfare
(E.g., if dependent_thoroughfare contains "N Main St" dependent_thoroughfare_trailing_type would contain "St.")
[dependent_thoroughfare_type] varchar(64) The leading thoroughfare type component of the dependent_thoroughfare field
(E.g., if dependent_thoroughfare contains "Rue De La Gare" dependent_thoroughfare_type would contain "Rue.")
[building_leading_type] varchar(64) The leading building type component of the building
(E.g., if building contains "Bloc C" building_leading_type would contain "Bloc.")
[building_name] varchar(64) The name component of the building
(E.g., if building contains "Westminster House" building_name would contain "Westminster.")
[building_trailing_type] varchar(64) The trailing building type component of the building
(E.g., if building contains "Westminster House" building_trailing_type would contain "House.")
[sub_building_type] varchar(64) The leading sub-building type of the sub_building
(E.g., if sub_building contains "Flat 1" sub_building_type would contain "Flat.")
[sub_building_number] varchar(64) The alphanumeric component of the sub_building
(E.g., if sub_building contains "Flat 1" sub_building_number would contain "1.")
[sub_building_name] varchar(64) The descriptive name component of the sub_building
(E.g., if sub_building contains "Basement Flat" sub_building_name would contain "Basement.")
[sub_building] varchar(64) All sub_building components combined
[post_box] varchar(64) All post_box Post Office Box components combined
[post_box_type] varchar(64) The type component of the post_box
(E.g., if post_box contains "PO Box 1234" post_box_type would contain "PO Box.")
[post_box_number] varchar(64) The alphanumeric component of the postbox
(E.g., if post_box contains "PO Box 1234" post_box_number would contain "1234.")

International postal code output fields

All output fields correspond to the Postal Code API Fields, but are arranged in a more useful order. Please note that the Postal Code API Fields output is only available via the Web Interface. It is not available via the Command-Line Interface.

Output fields

NOTE: Any returned fields that are not defined within this document should be considered experimental and may be changed or discontinued at any time without notice.

Field name Type Definition
[sequence] int Incrementing sequence number, which refers to the input record number.
[notes] varchar(250) Describes steps taken to verify and standardize the address and other information about it.
[super_administrative_area] varchar(64) The largest administrative division within a country (e.g., region in France)
[administrative_area] varchar(64) The most common administrative division within a country (e.g., province in Canada)
[sub_administrative_area] varchar(64) The smallest administrative division within a country (e.g., county in Germany)
[dependent_locality] varchar(64) If there is additional information about the locality, it will be here. (e.g., neighborhood in Turkey)
[dependent_locality_name] varchar(64) If the dependent_locality has a name, you'll find it here. (E.g., the dependent_locality "Dong Cheng Qu" is named "Dong Cheng.")
[double_dependent_locality] varchar(64) If there is additional information about the dependent_locality, you'll find it here. (e.g., village in the United Kingdom)
[locality] varchar(64) Within a country, this is the most common population center. (e.g., city in Chile)
[postal_code] varchar(64) The complete postal code for the delivery point (e.g., V6G1V9 in Canada)
[postal_code_extra] varchar(64) Secondary postal code information
[country_iso_3] varchar(3) The ISO 3166-1 alpha-3 country code. See our full listing for details.

Usage tips

Ready to get started?

Schedule Demo
42-day Free Trial