smartystreets-javascript-sdk

SMARTY DISCLAIMER: Subject to the terms of the associated license agreement, this software is freely available for your use. This software is FREE, AS IN PUPPIES, and is a gift. Enjoy your new responsibility. This means that while we may consider enhancement requests, we may or may not choose to entertain requests at our sole and absolute discretion.

Smarty JavaScript SDK

The official JavaScript/TypeScript SDK for accessing Smarty address validation APIs. Works in both Node.js and browser environments.

Installation

npm install smartystreets-javascript-sdk

Quick Start: US Street Address Validation

import SmartySDK from "smartystreets-javascript-sdk";

const credentials = new SmartySDK.core.StaticCredentials(
  process.env.SMARTY_AUTH_ID,
  process.env.SMARTY_AUTH_TOKEN,
);
const client = new SmartySDK.core.ClientBuilder(credentials).buildUsStreetApiClient();

const lookup = new SmartySDK.usStreet.Lookup();
lookup.street = "1600 Amphitheatre Parkway";
lookup.city = "Mountain View";
lookup.state = "CA";

const response = await client.send(lookup);
console.log(response.lookups[0].result);

Quick Start: US Autocomplete Pro

const client = new SmartySDK.core.ClientBuilder(credentials).buildUsAutocompleteProClient();

const lookup = new SmartySDK.usAutocompletePro.Lookup("4770 Lincoln");
lookup.maxResults = 10;
lookup.preferStates = ["IL"];

const response = await client.send(lookup);
console.log(response.result); // Array of address suggestions

Supported APIs

API	Module	Build Method	Example
US Street	usStreet	buildUsStreetApiClient()	example
US Zipcode	usZipcode	buildUsZipcodeClient()	example
US Autocomplete Pro	usAutocompletePro	buildUsAutocompleteProClient()	example
US Extract	usExtract	buildUsExtractClient()	example
US Enrichment	usEnrichment	buildUsEnrichmentClient()	example
US Reverse Geocoding	usReverseGeo	buildUsReverseGeoClient()	example
International Street	internationalStreet	buildInternationalStreetClient()	example
International Autocomplete	internationalAddressAutocomplete	buildInternationalAddressAutocompleteClient()	example
International Postal Code	internationalPostalCode	buildInternationalPostalCodeClient()	example

Authentication

Three credential types are available:

• StaticCredentials(authId, authToken) — Server-side authentication using auth-id and auth-token.
• SharedCredentials(key) — Client-side (browser) authentication using an embedded key. Does not support batch (POST) requests.
• BasicAuthCredentials(authId, authToken) — HTTP Basic Auth.

Common Patterns

Batch Requests

Send up to 100 lookups in a single request (not available with SharedCredentials):

const batch = new SmartySDK.core.Batch();
batch.add(lookup1);
batch.add(lookup2);

const response = await client.send(batch);

Error Handling

All API errors extend SmartyError:

import { SmartyError } from "smartystreets-javascript-sdk";

try {
  const response = await client.send(lookup);
} catch (err) {
  if (err instanceof SmartyError) {
    console.error("API error:", err.message);
  }
}

Retry and Timeout

const client = new SmartySDK.core.ClientBuilder(credentials)
  .withMaxRetries(10)
  .withMaxTimeout(30000)
  .buildUsStreetApiClient();

Proxy

const client = new SmartySDK.core.ClientBuilder(credentials)
  .withProxy("proxy.example.com", 8080, "https")
  .buildUsStreetApiClient();

Custom Headers

const client = new SmartySDK.core.ClientBuilder(credentials)
  .withCustomHeaders({ "X-Custom-Header": "value" })
  .buildUsStreetApiClient();

TypeScript

The SDK is written in TypeScript and ships with full type declarations — no @types/ package needed. All types are available as named exports:

import SmartySDK, { type MatchStrategy, type SmartyError } from "smartystreets-javascript-sdk";

const lookup = new SmartySDK.usStreet.Lookup();
lookup.street = "1600 Amphitheatre Parkway";
lookup.match = "enhanced" satisfies MatchStrategy;

JavaScript users benefit too — editors like VS Code automatically pick up the bundled type declarations, providing autocompletion and hover docs with no configuration.

See UPGRADING.md for details on migrating from the previous JavaScript-only release.

Documentation

Full API documentation is available at smarty.com/docs/sdk/javascript.

License

Apache 2.0