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.
You can download the SmartyList Command-Line Interface for the following platforms:
After downloading one of the above packages, extract the contents of the archive. You'll see the following listing of files:
smartylistThis is the compiled command-line tool you will invoke. BTW, those using windows will notice a
.exeextension on this file.
sample-input.csvThis is a simple address list for your reference.
sample-output.csvThis is an example of the output produced as a result of processing the sample-input.csv file above.
change-log.txtA log of recent changes made by the software developers.
DO-NOT-README.txtI dare you to leave this file alone. Actually, just delete it. It's trash.
Copy or move
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.
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
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:
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.
The following are command-line flags (complete with contrived values and explanations) available to you when invoking the
smartylist tool at the terminal.
smartylisttool issues requests to our US Street Address API which requires you to authenticate via an
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.
(Required) This flag allows you to specify the
auth-tokenfor 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.
- (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.
- (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.
(Required) This tells
smartylistwhere 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.)
(Optional) This tells
smartylistwhere 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:
(Optional) If provided, this is where
smartylistwill 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.
(Optional) When this flag is set to
smartylistbypasses all prompts and suppresses all non-error output. Every party has a pooper.
(Optional) When this flag is provided (no value needed),
smartylistsimply shows the version of the application and exits.
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-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
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:
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.
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:
- Make sure your file has no blank lines (except at the end).
- If you find any blank lines, refer to the previous rule.
- 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.