Local International Street Address API

This page describes how to download, install, and run a local instance of the International Street API.

Glossary
API Documentation
Prerequisites
Minimum System Requirements
Downloading the Packages
Installation Procedures
Managing the Local API Process
Connecting to the Local API Process
Updates
Automation

Glossary

Throughout this document we use the following consistently formatted terms:

International Street API
The product with the capabilities you wish to host on your local network.
international-street-data
The first of two packages you will download and extract. Contains the necessary data files used by the running program.
international-street-api
The second of two packages you will download and extract. Contains the main program and other binary resources.
international-street-api
The program that you will execute. Found in the international-street-api package.

API Documentation

A local installation of the International Street API performs identically to the cloud version hosted by SmartyStreets. Please refer to the documentation for details about input and output fields.

The main difference between the local and cloud installations lies in the parts of the URL used by clients to establish a connection. (scheme://hostname:port) This will be explained in more detail later.

Prerequisites

Access to local International Street API packages and resources is currently restricted to customers with an Enterprise account. Downloading the packages also requires a valid secret key pair for authentication.

The process of downloading, installing, and managing a local instance of the International Street API requires a system administrator or software engineer who has experience with the Linux operating system and its accompanying shell environment.

The International Street API sends HTTP requests to the US Street API in order to verify input addresses from the USA. By default, the International Street API targets a local US Street API instance. If configured, the International Street API may target the cloud US Street API (hosted by SmartyStreets) instead (more details below).

Minimum System Requirements

The International Street API is designed to run on a Linux server that can be reached by any clients you intend to call the service. Responsibility for network and server maintainence (as well as the performance of all other operations detailed in this document) rests with your organization.

The server provisioned to run the local International Street API binaries should match the following criteria:

1+ gigabytes of RAM
Multiple CPU cores
A relatively recent version of the Linux kernel (basically something that can run compiled Go programs). Anything later than v2.6.32 should function without issues.

Downloading the Packages

Running a local instance of the International Street API requires two packages that are available for download via the SmartyStreets Download API:

international-street-data
Includes all address data accessed by the international-street-api program in order to serve client requests.
international-street-api
Includes the compiled program (redundantly named international-street-api) and several shared libraries to be installed in /usr/lib.

See the sample script below for more details.

Installation Procedures

Both downloaded packages are gzipped archives and must be extracted (using the tar command) before they can be used. Examples of how to use the tar command to extract the downloaded archives can be found below.

Upon extracting the international-street-api package, the contents of the lib folder contained therein should be copied to /usr/lib. By default, the international-street-api program expects the extracted contents of the data package to be found at ./data.

Managing the Local API Process

To display the version of the program:
```
./international-street-api -version
```
To display command-line usage and all options:
```
./international-street-api -help
```

To run the program targeting a local instance of the US Street API:

./international-street-api -data "/path/to/extracted/data/package" -us-street-api="http://HOSTNAME:PORT"

To run the program targeting the cloud US Street API (hosted by SmartyStreets):

./international-street-api -data "/path/to/extracted/data/package" -auth-id="YOUR_AUTH_ID" -auth-token="YOUR_AUTH_TOKEN"

NOTE: Running the international-street-api program starts a process that is designed to run continuously until killed.

Connecting to the Local API Process

Connecting to the local international-street-api process using TLS is currently not supported. This means that the URL scheme will be http instead of https. We recommend using a private network or a proxy to establish encrypted connections if desired. Also, please note that the hostname for the local installation will not be international-street.api.smartystreets.com. The examples below use localhost. Finally, the default port for the local installation is 8080 rather than 80.

Once the international-street-api program is running, run the following command from another terminal window to send an actual HTTP request to the process:

curl -v "https://international-street.api.smartystreets.com/verify?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE&address1=Rua+Padre+Antonio+D%27Angelo+121&address2=Casa+Verde&locality=Sao+Paulo&administrative_area=SP&postal_code=02516-040&country=Brazil" | python -m json.tool

If everything is functioning correctly then the output should closely resemble the following JSON object:

[
    {
        "address1":"Rua Padre Antônio D'ângelo 121",
        "address2":"Casa Verde",
        "address3":"São Paulo - SP",
        "address4":"02516-040",
        "components":{
            "administrative_area":"SP",
            "dependent_locality":"Casa Verde",
            "country_iso_3":"BRA",
            "locality":"São Paulo",
            "postal_code":"02516-040",
            "postal_code_short":"02516-040",
            "premise":"121",
            "premise_number":"121",
            "thoroughfare":"Rua Padre Antônio D'ângelo",
            "thoroughfare_name":"Padre Antonio D'angelo",
            "thoroughfare_type":"Rua"
        },
        "metadata":{

        },
        "analysis":{
            "verification_status":"Verified",
            "address_precision":"Premise",
            "max_address_precision":"DeliveryPoint"
        }
    }
]

Updates

SmartyStreets publishes regular updates to both the international-street-api and international-street-data packages. We recommend that you download and install these updates on at least a monthly basis.

Automation

What follows is a script that you may use to download, install, and run a local instance of the International Street API. It's Bash. Use it as a starting point for putting in place your own update processes. Your mileage may vary. You're welcome.

#!/bin/bash

# Pro Tip:
#   Replace the placeholder auth values in the `wget` commands
#   below with your own auth-id and auth-token.

# Download the international-street-api package from the download API:
wget -O international-street-api.tar.gz "https://download.api.smartystreets.com/international-street-api/linux-amd64/latest.tar.gz?auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN"

# Download the international-street-api data package from the download API:
wget -O international-street-data.tar.gz "https://download.api.smartystreets.com/international-street-api/data/latest.tar.gz?auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN"

# Extract the api package:
tar xvf international-street-api.tar.gz -C .

# Install the shared libraries:
sudo cp ./lib/* /usr/lib

# Extract the data package:
mkdir ./data; tar xvf international-street-data.tar.gz -C ./data

# Run the international-street-api:
./international-street-api

Documentation

Local International Street Address API

Contents