Not sure which product you need? Let the wizard guide you
Smarty

Smarty JavaScript SDK

The Smarty JavaScript SDK enables developers to integrate address intelligence capabilities into JavaScript and TypeScript applications with minimal boilerplate code. The SDK provides unified access to APIs for address verification, geocoding, autocomplete, and data enrichment. It works in both Node.js and browser environments.

Contents

  1. Upgrading from JavaScript to TypeScript
  2. Installation
  3. Authentication
  4. Create an API client
  5. Create and send lookups
  6. Examine results
  7. More examples

Upgrading from JavaScript to TypeScript

The SDK has been rewritten from JavaScript to TypeScript. This is a non-breaking change — the published npm package still ships the same compiled JavaScript in both CommonJS and ESM formats, so existing JavaScript code continues to work without modification.

What changed

  • The SDK source is now TypeScript
  • The package now includes bundled type declarations (.d.ts files) in dist/types/

*Note: No classes, methods, or namespaces were renamed or removed

What JavaScript users get for free

Even without TypeScript in your project, you now get automatic benefits in editors like VS Code and WebStorm:

  • Autocompletion — property names, method signatures, and constructor parameters are suggested as you type
  • Hover documentation — hover over any SDK class or method to see its type signature
  • Inline error detection — your editor can flag typos in property names or incorrect argument types

These features come from the bundled .d.ts files and require no configuration.

What TypeScript users get

Full type declarations ship with the package — no @types/ package or DefinitelyTyped needed. Exported types are available as named imports: 

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

// Core interfaces
import type { Request, Response, Sender, Sleeper, Signer } from "smartystreets-javascript-sdk";

// API-specific types
import type { OutputFormat, CountySource } from "smartystreets-javascript-sdk";
import type { CoordinateLicense, MatchInfo } from "smartystreets-javascript-sdk";
import type { Geolocation } from "smartystreets-javascript-sdk";
import type { Language, Geocode } from "smartystreets-javascript-sdk";

Do I need to change anything?

Question Answer
Do I need TypeScript installed? No. The package contains compiled JavaScript. Types are optional metadata.
Did any method signatures change? No. The public API is identical.
Do I need to update my imports? No. All import patterns (import, require) work exactly as before.
Are the examples still JavaScript? Yes. The examples/ directory uses plain .mjs files.
What Node.js versions are supported? The same versions as before are supported. The compiled output targets ES2015.

Installation

Install the SDK from npm:

npm install smartystreets-javascript-sdk

Import the SDK into your application:

// ESM
import SmartySDK from "smartystreets-javascript-sdk";

// CommonJS
const SmartySDK = require("smartystreets-javascript-sdk");

The SDK is written in TypeScript and ships with bundled type declarations. TypeScript users get full type support with no additional @types/ package required.

Authentication

Smarty offers two kinds of credentials depending on the deployment context

  • Server-side (backend, CLI, batch jobs): Auth ID + Auth Token (Secret Key pair) using StaticCredentials or BasicAuthCredentials
  • Client-side (browser, front-end, public UI): Embedded Key using SharedCredentials (restricted by domain referrer)

Access all keys through your Smarty account under:
Account → API Keys.

We recommend storing your credentials in environment variables for security:

export SMARTY_AUTH_ID="your-auth-id"
export SMARTY_AUTH_TOKEN="your-auth-token"
export SMARTY_AUTH_EMBEDDED_KEY="your-embedded-key"

For details on authentication and embedded vs. secret keys, see our authentication documentation.

Create an API client

The SDK uses a ClientBuilder to configure and create API-specific clients.

Server-side client

Example for US street API using StaticCredentials:

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();

Or using BasicAuthCredentials:

const credentials = new SmartySDK.core.BasicAuthCredentials(
	process.env.SMARTY_AUTH_ID,
	process.env.SMARTY_AUTH_TOKEN,
);

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

Browser/Frontend client

Example for US Autocomplete Pro API using SharedCredentials:

const credentials = new SmartySDK.core.SharedCredentials(process.env.SMARTY_EMBEDDED_KEY);

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

Note: SharedCredentials does not support batch (POST) requests. Use BasicAuthCredentials for batch operations.

Available API clients

API Builder method
US street buildUsStreetApiClient()
US ZIP Code buildUsZipcodeClient()
US autocomplete pro buildUsAutocompleteProClient()
US extract buildUsExtractClient()
US enrichment buildUsEnrichmentClient()
US reverse geocoding buildUsReverseGeoClient()
International street buildInternationalStreetClient()
International autocomplete buildInternationalAddressAutocompleteClient()
International postal code buildInternationalPostalCodeClient()

Client configuration options

const client = new SmartySDK.core.ClientBuilder(credentials)
	.withMaxRetries(10)
	.withMaxTimeout(30000)
	.withBaseUrl("https://your-self-hosted-url.example.com")
	.withProxy("proxy.example.com", 8080, "https")
	.withCustomHeaders({ "X-Custom-Header": "value" })
	.buildUsStreetApiClient();

Create and send a lookup

Create lookups for addresses requiring validation. Each API has its own Lookup class that holds both input parameters and results.

Single lookup

Example for US street API:

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

const response = await client.send(lookup);

Batch lookup

Send up to 100 lookups in a single request using Batch:

const batch = new SmartySDK.core.Batch();

const lookup1 = new SmartySDK.usStreet.Lookup();
lookup1.street = "330 N 100 W";
lookup1.city = "Provo";
lookup1.state = "Utah";
lookup1.zipCode = "84601";

const lookup2 = new SmartySDK.usStreet.Lookup();
lookup2.street = "1600 Amphitheatre Parkway Mountain View, CA 94043";

batch.add(lookup1);
batch.add(lookup2);

const response = await client.send(batch);

Autocomplete lookup

Autocomplete lookups accept a search string directly:

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

const response = await client.send(lookup);

Examine results

Review API results after sending lookups. Results are attached to each lookup.

US street API results

const response = await client.send(batch);

for (const lookup of response.lookups) {
	console.log("Results for:", lookup.street);

	for (const candidate of lookup.result) {
		console.log("  Delivery line:", candidate.deliveryLine1);
		console.log("  Last line:", candidate.lastLine);
		console.log("  Input ID:", candidate.inputId);
	}
}

US autocomplete pro results

const response = await client.send(lookup);

for (const suggestion of response.result) {
	console.log(suggestion);
}

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);
	}
}

More examples

Complete working examples are available in the GitHub repository:

All JavaScript SDK examples are located in the examples/ directory of the official repository.

Ready to get started?

Schedule Demo
42-day Free Trial