Documentation

 

SmartyStreets JavaScript SDK

If you want to access our APIs (other than the Download API) from a JavaScript application, the SmartyStreets JavaScript SDK can make it a lot easier. Our JavaScript SDK includes ready-made data structures and takes care of all the gritty, low-level HTTP intricacies for you.

Contents

  1. Requirements
  2. How Does It Work?
  3. How to Get It
    1. NPM
    2. Attach It as a Script in Your HTML
    3. Download the Source Code
  4. How to Use It
    1. Demo
    2. Initialize the SDK
    3. Verifying a Single US Street Address
    4. Verifying Multiple US Street Addresses
    5. Sending a Single Lookup to the US ZIP Code API
    6. Sending Multiple Lookups to the US ZIP Code API
    7. Sending the Beginning of an Address to the US Autocomplete API
    8. Sending Text to the US Extract API
    9. Verifying an International Street Address
  5. API Reference Material

Requirements

  1. Have a JavaScript project written for ES6 or higher (or lower; we're Babel-safe back to the stone age).
  2. Realize that you need an address verification component.
  3. Congratulate yourself on your wisdom and personal growth when you conclude that you don't want to build your own address verification component.
  4. Realize that SmartyStreets has already created an address verification component.
  5. Maybe take a drink of something fluid and fit for human consumption to quench your thirst.
  6. Congratulations! You are now ready to use the SmartyStreets JavaScript SDK.

How Does It Work?

The SmartyStreets JavaScript SDK is pre-composed of a set of shared core components that can be used across all of our APIs with bespoke lookup objects for your convenience. New up a lookup and a client, send the lookup with the client, and get back a promise. Easy as that.

How to Get It

NPM

Of course we're on NPM. Slurp it down like this:

npm install smartystreets-javascript-sdk

Once you've got it, you can initialize the SDK and you're ready to start moving and shaking.

Attach It as a Script in Your HTML

Maybe you need a single package from a handy CDN. That's cool too. We got u, bro. Throw one of these little snippet at the bottom of your <body> tag to pull it into your project. This little beauty even works with all those legacy IE clients you want to ditch so badly!

<script src="https://d79i1fxsrar4t.cloudfront.net/sdk/1.0.0/smartystreets-sdk-1.0.0.js"></script>
<script src="https://d79i1fxsrar4t.cloudfront.net/sdk/1.0.0/smartystreets-sdk-1.0.0.min.js"></script>

Download the Source Code

You can download the source code from the SmartyStreets JavaScript SDK repository on Github.

Use the source, Luke!

How to Use It

Demo

Here are a few pieces of example code to show how to use our JavaScript library/SDK.

Initialize the SmartyStreets JavaScript SDK

With NPM using CommonJS:

const SmartyStreetsSDK = require("smartystreets-javascript-sdk");

With NPM using ES6:

import * as SmartyStreetsSDK from "smartystreets-javascript-sdk";

The Browserified package comes in ready to roll from our CDN.

<script src="https://d79i1fxsrar4t.cloudfront.net/sdk/1.0.0/smartystreets-sdk-1.0.0.min.js"></script>

Verifying a Single US Street Address

The following code assumes you have already initialized the sdk.

const SmartyStreetsCore = SmartyStreetsSDK.core;
const Lookup = SmartyStreetsSDK.usStreet.Lookup;

// Add your credentials to a credentials object.
let authId = /* your auth id here */;
let authToken = /* your auth token here */;
let credentials = new SmartyStreetsCore.StaticCredentials(authId, authToken);

// Build a client.
let clientBuilder = new SmartyStreetsCore.ClientBuilder(credentials);
let client = clientBuilder.buildUsStreetApiClient();

// Create and populate a lookup.
let lookup1 = new Lookup();
lookup1.street = "1600 Pennsylvania Ave NW";
lookup1.zipCode = "20500";

// Send the lookup from the client and handle the response.
client.send(lookup1)
	.then(handleSuccess)
	.catch(handleError);

function handleSuccess(response) {
	// Log the lookup results to the console.
	response.lookups.map(lookup => console.log(lookup.result));
}

function handleError(response) {
	console.log(response);
}

Verifying Multiple US Street Addresses

The following code assumes you have already initialized the sdk.

const SmartyStreetsCore = SmartyStreetsSDK.core;
const Lookup = SmartyStreetsSDK.usStreet.Lookup;

// Add your credentials to a credentials object.
let authId = /* your auth id here */;
let authToken = /* your auth token here */;
let credentials = new SmartyStreetsCore.StaticCredentials(authId, authToken);

// Build a client.
let clientBuilder = new SmartyStreetsCore.ClientBuilder(credentials);
let client = clientBuilder.buildUsStreetApiClient();

// Create and populate lookups.
let lookup1 = new Lookup();
lookup1.street = "1 Infinite Loop";
lookup1.zipCode = "95014";

let lookup2 = new Lookup();
lookup2.street = "1600 Amphitheater Pkwy";
lookup2.city = "Mountainview";
lookup2.state = "CA";

// Create and fill a batch.
let batch = new SmartyStreetsCore.Batch();
batch.add(lookup1);
batch.add(lookup2);

// Send the lookup from the client and handle the response.
client.send(batch)
	.then(handleSuccess)
	.catch(handleError);

function handleSuccess(response) {
	// Log the lookup results to the console.
	response.lookups.map(lookup => console.log(lookup.result));
}

function handleError(response) {
	console.log(response);
}

Sending a Single Lookup to the US ZIP Code API

The following code assumes you have already initialized the sdk.

const SmartyStreetsCore = SmartyStreetsSDK.core;
const Lookup = SmartyStreetsSDK.usZipcode.Lookup;

// Add your credentials to a credentials object.
let authId = /* your auth id here */;
let authToken = /* your auth token here */;
let credentials = new SmartyStreetsCore.StaticCredentials(authId, authToken);

// Build a client.
let clientBuilder = new SmartyStreetsCore.ClientBuilder(credentials);
let client = clientBuilder.buildUsZipcodeClient();

// Create and populate a lookup.
let lookup1 = new Lookup();
lookup1.zipCode = "49786";

// Send the lookup from the client and handle the response.
client.send(lookup1)
	.then(viewResults)
	.catch(handleError);

function viewResults(response) {
	// Log the lookup city results to the console.
	response.lookups.map(lookup => lookup.result.map(candidate => {
		candidate.cities.map(city => console.log(city.city));
	}));
}

function handleError(response) {
	console.log(response);
}

Sending Multiple Lookups to the US ZIP Code API

The following code assumes you have already initialized the sdk.

const SmartyStreetsCore = SmartyStreetsSDK.core;
const Lookup = SmartyStreetsSDK.usZipcode.Lookup;

// Add your credentials to a credentials object.
let authId = /* your auth id here */;
let authToken = /* your auth token here */;
let credentials = new SmartyStreetsCore.StaticCredentials(authId, authToken);

// Build a client.
let clientBuilder = new SmartyStreetsCore.ClientBuilder(credentials);
let client = clientBuilder.buildUsZipcodeClient();

// Create and populate lookups.
let lookup1 = new Lookup();
lookup1.zipCode = "49786";

let lookup2 = new Lookup();
lookup2.city = "Phoenix";
lookup2.state = "AZ";

// Create and fill a batch.
let batch = new SmartyStreetsCore.Batch();
batch.add(lookup1);
batch.add(lookup2);

// Send the lookup from the client and handle the response.
client.send(batch)
	.then(viewResults)
	.catch(handleError);

function viewResults(response) {
	// Log the lookup city results to the console.
	response.lookups.map(lookup => lookup.result.map(candidate => {
		candidate.cities.map(city => console.log(city.city));
	}));
}

function handleError(response) {
	console.log(response);
}

Sending the Beginning of an Address to the US Autocomplete API

The following code assumes you have already initialized the sdk.

const SmartyStreetsCore = SmartyStreetsSDK.core;
const Lookup = SmartyStreetsSDK.usAutocomplete.Lookup;

// Add your credentials to a credentials object.
let websiteKey = /* your auth id here */;
let credentials = new SmartyStreetsCore.SharedCredentials(websiteKey)

let clientBuilder = new SmartyStreetsCore.ClientBuilder(credentials);
let client = clientBuilder.buildUsAutocompleteClient();
let lookup = new Lookup("1080 Pasito");

client.send(lookup)
	.then(logSuggestions)
	.catch(handleError);

function logSuggestions(response) {
	console.log(response.result);
}

function handleError(response) {
	console.log(response);
}

Sending Text to the US Extract API

The following code assumes you have already initialized the sdk.

const SmartyStreetsCore = SmartyStreetsSDK.core;
const Lookup = SmartyStreetsSDK.usExtract.Lookup;

// Add your credentials to a credentials object.
let authId = /* your auth id here */;
let authToken = /* your auth token here */;
let credentials = new SmartyStreetsCore.StaticCredentials(authId, authToken);

// Build a client.
let clientBuilder = new SmartyStreetsCore.ClientBuilder(credentials);
let client = clientBuilder.buildUsExtractClient();

// Create and populate a lookup.
let lookup = new Lookup("If you work at 1600 Pennsylvania Ave NW, Washington DC you're gonna have a hard time.");

// Send the lookup from the client and handle the response.
client.send(lookup)
	.then(logResult)
	.catch(handleError);

function logResult(response) {
	console.log(response.result);
}

function handleError(response) {
	console.log(response);
}

Verifying an International Street Address

The following code assumes you have already initialized the sdk.

const SmartyStreetsCore = SmartyStreetsSDK.core;
const Lookup = SmartyStreetsSDK.internationalStreet.Lookup;

// Add your credentials to a credentials object.
let authId = /* your auth id here */;
let authToken = /* your auth token here */;
let credentials = new SmartyStreetsCore.StaticCredentials(authId, authToken);

// Build a client.
let clientBuilder = new SmartyStreetsCore.ClientBuilder(credentials);
let client = clientBuilder.buildInternationalStreetClient();

// Create and populate a lookup.
let lookup1 = new Lookup();
lookup1.country = "Brazil";
lookup1.freeform = "Rua Padre Antonio D'Angelo 121 Casa Verde, Sao Paulo";

// Send the lookup from the client and handle the response.
client.send(lookup1)
	.then(displayResult)
	.catch(handleError);

function displayResult(response) {
	console.log(response.result.map(result => console.log(result.components)));
}

function handleError(response) {
	console.log(response);
}
This site uses cookies for analytics, personalized content, and ads. By continuing to browse this site, you agree to this use.