Local US Extract API

This page describes how to download, install, and run a local instance of the US Extract 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
Docker and Containers
Automation

Glossary

Throughout this document we use the following consistently formatted terms:

US Extract API
The product with the capabilities you wish to host on your local network.
us-extract-api
The package you will download and extract. Contains the main program and other binary resources.
us-extract-api

The program that you will execute. Found in the us-extract-api package.

API Documentation

A local installation of the US Extract API performs identically to the cloud version hosted by Smarty. 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 US Extract 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 US Extract API requires a system administrator or software engineer who has experience with the Linux operating system and its accompanying shell environment.

The US Extract API sends HTTP requests to the US Street API in order to verify the address candidates it extracts from input data. By default, the US Extract API targets the cloud US Street API (hosted by Smarty). If configured, the US Extract API may utilize a local US Street API instance instead (more details below).

Minimum System Requirements

The US Extract 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 US Extract API binaries should match or exceed the following criteria:

.1 gigabytes of disk space / 2 gigabytes of RAM
4 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 US Extract API requires the following package that is available for download via the Smarty Download API:

us-extract-api
Includes the compiled program (redundantly named us-extract-api).

See the sample script below for more details.

Installation Procedures

The downloaded package is a gzipped archive and must be extracted (using the tar command) before it can be used. Examples of how to use the tar command to extract the downloaded archives can be found below.

Managing the Local API Process

To display command-line usage and all options:
```
./us-extract-api -help
```
To run the program, pointing to the cloud US Street API for verification of extracted addresses (which requires authentication):
```
./us-extract-api -auth-id="YOUR_AUTH_ID" -auth-token="YOUR_AUTH_TOKEN"
```
To run the program, pointing to a local US Street API for verification of extracted addresses (requiring no authentication):
```
./us-extract-api -us-street-api="http://HOSTNAME:PORT/street-address"
```

NOTE: Running the us-extract-api program starts a process that is designed to run continuously until killed. The version number is displayed when executed.

Connecting to the Local API Process

Connecting to the local us-extract-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 us-extract.api.smarty.com. The examples below use localhost. Finally, the default port for the local installation is 8080 rather than 80.

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

curl "http://localhost:8080/" -H 'Content-Type: text/plain; charset=utf-8' --data-binary 'Meet me at 5732 Lincoln Drive Minneapolis MN next Wednesday evening.' | python -m json.tool

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

{
	"addresses": [
		{
			"api_output": [
				{
					"analysis": {
						"active": "Y",
						"dpv_cmra": "N",
						"dpv_footnotes": "AABB",
						"dpv_match_code": "Y",
						"dpv_vacant": "N",
						"footnotes": "N#"
					},
					"candidate_index": 0,
					"components": {
						"city_name": "Minneapolis",
						"delivery_point": "32",
						"delivery_point_check_digit": "7",
						"plus4_code": "1608",
						"primary_number": "5732",
						"state_abbreviation": "MN",
						"street_name": "Lincoln",
						"street_suffix": "Dr",
						"zipcode": "55436"
					},
					"delivery_line_1": "5732 Lincoln Dr",
					"delivery_point_barcode": "554361608327",
					"input_index": 0,
					"last_line": "Minneapolis MN 55436-1608",
					"metadata": {
						"carrier_route": "C009",
						"congressional_district": "03",
						"county_fips": "27053",
						"county_name": "Hennepin",
						"dst": true,
						"elot_sequence": "0035",
						"elot_sort": "A",
						"latitude": 44.90127,
						"longitude": -93.40045,
						"precision": "Zip9",
						"rdi": "Commercial",
						"record_type": "S",
						"time_zone": "Central",
						"utc_offset": -6,
						"zip_type": "Standard"
					}
				}
			],
			"end": 44,
			"line": 1,
			"start": 11,
			"text": "5732 Lincoln Drive Minneapolis MN",
			"verified": true
		}
	],
	"meta": {
		"address_count": 1,
		"bytes": 68,
		"character_count": 68,
		"lines": 1,
		"unicode": false,
		"verified_count": 1
	}
}

Updates

Smarty publishes regular updates to the us-extract-api package. New releases are announced in our open-source Changelog repository.

Docker and Containers

Since version 3.12, the application binary is statically compiled. You no longer need libc or pcre to be available as dynamic modules. If the lookup verify endpoint for the option -us-street-api is using a TLS (https) endpoint (the default if not set), then an environment providing proper certificates in /etc/ssl/certs/ca-certificates.crt is required. 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 ca-certificates dependency, if it is not already installed. For example, via apk update && apk add ca-certificates.

Automation

What follows is a script that you may use to download, install, and run a local instance of the US Extract 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` command
#   below with your own auth-id and auth-token.

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

# Extract the api package:
tar xvf us-extract-api.tar.gz -C .

# Run the us-extract-api:
./us-extract-api

Integrations & plugins

Learning hub