Topics
SDK Reference Cloud API Documentation Local API Reference SmartyList Open Source Methodology Account / Billing Our Data SecurityThis page describes how to download, install, and run a local instance of the International Street API.
Throughout this document we use the following consistently formatted terms:
The product with the capabilities you wish to host on your local network.
The first of two packages you will download and extract. Contains the necessary data files used by the running program.
The second of two packages you will download and extract. Contains the main program and other binary resources.
international-street-apiThe program that you will execute. Found in the international-street-api package.
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.
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 this API requires a system administrator or software engineer who has experience with the Linux operating system and its accompanying shell environment. We assume you have familiarity with (or at least a willingness to grapple with) the following Linux utilities and concepts:
mkdir (to create directories)cp (to copy files)tar (to extract compressed archives)curl (to download packages)sudo (to perform certain tasks with root-level privileges)ldconfig (to refresh the linker's shared library cache)$LD_LIBRARY_PATH environment variable (set to extend the linker's shared library cache)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).
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:
Running a local instance of the International Street API requires two packages that are available for download via the SmartyStreets Download API:
Includes all address data accessed by the us-street-api program in order to serve client requests. Here's an example command you might use to download the package:
curl -L "https://download.api.smartystreets.com/international-street-api/data/latest.tar.gz?auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN" -o international-street-data.tar.gzIncludes the compiled program (redundantly named us-street-api) and several shared libraries. Here's an example command you might use to download this package:
curl -L "https://download.api.smartystreets.com/international-street-api/linux-amd64/latest.tar.gz?auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN" -o international-street-api.tar.gzSee the sample script below for more details.
Both downloaded packages are gzipped archives and must be extracted (using the tar command) before they can be used.
mkdir ./data
tar xvf international-street-data.tar.gz -C ./data
tar xvf international-street-api.tar.gz
Having extracted the contents of both packages you are now ready to register the included shared libraries with the linker. There are three different ways to do this. You only need choose one of the following options!
Recommended Approach: Set the LD_LIBRARY_PATH environment variable to the extracted lib folder.
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`pwd`/libThe above command appends the extracted lib folder to any pre-existing value in the LD_LIBRARY_PATH environment variable. Care should be taken when downloading updated versions of the package on the same machine that you don't unnecessarily append this value again. Managing the environment variables on your machine is your responsibility. Notwithstanding this slight "complexity" we encourage this approach because it doesn't require any changes to existing directories on the machine. But, if this approach isn't working, try one of the following methods.
With root privileges (ie. sudo), copy the contents of the extracted lib folder to a folder included in the shared library cache. Commonly configured locations include /usr/lib and /usr/local/lib.
sudo cp ./lib/* /usr/libSome distributions (like CentOS) do not automatically acknowledge new arrivals in the shared library cache locations and so the cache must be rebuilt by running the ldconfig utility with root privileges:
sudo ldconfig -vAdd the extracted lib folder path to /etc/ld.so.conf (on it's own line) and invoke ldconfig as above. This has the effect of including the lib folder in the shared library cache.
./international-street-api -version./international-street-api -help./international-street-api -data "/path/to/extracted/data/package" -us-street-api="http://HOSTNAME:PORT"./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 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.toolIf 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"
}
}
]SmartyStreets publishes regular updates to both the international-street-api and international-street-data packages. New releases are announced in our open-source Changelog repository.
Applications are compiled with a dependency on libc. This means that any container images created must have the libc binary available. In production environments containers based upon officially maintained releases of Debian, Ubuntu, Red Hat, and Fedora base images will work. For containers based upon Alpine Linux, you will need to install the libc dependency. While Alpine Linux is typically used to drastically reduce the size of the base image layers, please remember that the host machine caches these layers so that the cost of downloading the base image is only paid once. The latest official Ubuntu base images are around 25 MB in size.
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 `curl` commands
# below with your own auth-id and auth-token, or with environment
# variables that contain your own auth-id and auth-token values.
# Download the us-street-api data package from the download API:
curl -L "https://download.api.smartystreets.com/international-street-api/linux-amd64/latest.tar.gz?auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN" -o international-street-api.tar.gz
# Download the international-street-api package from the download API:
curl -L "https://download.api.smartystreets.com/international-street-api/data/latest.tar.gz?auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN" -o international-street-data.tar.gz
# Extract the data package:
mkdir ./data
tar xvf international-street-data.tar.gz -C ./data
# Extract the api package:
tar xvf international-street-api.tar.gz -C .
# Extract the data package:
mkdir ./data; tar xvf international-street-data.tar.gz -C ./data
# Run the international-street-api:
./international-street-api