SmartyList: Command-Line Interface

For most customers that need to process a list of US addresses our Web Interface does a great job. For those with larger lists (50,000+ records) we have a Command-Line Interface.

Contents

  1. Download
  2. Installation
  3. Getting Started
  4. Updates
  5. Reference and Usage
  6. Other stuff at the bottom

Download

You can download the SmartyList Command-Line Interface for the following platforms:

You're welcome!

Installation

After downloading one of the above packages, extract the contents of the archive. You'll see the following listing of files:

  • smartylist This is the compiled command-line tool you will invoke. BTW, those using windows will notice a .exe extension on this file.
  • sample-input.csv This is a simple address list for your reference.
  • sample-output.csv This is an example of the output produced as a result of processing the sample-input.csv file above.
  • change-log.txt A log of recent changes made by the software developers.
  • DO-NOT-README.txt I dare you to leave this file alone. Actually, just delete it. It's trash.

Copy or move smartylist (smartylist.exe on windows) to wherever is convenient. On a linux machine you might put it in /usr/local/bin or somewhere else that is already in your $PATH. If you don't have a preference, you can leave the files in your Downloads folder or just plop it on your desktop.

Getting Started

It's so easy, we hardly need a tutorial, but we've got one coming soon anyway.

Updates (Pay attention, this is important!)

Try this command in the terminal/prompt:

$ smartylist -version

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

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

2.1.10

The version number you see is the semantic version number of your copy of the application. Each of the three dot-delimited numbers is significant: major.minor.patch

The first of the three numbers in the version output is the "major" version number. If we need to release a new major version, any copies of the old version will be automatically disabled, requiring you to download and install the latest version before processing any additional lists. (Read that last sentance again...slowly...just to make sure it sinks in.) This is not something we will do often and certainly not ever without extensive consideration.

The second of the three numbers in the version output is the "minor" version number. Incrementing this number means we have released new functionality that is still backwards-compatible. It would behoove you to download and install the latest version. Until you do, a message will be sent to stderr and a non-zero exit status will be returned by the application as a signal that something is amiss. The application will continue to process your lists.

This third number refers to patches and bug fixes--corrections to existing behavior. If this number doesn't match, it would be a good idea (probably worth a promotion!) for you to download and install the latest version so you have the most current and correct software. In this situation, a message will be sent to stdout as a signal that something is amiss. The application will continue to process your lists.

Reference

Command-Line Flags

The following are command-line flags (complete with contrived values and explanations) available to you when invoking the smartylist tool at the terminal.

-auth-id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
(Required) The smartylist tool issues requests to our US Street Address API which requires you to authenticate via an auth-id and auth-token. This flag allows you to specify your auth-id. There is one case in which the flag is not required, which is for Enterprise customers that send requests to a local installation of the US Street Address API.
-auth-token="xxxxxxxxxxxxxxxx"
(Required) This flag allows you to specify the auth-token for authentication in HTTP API requests. There is one case in which the flag is not required, which is for Enterprise customers that send requests to a local installation of the US Street Address API.
-base-url=https://us-street.api.smartystreets.com
(Optional) The base URL to use for verification requests. In all but very few cases (like if you are pointing to a local installation of the API) the default value is appropriate.
-proxy=http://address-of-your-proxy
(Optional) The address of a proxy to use for verification requests. This flag is not necessary, unless your organization restricts outbound network traffic to a proxy.
-input="/path/to/the/input/file.txt"
(Required) This tells smartylist where your input file is. Hopefully you've already formatted your file as delimited rows (csv or tab-delimited) and provided helpful column names in the first row. (Names like street, city, state, and zipcode would be good.)
-log="/path/to/the/log/file.txt"
(Optional) This tells smartylist where to put the log file containing diagnostic information about processing the input file. The support team will probably ask for this file when diagnosing any issues you may have. If not provided, we will place the log file alongside the input file with a name something like: "/path/to/the/input/file-log_datetime.txt"
-output="/path/to/the/output/file.txt"
(Optional) If provided, this is where smartylist will place the output file containing the results of processing your input file. If not provided, we will place the output alongside the input with a name something like: "/path/to/the/input/file-output.txt". The file will contain these output fields.
-silent
(Optional) When this flag is set to true, smartylist bypasses all prompts and suppresses all non-error output. Every party has a pooper.
-version
(Optional) When this flag is provided (no value needed), smartylist simply shows the version of the application and exits.

Example Usage

Output help and exit:

$ smartylist -help

Output version and exit:

$ smartylist -version

Process the sample list:

$ smartylist -input="sample-input.csv" -auth-id="blahblah" -auth-token="blahblahblah"

Process your actual list:

$ smartylist -input="stuff.csv" -auth-id="1a2b3c4d" -auth-token="z0y9x8"

Keep in mind that using command-line flags to specify your auth-token will make that value visible to anyone that can view running processes on the machine (ie. ps -aux on linux systems). Alternatively, specify environment variables to store both your auth-id and auth-token values, and supply the names of those variables (not their values) as the -auth-id and -auth-token command-line flags.

						$ export SMARTYLIST_AUTH_ID="your-auth-id-here"
$ export SMARTYLIST_AUTH_TOKEN="your-auth-token-here"
$ smartylist -input="stuff.csv" -auth-id="SMARTYLIST_AUTH_ID" -auth-token="SMARTYLIST_AUTH_TOKEN"
						
					

Process your list using your organization's proxy (if one has been configured):

$ smartylist -proxy=http://address-of-the-proxy -input="stuff.csv" -auth-id="1a2b3c4d" -auth-token="z0y9x8"

Process your list using your organization's local installation of the US Street API (if one has been provisioned):

$ smartylist -base-url=http://localhost:8080 -input="stuff.csv"

Interesting stuff relagated to the bottom of the page

Logging

This tool aims to produce friendly output (like a progress bar) during processing. But there's a lot going on "under the hood" that doesn't show up. Rather than litter your screen with all that stuff a log file will be produced (in your working directory) every time you process a list. The name of that log file follows this pattern:

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

In the rare scenario in which a problem occurs that prevents a list from being processed, check that file for the gory details of what happened. When contacting support with questions they will probably ask for that file to aid in the debugging process.

Blank Lines

Your list doesn't have blank lines does it? Good. Because if it did you might have to worry about line numbers being slightly off in the output, which could make copying the output into the input spreadsheet (like if you're using Excel) a bit tricky. We recommend the following rules:

  1. Make sure your file has no blank lines (except at the end).
  2. If you find any blank lines, refer to the previous rule.
  3. If you somehow escaped reading the last two rules and still have blank lines in your file, make sure you have an 'id' column and that each record has a unique value in that column.

By "blank lines" we mean lines that have no data except a carriage return character (and/or line feed character). Lines that have delimiters (commas or tabs) but no data between them are not considered blank in terms of the implications outlined in this section.


Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff