Smarty Java SDK

A Java client for Smarty's address verification, geocoding, autocomplete, and data enrichment APIs.

The Smarty Java SDK lets you integrate address intelligence into your Java applications with minimal boilerplate. Whether you're validating millions of addresses, enriching them with precise geocodes, or powering an autocomplete form, the SDK gives you a clear, idiomatic way to call every Smarty API.

Contents

1. Installation
2. Authentication
3. Create an API client
4. Create and send lookups
5. Examine results
6. Quick start
7. Batch lookups
8. More examples

Installation

The easiest way to get started is with Apache Maven. Add the following to the <dependencies> section of your project's pom.xml:

<dependency>
	<groupId>com.smartystreets.api</groupId>
	<artifactId>smartystreets-java-sdk</artifactId>
	<version>5.5.0</version>
</dependency>

Important: Check the Smarty Java SDK repository on GitHub for the latest version number.

The SDK requires Java 11 or higher.

Note: The examples in this guide require SDK version 5.0.0 or higher.

Authentication

Smarty offers two kinds of credentials depending on where your code runs:

1. Server-side (backend, CLI, batch jobs): Use Auth ID + Auth Token (a Secret Key pair).
2. Client-side (browser, front-end, public UI): Use Auth Web + Auth Referer (a Website Key pair restricted by domain).

You can find all keys in 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_WEB="your-auth-web"
export SMARTY_AUTH_REFERER="your-auth-referer"

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

Create an API client

The SDK uses ClientBuilder to configure and create API clients. Each API has its own build method.

Server-side client

Here’s an example for US Street API:

import com.smartystreets.api.BasicAuthCredentials;
import com.smartystreets.api.ClientBuilder;
import com.smartystreets.api.us_street.*;

BasicAuthCredentials credentials = new BasicAuthCredentials(
	System.getenv("SMARTY_AUTH_ID"),
	System.getenv("SMARTY_AUTH_TOKEN")
);

Client client = new ClientBuilder(credentials).buildUsStreetApiClient();

Client-side (browser/mobile) client

Here’s an example for International Autocomplete API:

import com.smartystreets.api.SharedCredentials;
import com.smartystreets.api.ClientBuilder;
import com.smartystreets.api.international_autocomplete.*;

SharedCredentials credentials = new SharedCredentials(
	System.getenv("SMARTY_AUTH_WEB"),
	System.getenv("SMARTY_AUTH_REFERER")
);

// Note: the method name is missing the "o" in "Autocomplete"
Client client = new ClientBuilder(credentials).buildInternationalAutcompleteApiClient();

All API clients implement Closeable. Use try-with-resources to ensure the underlying HTTP client shuts down cleanly:

try (Client client = new ClientBuilder(credentials).buildUsStreetApiClient()) {
	// use client
}

You can find a full list of builder options in ClientBuilder.java.

Create and send lookups

Create a lookup for the address you want to validate. Here's an example for the US Street Address API:

Lookup lookup = new Lookup();
lookup.setStreet("1600 Amphitheatre Pkwy");
lookup.setCity("Mountain View");
lookup.setState("CA");
lookup.setZipCode("94043");
lookup.setMaxCandidates(3);

client.send(lookup);

The send method throws SmartyException, IOException, and InterruptedException. Be sure to handle or declare these exceptions in your code.

Examine results

After sending a lookup, the results are stored on the lookup itself:

List<Candidate> results = lookup.getResult();

if (results.isEmpty()) {
	System.out.println("No candidates. This means the address is not valid.");
	return;
}

Candidate firstCandidate = results.get(0);
System.out.println("ZIP Code:  " + firstCandidate.getComponents().getZipCode());
System.out.println("County:    " + firstCandidate.getMetadata().getCountyName());
System.out.println("Latitude:  " + firstCandidate.getMetadata().getLatitude());
System.out.println("Longitude: " + firstCandidate.getMetadata().getLongitude());

Quick start

Here's a complete, runnable example that ties together authentication, client creation, sending a lookup, and examining results:

package com.example;

import com.smartystreets.api.BasicAuthCredentials;
import com.smartystreets.api.ClientBuilder;
import com.smartystreets.api.us_street.*;

import java.util.List;

public class App {
	public static void main(String[] args) throws Exception {
		BasicAuthCredentials credentials = new BasicAuthCredentials(
			System.getenv("SMARTY_AUTH_ID"),
			System.getenv("SMARTY_AUTH_TOKEN")
		);

		try (Client client = new ClientBuilder(credentials).buildUsStreetApiClient()) {
			Lookup lookup = new Lookup();
			lookup.setStreet("1600 Amphitheatre Pkwy");
			lookup.setCity("Mountain View");
			lookup.setState("CA");
			lookup.setZipCode("94043");
			lookup.setMaxCandidates(3);

			client.send(lookup);

			List<Candidate> results = lookup.getResult();

			if (results.isEmpty()) {
				System.out.println("No candidates. This means the address is not valid.");
				return;
			}

			Candidate firstCandidate = results.get(0);
			System.out.println("ZIP Code:  " + firstCandidate.getComponents().getZipCode());
			System.out.println("County:    " + firstCandidate.getMetadata().getCountyName());
			System.out.println("Latitude:  " + firstCandidate.getMetadata().getLatitude());
			System.out.println("Longitude: " + firstCandidate.getMetadata().getLongitude());
		}
	}
}

Batch lookups

You can send up to 100 lookups at once using a Batch. Single lookups are sent as GET requests; batches of 2 or more are sent as POST requests.

Batch batch = new Batch();

Lookup address1 = new Lookup("1600 Amphitheatre Pkwy, Mountain View, CA 94043");
Lookup address2 = new Lookup("1 Rosedale, Baltimore, Maryland");

batch.add(address1);
batch.add(address2);

client.send(batch);

for (int i = 0; i < batch.size(); i++) {
	List<Candidate> candidates = batch.getAllLookups().get(i).getResult();
	for (Candidate candidate : candidates) {
		System.out.println(candidate.getDeliveryLine1());
		System.out.println(candidate.getLastLine());
	}
}

More examples

• US Street API
• US Street API (Batch)
• US Autocomplete Pro API
• US Enrichment API
• US Extract API
• US Reverse Geocoding API
• US ZIP Code API
• International Street Address API
• International Autocomplete API
• International Postal Code API

All Java SDK examples can be found on our GitHub here.